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.

<h3>Introduction</h3>

<p>Java 5 and above supports the use of annotations to include metadata within programs. Groovy 1.1 and above also supports such annotations.</p>

<p>Annotations are used to provide information to tools and libraries. They allow a declarative style of providing metadata information and allow it to be stored directly in the source code. Such information would need to otherwise be provided using non-declarative means or using external files. We won't discuss guidelines here for when it is appropriate to use annotations, just give you a quick run down of annotations in Groovy.</p>

<p>Annotations are defined much like Java class files but use the <code>@interface</code> keyword. As an example, here is how you could define a <code>FeatureRequest</code> Annotation in Java:</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>
// Java
public @interface FeatureRequest {
    String key();
    String summary();
    String assignee() default "[unassigned]";
    String status() default "[open]";
    String targetVersion() default "[unassigned]";
}
</pre></td></tr></table>

<p>This annotation represents the kind of information you may have in an issue tracking tool. You could use this annotation in a Groovy file as follows:</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>
@FeatureRequest(
    key="GROOVY-9999",
    summary="Support Graphical Annotations",
    assignee="Pete",
    status="Open",
    targetVersion="5.0"
)
class SomeClassWhereFeatureCouldBeUsed {
   // ...
}
</pre></td></tr></table>

<p>Now if you had tools or libraries which understood this annotation, you could process this source file (or the resulting compiled class file) and perform operations based on this metadata.</p>

<p>As well as defining your own annotations, there are many existing tools, libraries and frameworks that make use of annotations. See some of the examples referred to at the end of this page. As just one example, here is how you could use annotations with Hibernate or JPA:</p>

@Entity
@Table(name="staff")
class Staff implements Serializable {
    @Id @GeneratedValue
    Long id
    String firstname
    String lastname
    String position
}
</pre></td></tr></table>

<h3>Example</h3>

<p>As another example, consider this <a href="http://xstream.codehaus.org/">XStream</a> example. XStream is a library for serializing Java (and Groovy) objects to XML (and back again if you want). Here is an example of how you could use it without annotations:</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>
// require(groupId:'com.thoughtworks.xstream', artifactId:'xstream', version:'1.3')
import com.thoughtworks.xstream.*

class Staff {
    String firstname, lastname, position
}

def xstream = new XStream()
xstream.classLoader = getClass().classLoader
def john = new Staff(firstname:'John',
                     lastname:'Connor',
                     position:'Resistance Leader')

println xstream.toXML(john)
</pre></td></tr></table>

<p>This results in the following output:</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;Staff>
  &lt;firstname>John&lt;/firstname>
  &lt;lastname>Connor&lt;/lastname>
  &lt;position>Resistance Leader&lt;/position>
&lt;/Staff>
</pre></td></tr></table>

<p>Just as an aside, not related to annotations, here is how you could write the XML to a file:</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>
new File("john.xml").withOutputStream { out ->
    xstream.toXML(john, out)
}
</pre></td></tr></table>

<p>And how you would read it back in:</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>
// require(groupId:'com.thoughtworks.xstream', artifactId:'xstream', version:'1.3')
// require(groupId:'xpp3', artifactId:'xpp3_min', version:'1.1.4c')
import com.thoughtworks.xstream.*

class Staff {
    String firstname, lastname, position
}

def xstream = new XStream()
def john
// now read back in
new File("john.xml").withInputStream { ins ->
    john = xstream.fromXML(ins)
}

println john.dump()
// => &lt;Staff@12d96f2 firstname=John lastname=Connor position=Resistance Leader>
</pre></td></tr></table>

<p>Now, on to the annotations ...</p>

<p>XStream also allows you to have more control over the produced XML (in case you don't like its defaults). This can be done through API calls or with annotations. Here is how we can annotate our Groovy class with XStream annotations to alter the resulting XML:</p>

@XStreamAlias("person")
class Associate {
    @XStreamAsAttribute
    @XStreamAlias('first-name')
    String firstname

@XStreamAlias('surname')
    String lastname

@XStreamOmitField
    String position
}

msg = new Associate(firstname:'Sarah',
                    lastname:'Connor',
                    position:'Protector')
Annotations.configureAliases(stream, Associate)
println stream.toXML(msg)
</pre></td></tr></table>

<p>When run, this produces the following output:</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;person first-name="Sarah">
  &lt;surname>Connor&lt;/surname>
&lt;/person>
</pre></td></tr></table>

<h3>Differences to Java</h3>

<p>Annotations may contain lists. When using such annotations with Groovy, remember to use the square bracket list notation supported by Groovy rather than the braces used by Java, i.e.:</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>
// Java
@ManagedOperationParameters({
    @ManagedOperationParameter(name="x", description="The first number"),
    @ManagedOperationParameter(name="y", description="The second number")})
</pre></td></tr></table>

<p>Would become:</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>
// Groovy
@ManagedOperationParameters([
    @ManagedOperationParameter(name="x", description="The first number"),
    @ManagedOperationParameter(name="y", description="The second number")])
</pre></td></tr></table>

<h3>More Examples</h3>

<p>Annotations are also used in examples contained within the following pages:</p>

<ul>
	<li><a class="confluence-link" href="/display/GROOVY/Using+JUnit+4+with+Groovy" data-linked-resource-id="75345" data-linked-resource-type="page" data-linked-resource-default-alias="Using JUnit 4 with Groovy" data-base-url="http://docs.codehaus.org">Using JUnit 4 with Groovy</a></li>
	<li><a class="confluence-link" href="/display/GROOVY/Using+TestNG+with+Groovy" data-linked-resource-id="77161" data-linked-resource-type="page" data-linked-resource-default-alias="Using TestNG with Groovy" data-base-url="http://docs.codehaus.org">Using TestNG with Groovy</a></li>
	<li><a class="confluence-link" href="/display/GROOVY/Using+Instinct+with+Groovy" data-linked-resource-id="76908" data-linked-resource-type="page" data-linked-resource-default-alias="Using Instinct with Groovy" data-base-url="http://docs.codehaus.org">Using Instinct with Groovy</a></li>
	<li><a class="confluence-link" href="/display/GROOVY/Using+Popper+with+Groovy" data-linked-resource-id="80123" data-linked-resource-type="page" data-linked-resource-default-alias="Using Popper with Groovy" data-base-url="http://docs.codehaus.org">Using Popper with Groovy</a></li>
	<li><a class="confluence-link" href="/display/GROOVY/Singleton+Pattern" data-linked-resource-id="78454" data-linked-resource-type="page" data-linked-resource-default-alias="Singleton Pattern" data-base-url="http://docs.codehaus.org">Singleton Pattern</a></li>
	<li><a class="confluence-link" href="/display/GROOVY/Using+Spring+Factories+with+Groovy" data-linked-resource-id="79513" data-linked-resource-type="page" data-linked-resource-default-alias="Using Spring Factories with Groovy" data-base-url="http://docs.codehaus.org">Using Spring Factories with Groovy</a></li>
	<li><a class="confluence-link" href="/display/GROOVY/Groovy+and+JMX" data-linked-resource-id="79147" data-linked-resource-type="page" data-linked-resource-default-alias="Groovy and JMX" data-base-url="http://docs.codehaus.org">Groovy and JMX</a></li>
</ul>