Java Custom Annotations

My earlier post covered in-built annotations supported by Java 5. Today we will look at developing custom java annotations on our own.

Let’s begin by defining our own custom java annotation called Documentation. The definition of the annotation class is as below:

package com.vinraj.custom;

public @interface Documentation {

}

The only difference between an interface definition and that of an annotation is the presence of @ before the interface keyword. Now the annotation can have its own members.

package com.vinraj.custom;

public @interface Documentation {

    public String author();

    public String version();

    public String shortDescription();

    public String[] reviews();

}

Below are the general guidelines to be followed while defining annotations:

1. Annotation declaration should start with an ‘at’ sign like @, following with an interface keyword, following with the annotation name.
2. Method declarations should not have any parameters.
3. Method declarations should not have any throws clauses.
4. Return types of the method should be one of the following:

• • primitives
  • String
  • Class
  • enum
  • array of the above types

Let’s look at how the custom annotation Documentation can be used.

package com.vinraj.custom;

public class NewClass {

    @Documentation(
	author="James Smith",
	version="1.0",
	shortDescription="Testing",
	reviews={"good", "nice"})
    public void test() {

    }
}

The annotation member elements can be set to have default values. Here’s an example:

package com.vinraj.custom;

public @interface Documentation {

    public String author() default "Tim Burton";

    public String version() default "1.0";

    public String shortDescription();

    public String[] reviews();

}

Due to introduction of the default values the NewClass can be defined in the following manner:

package com.vinraj.custom;

public class NewClass {

    @Documentation(
	author="James Smith",
	shortDescription="Testing",
	reviews={"good", "nice"})
    public void test() {

    }

}

We have omitted the version member variable from the annotation Documentation in NewClass.

There are specific annotations which can only be used in the context of annotations. The annotations are target, retention, documented and inherited.

Let’s look at their usage one at a time. First let’s look at target annotation. The target annotation defines which program elements can have annotations of the defined type. The user can put in the following options:

1. TYPE: Class, interface, or enum (not annotation)
2. FIELD: member fields (including enum values)
3. METHOD: methods (does not include constrcutors)
4. PARAMETER: method parameter
5. CONSTRUCTOR: constructor
6. LOCAL_VARIABLE: local variable or catch clause
7. ANNOTATION_TYPE: Annotation types
8. PACKAGE: java package

Let’s change the Documentation annotation class to the following.

package com.vinraj.custom;

import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

@Target(ElementType.METHOD)
public @interface Documentation {

    public String author() default "Tim Burton";

    public String version() default "1.0";

    public String shortDescription();

    public String[] reviews();

}

We have now limited the usage of the Documentation annotation to the class methods. Let’s change the implementation of the NewClass to the following:

package com.vinraj.custom;

public class NewClass {

    @Documentation(
	author="James Smith",
	shortDescription="Testing",
	reviews={"good", "nice"})
    public void test() {

    }

    @Documentation(
	author="James Smith",
	shortDescription="Testing",
	reviews={"good", "nice"})
    public String name = "";

}

A compilation error is raised for using Documentation annotation for class instance variable.

The retention annotation indicates where and how long annotations of this type will be retained. This annotation has three options source, class and runtime. If the retention option selected is source, the annotation is discarded post compilation. Examples of such annotation types are @Override and @SuppressWarnings. The next option is class, the annotation is discarded during class load. The last option is the runtime. The annotation information marked using this option is never discarded. The annotation should be available for reflection at runtime. Example of annotation that could be useful at runtime is @Deprecated.

The Documentation custom annotation can be added the Retention annotation in the following manner.

package com.vinraj.custom;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Documentation {

    public String author() default "Tim Burton";

    public String version() default "1.0";

    public String shortDescription();

    public String[] reviews();

}

By default, the annotation and related information does not appear in the class javadoc. A marker annotation @Documented in provided to cause the annotation related information to be added in the class javadoc. The Documentation custom annotation can use the @DOcumented in the following manner.

package com.vinraj.custom;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Documented
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Documentation {

    public String author() default "Tim Burton";

    public String version() default "1.0";

    public String shortDescription();

    public String[] reviews();

}

Now let’s move on to the last annotation @Inherited. Inherited is probably the most complex of all annotations and does provide an interesting option.

(Update: 24th Dec 09) This portion of this post content has been revised after Gustav pointed out an error in my earlier content.

To understand the @Inherited annotation let’s consider the following custom annotation CarAnnotation.

package com.test.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface CarAnnotation {

    public String maker();

}

I create the following AbstractBMWCar with CarAnnotation annotation.

package com.test.annotations;

@CarAnnotation(maker="BMW")
public class AbstractBMWCar {

}

I also create a child class BMWRoadsterCar which inherits AbstractBMWCar. The source code is as follows:

package com.test.annotations;

public class BMWRoadsterCar extends AbstractBMWCar {

}

As I have defined the CarAnnotation with the @Inherited annotation, its informational content is available to the child class BMWRoadsterCar. As already clarified BMWRoadsterCar is a child class of AbstractBMWCar. To understand the implication, please run the following test class in two scenarios:

• With the @Inherited annotation in the CarAnnotation.
• Without the @Inherited annotation in the CarAnnotation (i.e. comment out line 11 of the CarAnnotation annotation class).

The test class source code is as below:

package com.test.annotations.test;

import java.lang.annotation.Annotation;

import com.test.annotations.AbstractBMWCar;
import com.test.annotations.BMWRoadsterCar;
import com.test.annotations.CarAnnotation;

public class CarAnnotationsTest {

	public static void main(String[] args) {
		
		Class[] classes = {AbstractBMWCar.class, BMWRoadsterCar.class};
		
		for (Class classObj : classes) {
			Annotation[] annotations = classObj.getAnnotations();
			System.out.println("No. of annotations: " + annotations.length);
			for (Annotation annotation : annotations) {
				CarAnnotation carAnnotation = (CarAnnotation)annotation; 
				System.out.println(carAnnotation.maker());
			}			
		}		
	}
}

The output for scenario 1 is :

No. of annotations: 1
BMW
No. of annotations: 1
BMW

The output for scenario 2 is :

No. of annotations: 1
BMW
No. of annotations: 0

Clearly, both the classes AbstractBMWCar and BMWRoadsterCar have access to CarAnnotation information when the CarAnnotation is defined with @Inherited; BMWRoadsterCar does not have access to the CarAnnotation when the @Inherited annotation is removed. Something to keep in mind when developing your own custom annotations.

That’s all from the annotation desk at the moment.