Professional Open Source™

Annotations

© JBoss, Inc. 2003, 2004. 07/17/04 1

 What are Annotations?
Professional Open Source™

 An annotation, is a special form of syntactic metadata that can be

added to Java source code.

 Classes, methods, variables, parameters and packages may be

annotated

 Unlike Javadoc tags, Java annotations are reflective in that they are
embedded in class files generated by the compiler and may be
retained by the Java VM to be made retrievable at run-time.

© JBoss, Inc. 2003, 2004. 2

 Professional Open Source™

 Annotations are a metaprogramming facility introduced J2SE 5.0.

They allow us to mark code with defined tags.

 Some developers think that the Java compiler understands the tag
and work accordingly. This is not right.

 The tags actually have no meaning to the Java compiler or runtime

itself. There are tools that can interpret these tags. For instance:
IDEs, testing tools, profiling tools, and code-generation tools
understands these tags.

© JBoss, Inc. 2003, 2004. 3

 Why use annotations?
Professional Open Source™

 Metadata is beneficial for documentation, compiler checking, and

code analysis.

 Metadata is used by the compiler to perform some basic compile-time

checking.

 For example there is a override annotation that lets you specify that a
method overrides another method from a superclass. At this, the Java
compiler will ensure that the behavior you indicate in your metadata
actually happens at a code level as well.

 Another great feature of using annotation is code analysis. A good

tool like XDOCLET can manage all of these dependencies, ensuring
that classes that have no code-level connection, but do have a logic-
level tie-in, stay in sync. In this case, metadata is really useful.

© JBoss, Inc. 2003, 2004. 4

 Categories of annotations
Professional Open Source™

 There are three categories of annotations:

 Marker annotations
 There annotations have no variables. These are identified by name,
with no additional data supplied. For example:
 Code:
 @SingleValueAnnotation

© JBoss, Inc. 2003, 2004. 5

 Professional Open Source™

 Single-value annotations
 These are similar to markers, but also provide a single piece of data.
You can only provide a single bit of data with these. For example:
 Code:
 @SingleValueAnnotation(”my data”)

© JBoss, Inc. 2003, 2004. 6

 Professional Open Source™

 Full annotations
 There have multiple data members. Annotations of this type won’t
look quite so much like a normal Java method:

 Example :

 @FullAnnotation(var1="data value 1", var2="data value 2",

var3="data value 3")

 In addition to supplying values to annotations through the default

syntax, you can use name-value pairs when you need to pass in
more than one value.

© JBoss, Inc. 2003, 2004. 7

 Annotation Basics
Professional Open Source™

 There are two things you need to consider with annotations. One is
the “annotation” itself; another is the “annotation type.”

 An annotation is the meta-tag that you will use in your code to give it
some life.

 Annotation type is used for defining an annotation. You will use it

when you want to create your own custom annotation. The type is the
actual construct used, and the annotation is the specific usage of that
type.

© JBoss, Inc. 2003, 2004. 8

 Professional Open Source™

 Example to Define an Annotation (Annotation type)

public @interface MyAnnotation {
String doSomething();
}

 Example to Annotate Your Code (Annotation)

MyAnnotation (doSomething="What to do")
public void mymethod() { .... }

© JBoss, Inc. 2003, 2004. 9

 Annotation Types
Professional Open Source™

 Marker

 Single-Element

 Full-value or multi-value

© JBoss, Inc. 2003, 2004. 10

 Professional Open Source™

 Marker: Marker type annotations have no elements, except the

annotation name itself.

 Example: public @interface MyAnnotation { }

 Usage:
 @MyAnnotation
 public void mymethod() { .... }

© JBoss, Inc. 2003, 2004. 11

 Professional Open Source™

 Single-Element: Single-element, or single-value type, annotations

provide a single piece of data only. This can be represented with a
data=value pair or, simply with the value (a shortcut syntax) only,
within parenthesis.

 Example: public @interface MyAnnotation {

 String doSomething();
}

 Usage:
 @MyAnnotation ("What to do")
 public void mymethod() { .... }

© JBoss, Inc. 2003, 2004. 12

 Professional Open Source™

 Full-value or multi-value: Full-value type annotations have multiple

data members. Therefore, you must use a full data=value parameter
syntax for each member.
Example: public @interface MyAnnotation {
String doSomething();
int count;
String date();
}

 Usage:
@MyAnnotation (doSomething="What to do", count=1, date="09-09-
2005")
public void mymethod() { .... }

© JBoss, Inc. 2003, 2004. 13

 Meta-Annotations (Annotation Types)
Professional Open Source™

 Meta-annotations, which are actually known as the annotations of

annotations, contain four types. These are:

– Target
– Retention
– Documented
– Inherited

© JBoss, Inc. 2003, 2004. 14

 The Target annotation
Professional Open Source™

 The target annotation indicates the targeted elements of a class in

which the annotation type will be applicable. It contains the following
enumerated types as its value:

 @Target(ElementType.TYPE)—can be applied to any element of a class

@Target(ElementType.FIELD)—can be applied to a field or property
@Target(ElementType.METHOD)—can be applied to a method level annotation
@Target(ElementType.PARAMETER)—can be applied to the parameters of a method
@Target(ElementType.CONSTRUCTOR)—can be applied to constructors
@Target(ElementType.LOCAL_VARIABLE)—can be applied to local variables
@Target(ElementType.ANNOTATION_TYPE)—indicates that the declared type itself is
an annotation type

© JBoss, Inc. 2003, 2004. 15

 The Retention annotation
Professional Open Source™

 The retention annotation indicates where and how long annotations

with this type are to be retained. There are three values:

 RetentionPolicy.SOURCE—Annotations with this type will be by

retained only at the source level and will be ignored by the compiler

 RetentionPolicy.CLASS—Annotations with this type will be by

retained by the compiler at compile time, but will be ignored by the
VM

 RetentionPolicy.RUNTIME—Annotations with this type will be

retained by the VM so they can be read only at run-time

© JBoss, Inc. 2003, 2004. 16

 Professional Open Source™

 @Retention(RetentionPolicy.RUNTIME)
 public @interface Test_Retention {
 String doTestRetention();
 }

© JBoss, Inc. 2003, 2004. 17

 The Inherited annotation
Professional Open Source™

 It indicates that the annotated class with this type is automatically

inherited.

 More specifically, if you define an annotation with the @Inherited tag,

then annotate a class with your annotation, and finally extend the
class in a subclass, all properties of the parent class will be inherited
into its subclass.

© JBoss, Inc. 2003, 2004. 18

 Professional Open Source™

 Example 7
 First, define your annotation:
 @Inherited public @interface myParentObject {
 boolean isInherited() default true;
 String doSomething() default "Do what?";
 }

 Next, annotate a class with your annotation:

 @myParentObject
 public Class myChildObject { }

 As you can see, you do not have to define the interface methods
inside the implementing class. These are automatically inherited
because of using the @Inherited tag.

© JBoss, Inc. 2003, 2004. 19