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>When you are writing your annotation in JavaDoc, you need to post-compile your classes in order to parse the sources, retrieve the JavaDoc annotations, process and validate the annotations and finally put them into the bytecode as regular Java 5 RuntimeVisible annotations. </p>

<p>This is done by using the backport175 compiler, <code>AnnotationC</code>.</p>

<h3>AnnotationC compiler</h3>

<p>You can run <code>AnnotationC</code> either from the command line or using the <a class="confluence-link" href="/display/175/Ant+task" data-linked-resource-id="18668" data-linked-resource-type="page" data-linked-resource-default-alias="Ant task" data-base-url="http://docs.codehaus.org">Ant task</a>.</p>

<p>You invoke the compiler like this:</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>
java [options...] org.codehaus.backport175.compiler.AnnotationC
     [-verbose]
     -src &lt;path to src dir>
     -classes &lt;path to classes dir>
     [-dest &lt;path to destination dir>]
     [-config &lt;optional property file(s) for annotations>]
</pre></td></tr></table>

<p>The last option <code>-config &lt;property file(s)&gt;</code> points to the (or several files separated by classpath separator - <code>;</code> or <code>:</code> depending on you OS) property file which defines annotation aliases (or imports) by mapping the names to the fully qualified class names of the annotation interface.</p>

<p>Note that if you are using the <code>-dest</code> option, the anonymous inner classes will not be copied to the destination directory, since the anonymous classes are not taken into account by the annotation compiler. In such a case it is recommended to add the following (if using <em>Ant</em>) just after the call to <code>AnnotationC</code> when the <code>-dest</code> option is used: (adapt according to the directories you are using)</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;copy todir="classes/annotated" overwrite="false"> 
    &lt;fileset dir="classes/regular"/> 
&lt;/copy>
</pre></td></tr></table>

<h3>Annotation definition file</h3>

<p>Since the annotations are written in JavaDoc, there is no way of doing imports of the annotations interfaces. </p>

<p>This leaves you two options:</p>

<ul>
	<li>either you use the fully qualified name of the annotation interface when writing the the annotations, e.g.:
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="java" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6amF2YX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
/**
 * @org.codehaus.backport175.annotation.OneWay
 */
public void method() {
    ...
}
</pre></td></tr></table>
which can be a bit verbose and cumbersome in the long run.</li>
</ul>

<ul>
	<li>or you define <em>aliases</em> (shortcuts/abbreviations), for the annotations and map these to the fully qualified class names for the annotation interfaces. This is done using the <code>annotations.properties</code> file.<br />
Example:
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="java" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6amF2YX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
OneWay = org.codehaus.backport175.annotation.OneWay
TwoWay = org.codehaus.backport175.annotation.TwoWay
</pre></td></tr></table>
If we now feed this property file to the compiler we are able to write the annotations like this instead:
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="java" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6amF2YX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
/**
 * @OneWay
 */
public void method() {
    ...
}
</pre></td></tr></table></li>
</ul>

<p>You can have more than one annotation.properties file (see the compiler section) and those are not at all required at runtime.</p>

<h3>Rules for annotation naming consistency</h3>

<p>It is important to remember that if you are using an alias through a propery file, the annotation name is still the fully qualified name of the interface class for the annotation when using the <code>Annotations.getAnnotation</code> API.</p>

<p>If you decide to use an alias, then you have to use this alias in the whole sources. It is not possible to use from time to time in the source an alias or the fully qualified name, since backport175 has to ensure an element cannot be annotated twice with the same annotation, as per JSR-175.<br />
If you decide to use the fully qualified name, the same rule applies, it needs to stay consistent.</p>

<p>If the annotation is a nested class like <code>Target.OneWay</code> below, you can use a <code>$</code> in the name (as when using java.lang.reflect.* API) or a <code>.</code> which can be more readable.<br />
Once again, this choice has to be consistent thus one or the other has to be used accross the code base but not both:</p>
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="java" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6amF2YX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
package demo;
/**
 * @demo.Target$OneWay
 */
public class Target {
  public static interface OneWay {}
}
</pre></td></tr></table>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="java" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6amF2YX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
package demo;
/**
 * @demo.Target.OneWay
 */
public class Target {
  public static interface OneWay {}
}
</pre></td></tr></table>

<h3>Annotation default values</h3>

<p>JSR-175 annotation support default values. This is supported in backport175 with the <code>org.codehaus.backport175.DefaultValue</code> special annotation, that only accepts one single anonymous value whose type must match the one of the annotation element which has this default value :</p>
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="java" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6amF2YX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
package demo;
/**
 * @demo.Target.OneWayDefaulted
 */
public class TargetUsingDefaultValue {

public static interface OneWayDefaulted {
    /**
     * @org.codehaus.backport175.DefaultValue ("default message")
     */
    String message();
  }
}

/**
 * @demo.Target.OneWayDefaulted (message="this is not the default message !")
 */
public class TargetNOTUsingDefaultValue {

...
}
</pre></td></tr></table>