Groovy 2.1: The @DelegatesTo Annotationhttp://docs.codehaus.org/display/GROOVY/Eclipse+Plugin#EclipsePlugin-DevelopmentBuildsGroovy 2.1 comes with a neat feature for DSL and Groovy library others: the @DelegateTo  annotation.
The Delegate and The ClosureGroovy supports the concept of closures . One closure feature is to being able to modifiy the closure code delegation mechanism. Once a closure is defined, its delegate object can be changed by setting the delegate property: In the code sample above, we change the delegate to an instance of Greeter. When executing the code in groovConsole , it prints Ups, obviously we did forget one little thing: the resolve strategy. By setting the resolve strategy of a single groovy.lang.Closure instance, we can chose between the following types:
- OWNER_ONLY: delegate method calls to the owner of the closure (e.g. the instance creating the closure instance)
- DELEGATE_ONLY: delegate method calls to the delegate of the closure
- OWNER_FIRST: delegate to the owner first, then the delegate
- DELEGATE_FIRST: delegate to the delegate first, then the owner
- SELF_ONLY: method calls are resolved against the closure instance only
What's the deal?Modifying the closure resolving strategy is a powerful technuique for DSL and Groovy library authors. For example, take a look at GContracts , a Design by Contract extension for Groovy, that uses closure annotations to specify contracts on methods and classes: Another example is definitely Gradle , the Groovy-based build automation framework: When working with one of these libraries in IntelliJ or Eclipse, one shortage becomes immediately apparent: whenever a custom delegate object is set, IntelliJ or Eclipse do not provide code completion for closure code, except the IDE of choice comes with specific framework support.
@DelegatesTo comes into playAs of version 2.1, Groovy provides a way for DSL, library and framework authors to hint IDEs in the right direction: the @DelegatesTo annotation. In its simplest application, @DelegatesTo has only a single default argument of type java.lang.Class. Back to our previous example, we have to introduce an indirection as @DelegatesTo can only be applied on parameters: We can even provide more meta-data by specifying the strategy attribute:
The DelegatesTo.Target Annotation@DelegatesTo has one last additional meta-data that can be applied on method paramters: the @DelegatesTo.Target annotation. Whenever an actual parameter will be set as the closure's delegate object, the Target can be used to document this circumstance: For the special case of having multiple parameters of the same type, there is a target annotation element type that allows for specifying unique String ids. Note, in the example above we did not specify a class for the closure parameter. This can be omitted since the type will be inferred from the greeter parameter.
IDE SupportBesides supporting IDEs the @DelegatesTo information is evaluated by @TypeChecked and @CompileStatic. As of writing, neither IntelliJ nor the Groovy Eclipse plugin comes with support for @DelegatesTo, but it is expected to become supported in the near future:
ConclusionDSL, library and Groovy framework authors should definitely consider adding @DelegatesTo to their method meta-data. Besides the benefit of better IDE support (think of code completion), additional meta-data is utilized by Groovy 2.0's @TypeChecked and @CompileStatic to catch even more typing errors. It's a small step for third party authors, but a big step for Groovy IDE support. Update As announced today (2013-02-07), @DelegatesTo is supported by the Groovy-Eclipse plugin. Snapshot builds are available at http://docs.codehaus.org/display/GROOVY/Eclipse+Plugin#EclipsePlugin-DevelopmentBuilds