I know Java annotations are a very controversial subject, and there are lots of different opinions regarding them.

In a general manner, i like annotations. Annotations placed on classes and methods are nice, they help a lot without much damage. A good example of well used annotations in my opinion is the Java Persistence API. It reduces a lot of the code you'd need to write and doesn't polute things too much.

However, placing annotations inside method arguments, such as in JSR-311 (first place where i saw it) starts to really mess things up. Here's an example of the use they propose:

@UriTemplate("widgets")
public class WidgetList {
@HttpMethod
@UriTemplate("offers")
WidgetList getDiscounted() {...}

@UriTemplate("{id}")
Widget findWidget(@UriParam("id") String id) {
return lookupWidget(id);
}
}

The @UriParam is the one that really bothers me here. I'm sure it must serve a good purpose for the JSR, and it probably makes some stuff easier. However, it's unquestionable that annotating this much starts to polute the code beyond the acceptable limits. In such a short piece of code we saw 5 annotations.

I'm not saying we should go back to XML files. I really prefer annotations over XML when they are used over classes and methods, much like JPA does it. However, as many other things, annotations can be misused, and in this JSR 311 example, i think they misuse them. I just hope this trend doesn't get stronger, because i think Java would get uglier with this. Just keep the simple annotations please :)

Find Singapore Apartment  and Room Rentals here

India Stock Market blog

I am writing this as I learn about writing custom java annotations. I find that information about custom annotations and their processing is scattered and lengthy so I am summarizing the steps that is required to write a custom annotation and the ways to process it in a single place. I am also attaching the links to the tutorials and documents that I am referring to while I learn.

I hope this will help to get a high-level overview and also to refer back when in need. Use the given links for a detailed description of all the steps listed in this post

Steps to write a custom java annotation and process it either at run-time or compile time:

1. Declare the Annotation Type

- use @interface keyword to declare the Annotation
- add a method declaration for every element in the Annotation
- name the method as 'value' if the annotation has only one element
- add no declarations if is to act as a marker Annotation
- restrict return types to primitives, String, Class, enums, annotations, and arrays of the preceding types
- add no parameters and no throws clause
- specify any default values using 'default' keyword
- annotate this new type with meta-annotations like @Retention and @Target

2. Decorate the target classes and methods with the custom annotation

- use @NewAnnotationType( element key-value pairs separated by commas ) e.g @TryMe (name="RK', age="24", sex="female")
- if its a marker annotation then there is no need for the paranthesis
- if its an annotation with a single element then no need to use 'key=value' syntax e.g @TryMe("Waiting for you!!")

3. Process the custom Annotation. Annotations can be read from source files, class files, or reflectively at run time so there are few options and subsequently decisions to be made when it comes to the best way to process them for your application

Run Time:

- Use the new AnnotatedElement and Annotation interfaces added to the java reflection API to detect the presence of your annotation at run-time
- AnnotatedElement interface is in the java.lang.reflect package and implemented by the classes Class, Constructor, Field, Method, and Package
- AnnotatedElement interface has the following methods - getAnnotations(),getDeclaredAnnotations(),getAnnotation(Class<T>),isAnnotationPresent(Class<? extends Annotation>)
- Every annotation type automatically implements the java.lang.annotation.Annotation interface which happens in the background when the @interface keyword is used to declare a new annotation type

Compile Time with APT:

- Use APT (Annotation Processing Tool) command line utility that comes with Java 5. In Java 6 this is included as part of the compiler itself so there will be no need to use a tool explicitly. Overview in the sun's document make it sound simple but implementing could be a little more complex than that. Here are the steps

1. Write a Processor that implements the com.sun.mirror.apt.AnnotationProcessor interface
2. Write a processor factory class that implements AnnotationProcessorFactory interface. This factory should use the AnnotationProcessorEnvironment object passed to it to return the AnnotationProcessor that can process the annotations present in the source file
3. Compile the processors and factories using javac with tools.jar on the classpath
4. Make the factory available to the apt tool either using the '-factory' command line option or by using the 'apt discovery' procedure

Compile Time with javax.annotation.processing package:

- Use a custom annotation processor based on javax.annotation.processing package

1. Write a processor class that extends javax.annotation.processing.AbstractProcessor class
2. Specify the annotation that this custom processor is interested in. Can be done by either overriding the getSupportedAnnotationTypes() method of AbstractProcessor class or by annotating the custom class with @SupportedAnnotationTypes annotation.
3. Override the process() method
http://www.zdnetasia.com/techguide/java/0,39044898,39362483,00.htm is an excellent article you can refer to for more information on this

References and Sources :

Very good document about processing the Annotations - http://www.zdnetasia.com/techguide/java/0,39044898,39362483,00.htm
Another nice document - http://www.oracle.com/technology/pub/articles/hunter_meta_2.html &
http://www.oracle.com/technology/pub/articles/hunter_meta_3.html
SR 175: A Metadata Facility for the JavaTM Programming Language -  http://www.jcp.org/en/jsr/detail?id=175
Very Basic tutorial - http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html
Document about the Annotation Processing Tool - http://java.sun.com/j2se/1.5.0/docs/guide/apt/index.html
Mirror API Specification - http://java.sun.com/j2se/1.5.0/docs/guide/apt/mirror/overview-summary.html
Good tutorial for Custom Annotations - http://www.ibm.com/developerworks/library/j-annotate2.html

RK

Find Singapore Apartment  and Room Rentals here

Looking for a date or love? Click here to find one for free!!

Stock Market Views, Experiences on http://theindiastockmarket.blogspot.com/

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. In a typical inheritance heirarchy, we define the parent as typically an interface and all the children implement that interface. In case we need to associate any default behavior with interface, we need to create an abstract class that implements the default behavior and all children inherit this class. Let's use an example to understand this.

package com.test.annotations.inherited;

public interface Car {

    public String makeNoise();

}

package com.test.annotations.inherited;

public class AbstractCarImpl implements Car {

    public String makeNoise() {
	return "Vroom";
    }

}

package com.test.annotations.inherited;

public class BMW extends AbstractCarImpl {

}

package com.test.annotations.inherited;

public class Toyota extends AbstractCarImpl {

}

The AbstractCarImpl class has been created purely to ensure that the default behavior associated with Car i.e. makeNoise is implemented. This severely restricts the object hierarchy. The Inherited annotation may provide us an alternative. Note this has some restrictions.

package com.test.annotations.inherited;

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

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

    public String makeNoise() default "Vroom";

}

package com.test.annotations.inherited;

@CarAnnotation
public class BMWCar {

}

We define a custom annotation named CarAnnotation. Add the @Inherited annotation to it and add the annotation in the child class BMWCar. The advantage of this approach is that we do not need to define an intermediate abstract class for default implementations. The default implementations are inherited because of the @Inherited tag. The pitfalls are that this might take some time to understand and we cannot use this approach for complex data types. The data types are restricted to the annotation type restriction.

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

Java provides three in built annotations, namely Override, Deprecated and SuppressWarnings. Let's look at the first annotation type Override. Consider the following code:

Class A:

package com.test.annotations;

public class A {

    public void doSomething() {

    }

}

Class B:

package com.test.annotations;

public class B extends A {

    public void doSomething(){

    }

}

Class B extends A. We want class B to override the doSomething method defined in class A. Due to oversight it is possible that the method name could be misspelt or the method signature changed causing the override behaviour to remain unimplemented. To ensure that such mistakes do not happen we have the Override annotation. Let's change the Class B implementation to the following.

package com.test.annotations;

public class B extends A {

    @Override
    public void doSomething(){

    }

}

The addition of the annotation forces the compiler to verify if the doSomething method in the parent class is actually overridden. Let's assume that the method name is changed from doSomething to dosomething. The Override annotation causes the compiler to throw the following error message "The method dosomething of B must override a superclass method" Moving on to the next standard annotation Deprecated. Consider the following class DeprecatedTest:

package com.test.annotations.deprecated;

public class DeprecatedTest {

    @Deprecated
    public void test() {

    }

    public static void main(String args[]) {
	DeprecatedTest dpTest = new DeprecatedTest();
	dpTest.test();
    }

}

The method test has been marked deprecated using the deprecated annotation. In Eclipse the usage of the deprecated method is marked using a strikethrough. Java compiler will show a warning message like "warning: test method of DeprecatedTest class is deprecated". To force the compiler to show warnings run javac using the -deprecated or -Xlint:deprecated option.

Let's look at the third standard annotation available in the Java 5 JDK i.e. SuppressWarnings. Consider the following sample class:

package com.test.annotations.suppresswarns;

import java.util.ArrayList;
import java.util.List;

1:public class SuppressWarningsTest {
2:
3:    public static void main(String[] args) {
4:	List names = new ArrayList<String>();
5:	names.add("tim");
6:
7:    }
8:
9:}

The warning message "The method add(Object) belongs to the raw type List. References to generic type List<E> should be parameterized." is generated at line 5. In case we do not want to view the warning messages, change the SuppressWarningsTest class's code to the following:

package com.test.annotations.suppresswarns;

import java.util.ArrayList;
import java.util.List;

public class SuppressWarningsTest {

    @SuppressWarnings(value={"unchecked"})
    public static void main(String[] args) {
	List names = new ArrayList<String>();
	names.add("tim");
    }

}

The warning message is removed. Note my current observations are based on running the code in Eclipse environment. The compiler generated error/warning messages should be similar. In the next post I intend to look at developing custom annotations and their possible scenarios for use.