Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h1>What are meta-annotations ?</h1><p>Meta-annotations, also known as annotation aliases are annotations that are replaced at compile time by other annotations (one meta-annotation is an alias for one or more annotations). This feature was added in Groovy 2.1.0. It can be used to dramatically reduce the verbosity of code involving multiple annotations.</p><h2>Writing a meta-annotation</h2><p>Let's start with a simple example. Imagine you have the <em>@Service</em> and <em>@Transactional</em> annotations and that you want to annotate a class with both:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>@Service
@Transactional
class MyTransactionalService {}</pre></td></tr></table><p>What meta-annotations allows you is to replace the two annotations by a single one. First of all, you need to define your alias:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>import groovy.transform.AnnotationCollector
 
@Service
@Transactional
@AnnotationCollector
public @interface TransactionalService {
}</pre></td></tr></table><p>We are defining a <em>@TransactionalService</em> annotation here, a meta-annotation, that <em>collects</em> the <em>@Service</em> and <em>@Transactional</em> annotations. This is done by annotating the interface with <em>@AnnotationCollector</em>.</p><h2>Understanding the behaviour</h2><p>Before going further, we have to understand how meta-annotations work. First of all, Groovy supports both precompiled and source form meta-annotations. This means that your meta-annotation <em>may</em> be precompiled, or you can have it in the same source tree as the one you are currently compiling. Second, this is a Groovy feature only. There is no chance for you to annotate a Java class with a meta-annotation and hope it will do the same as in Groovy. Likewise, you cannot write a meta-annotation in Java: both the meta-annotation definition <strong>and</strong> usage have to be Groovy code.</p><p>When the Groovy compiler encounters a class annotated with a meta-annotation, it <strong>replaces</strong> it with the collected annotations. That is, in our previous example, that it will replace <em>@TransactionalService</em> with <em>@Transactional</em> and <em>@Service</em>. This happens during the semantic analysis phase, that is to say exactly when AST transformations are collected. </p><p>More than replacing the alias, a meta-annotation is capable of processing the collected annotations, including processing arguments. The default processor includes interesting behaviour with regards to annotation parameters.</p><h2>Meta-annotation parameters</h2><p>Here, we will imagine two annotations, each of them taking one argument:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>@Timeout(after=100)
@Dangerous(type="explosive")</pre></td></tr></table><p>And that you want create a meta-annotation named <em>@Explosive</em>:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>@Timeout(after=100)
@Dangerous(type="explosive")
@AnnotationCollector
public @interface Explosive {}</pre></td></tr></table><p>Then, by default, when the annotations are replaced, they will get the values as they were defined in the alias. More interesting, the alias supports overriding specific values:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>@Explosive(after=0)
class Bomb {}</pre></td></tr></table><p>Here, the value provided as a parameter to <em>@Explosive</em> overrides the one defined in the annotation.</p><h3>Name clashes</h3><p>What happens if two annotations define the same parameter name? The default processor will copy the annotation value to all annotations that accept this parameter. Take this example (you can run it in a Groovy console, for example):</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>import java.lang.annotation.Retention
import java.lang.annotation.RetentionPolicy
@Retention(RetentionPolicy.RUNTIME)
public @interface Foo {
   String value()
}
@Retention(RetentionPolicy.RUNTIME)
public @interface Bar {
    String value()
}
@Foo
@Bar
@groovy.transform.AnnotationCollector
public @interface FooBar {}
@Foo('a')
@Bar('b')
class Bob {}
println Bob.class.getAnnotation(Foo)
println Bob.class.getAnnotation(Bar)
@FooBar('a')
class Joe {}
println Joe.class.getAnnotation(Foo)
println Joe.class.getAnnotation(Bar)</pre></td></tr></table><p>this would print:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>@Foo(value=a)
@Bar(value=b)
@Foo(value=a)
@Bar(value=a)</pre></td></tr></table><p>which means that in the second case, the annotation value was copied in both annotations. But what happens if, for example, the annotation type for Foo is String, and the one for Bar is an integer? The current behaviour of the annotation is to fail at compile time. Does it mean that there's nothing more you can do? No. Meta-annotations support a special feature called a processor, that will help you deal with such problems.</p><h3>Custom annotation processors</h3><p>A custom annotation processor will let you choose how to explode a meta-annotation. The behaviour of the meta-annotation is, in this case, totally up to you. You can do whatever you want. Let's take a look, for example, on how <em>@CompileDynamic</em> is implemented in Groovy 2.1.0. <em>@CompileDynamic</em> is a meta-annotation that replaces itself with <em>@CompileStatic(TypeCheckingMode.SKIP)</em>. The problem is that the default meta annotation processor doesn't support enums and we need to produce that enum. So, instead of defining <em>@CompileDynamic</em> like this:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>@CompileStatic(TypeCheckingMode.SKIP)
@AnnotationCollector
public @interface CompileDynamic {}</pre></td></tr></table><p>We will define it like this:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>@AnnotationCollector(processor = "org.codehaus.groovy.transform.CompileDynamicProcessor")
public @interface CompileDynamic {
}</pre></td></tr></table><p>The first thing you may notice is that our interface is no longer annotated with <em>@CompileStatic</em>. The reason for this is that we rely on the extra <em>processor</em> parameter, that references a class which will <strong>generate</strong> the annotation. And here is what this class looks like:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>public class CompileDynamicProcessor extends AnnotationCollectorTransform {
    private static final ClassNode COMPILESTATIC_NODE = ClassHelper.make(CompileStatic.class);
    private static final ClassNode TYPECHECKINGMODE_NODE = ClassHelper.make(TypeCheckingMode.class);
    public List&lt;AnnotationNode> visit(AnnotationNode collector, AnnotationNode aliasAnnotationUsage, AnnotatedNode aliasAnnotated, SourceUnit source) {
        AnnotationNode node = new AnnotationNode(COMPILESTATIC_NODE);
        node.addMember("value", new PropertyExpression(new ClassExpression(TYPECHECKINGMODE_NODE), "SKIP"));
        return Collections.singletonList(node);
    }
}

</pre></td></tr></table><p>Our custom processor extends the default one and overrides the <em>public List&lt;AnnotationNode&gt; visit(AnnotationNode collector, AnnotationNode aliasAnnotationUsage, AnnotatedNode aliasAnnotated, SourceUnit source)</em> method. This method is responsible for returning the list of annotations that will be added to the AST tree in place of the alias. The body of this method, hence, is only there to generate the appropriate <em>AnnotationNode</em>, nothing more! Of course, you can rely on the superclass to deal with arguments, for example.</p><p> </p>