Annotations in action

Introductions:

Annotations is not new to JEE programmer, we are often using annotation while coding in spring or hibernate or simple servlet-3 or  EJB-3. Day by dat the popularity of annotations goes increasing. One line annotation can reduce 10 line of XML configuration.In other word the popularity of java is because of annotation.

So before using annotations we should know and understand it better.This blog will cover  what is annotation how to use it effectively and how to create and use your own custom annotation.

At the end of session we attached some source code of spring-MVC related annotation like @Controller, @ResuestMapping etc.

What is Annotation?

Java annotations are used to provide meta data for Java code, data about a program that is not part of the program itself. Annotations have no direct effect on the operation of the code they annotate.

Uses/Purposes of annotation:

• Information for the compiler — Annotations can be used by the compiler to detect errors or suppress warnings.
• Compile-time and deployment-time processing — Software tools can process annotation information to generate code, XML files, and so forth.
• Runtime processing — Some annotations are available to be examined at runtime.

Create your custom annotation:

It is possible to create your own annotations. Annotations are defined in their own file, just like a Java class or interface. Here is an example:

@interface MyAnnotation {

    String     value();

    String      name();

    int           age();

    String[]   newNames();

}

This example defines an annotation called MyAnnotation which has four elements.

Notice that each element is defined similarly to a method definition in an interface. It has a data type and a name. You can use all primitive data types as element data types. You can also use arrays as data type. You cannot use complex objects as data type.

To use the above annotation, you do like this:

@MyAnnotation(

    value="123",

    name="Jakob",

    age=37,

    newNames={"Jenkov", "Peterson"}

)

public class MyClass {

}

As you can see, I have to specify values for all elements of the MyAnnotation annotation.

Annotation Default Values:

You can specify default values for an element. That way the element becomes optional and can be left out. Here is an example of how the annotation definition looks with a default value for an element:

@interface MyAnnotation {

    String   value() default "";

    String   name();

    int      age();

    String[] newNames();

}

The value element can now be left out when using the annotation. If you leave it out, it will be considered as if you had used the default value for the value element. Here is an example:

@MyAnnotation(

    name="Jakob",

    age=37,

    newNames={"Jenkov", "Peterson"}

)

public class MyClass {

}

Notice that the value element is no longer present.

@Retention

You can specify for your custom annotation if it should be available at runtime, for inspection via reflection. You do so by annotating your annotation definition with the @Retention annotation. Here is how that is done:

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

@Retention(RetentionPolicy.RUNTIME)

@interface MyAnnotation {

    String   value() default "";

}

Notice the annotation added above the MyAnnotation definition:

@Retention(RetentionPolicy.RUNTIME)

This is what signals to the compiler and JVM that the annotation should be available via reflection at runtime. Accessing annotation at runtime is covered in my Java Reflection and Annotations tutorial, which is part of my Java Reflection Tutorial.

The RetentionPolicy class contains two more values you can use:

RetentionPolicy.CLASS means that the annotation is stored in the .class file, but not available at runtime. This is the default retention policy, if you do not specify any retention policy at all.

RetentionPolicy.SOURCE means that the annotation is only available in the source code, and not in the .class files and not a runtime. If you create your own annotations for use with build tools that scan the code, you can use this retention policy. That way the .class files are not poluted unnecessarily.

@Target

You can specify which Java elements your custom annotation can be used to annotate. You do so by annotating your annotation definition with the @Target annotation. Here is an example:

import java.lang.annotation.ElementType;

import java.lang.annotation.Target;

@Target({ElementType.METHOD})

public @interface MyAnnotation {

    String   value();

}

This example shows an annotation that can only be used to annotate methods.

The ElementType class contains the following possible targets:

ElementType.ANNOTATION_TYPE

ElementType.CONSTRUCTOR

ElementType.FIELD

ElementType.LOCAL_VARIABLE

ElementType.METHOD

ElementType.PACKAGE

ElementType.PARAMETER

ElementType.TYPE

Most of these are self explaining, but a few are not. Therefore is here an explanation of the few that are not obvious.

The ANNOTATION_TYPE target means annotation definitions. Thus, the annotation can only be used to annotate other annotations. Like the @Target and @Retention annotations.

The TYPE target means any type. A type is either a class, interface, enum or annotation.

@Inherited

The @Inherited annotation signals that a custom annotation used in a class should be inherited by subclasses inheriting from that class. Here is an example:

java.lang.annotation.Inherited

@Inherited

public @interface MyAnnotation { }

@MyAnnotation

public class MySuperClass { ... }

public class MySubClass extends MySuperClass { ... }

In this example the class MySubClass inherits the annotation @MyAnnotation because MySubClass inherits from MySuperClass, and MySuperClass has a @MyAnnotation annotation.

@Documented

The @Documented annotation is used to signal to the JavaDoc tool that your custom annotation should be visible in the JavaDoc for classes using your custom annotation. Here is an example:

java.lang.annotation.Documented

@Documented

public @interface MyAnnotation {

}

@MyAnnotation

public class MySuperClass { ... }

When generating JavaDoc for the MySuperClass class, the @MyAnnotation is now included in the JavaDoc.

You will not use the @Documented annotation often, but now you know it exists, if you should need it.

Spring related annotation:

Source code for @RequestMapping:

Eg:

@RequestMapping(value = {"/markcompleted","/updateinteractionbyuniqueid"},method = {RequestMethod.POST,RequestMethod.GET})

Source code:

@controller:

For more spring related annotation you can form the spring source code form Github

https://github.com/JavaInCloud/spring-framework.git