Annotations: Java

Annotation is a tag, of interface type, which will be processed during compile-time or run-time.

The concept of "Annotations" in java is introduced in java 1.5.
These are inserted into the code to provide more information about the code(meta code)

Annotations can be processed by the compiler (or) annotation processing tools, which can be made available at run-time.
eg: Java predefined annotations are processed by "apt.exe" under jdk's bin folder
Servlet specific annotations are processed by a jar called "annotations-api.jar"

Advantages of using Annotations:
1. Provides a kind of information to the compiler, for eg: to detect programmer error(Override) or to suppress warnings
2. Compile-time and Deployment-time processing
3. Run-time processing

Types of Annotations:
There can be two types of annotations
1. Built-in annotations(Predefined)
2. Custom annotations(User-defined)

1. Built-in Annotations:
These are provided by Sun as part of java 1.5
There are 7 built-in annotations

• Override
• Deprecated
• SuppressWarnings
• Retention
• Target
• Documented
• Inherited

@Override, @Deprecated, @SuprressWarnings - These 3 are called Regular Java Annotations and are used at compile-time.
Remaining 4 (Retention, Target, Documented, Inherited) are used to create custom annotations.

Regular Annotations:

1. @Override
This can be used by the compiler to check whether a method in sub-class is properly overriding its super-class method or not.
The Retention Policy for @Override annotation is SOURCE, which means this java annotation will be discarded completely after compiling the code and would not be included in .class file or byte code.

eg:
I want to override equals method in Object class, whose signature is:
public boolean equals(Object obj)

class OverrideDemo {
        @Override
        public boolean equals(OverrideDemo od) {
                return false;
        }
}

Compiler output:

If you replace equals method parameter "OverrideDemo" with "Object", it gets compiled without any errors.

2. @Deprecated:

This can be specified to all types - variables/classes/methods.

When this is specified for a method, it indicates the developer who are using those API methods, that this method should not be used and it is expected to be removed in future releases.

If developer still uses it, it gives a warning during compile-time.

eg:

@Deprecated

class ClassOne {

}

public class DeprecatedDemo {

        static public void main(String[] args) {

                ClassOne one = new ClassOne();

        }

}

Compiler output:

3. @SuppressWarnings:

This instructs the compiler to suppress warnings of a particular type that are shown during compilation time.

This can be applied only to Classes.

For this annotation type, we must pass the value which should be suppressed. If no value is passed, compiler flags it with following error.
annotation java.lang.SuppressWarnings is missing value

eg:
import java.util.List;
import java.util.ArrayList;

public class ListDemo {
        static public void main(String[] args) {
                List list = new ArrayList();
                list.add("one");
        }
}

Compiler output:

Now if you modify the code as below, to remove "unchecked" or "unsafe" warnings, compiler will not flag any warning.

import java.util.List;

import java.util.ArrayList;

@SuppressWarnings(value="unchecked")

public class ListDemo {

        static public void main(String[] args) {

                List list = new ArrayList();

                list.add("one");

        }

}

Meta Annotations:
These are used to create custom java annotations.
These are part of "java.lang.annotation" package.

1. @Retention:
Retention Policy: The Retention policy determines at which point of time, an annotation should be discarded.

There are 3 types of retention policies, which are specified using an enum class "java.lang.annotation.RetentionPolicy".

• SOURCE: Annotations are to be discarded by the compiler.
• CLASS: Annotations are to be recorded in the class file by the compiler but need not be retained by the VM at run time.  This is the default behavior.
• RUNTIME: Annotations are to be recorded in the class file by the compiler and retained by the VM at run time, so they may be read reflectively.

2. @Target:
This is a meta annotation that defines the target type or type of programming element.
Allowed target types are defined in the enum class "java.lang.annotation.ElementType", which are: TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE, ANNOTATION_TYPE, PACKAGE.

3. @Documented:
4. @Inherited:

Marker Annotation:
An annotation type with no elements is termed a marker annotation type.

Single Member Annotation:
An annotation with only single member is termed as "Single Member Annotation", whose value can be specified directly or with an attribute called "value".


Marker Annotation Example:

package com;

import java.lang.annotation.Annotation;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.reflect.Method;

@Retention(RetentionPolicy.RUNTIME)
@interface MyMarkerAnnotation {
}

enum AnnotationType {
METHOD, CLASS;
}

@Deprecated
class TestMarkerAnnoationClass {
@MyMarkerAnnotation
@Deprecated
public void markerMethod() {

}
}

public class MarkerAnnotationDemo {

public void testMarkerMethod(String methodName, Class methodClass,
Class annotClass) throws Exception {
try {
Method method = methodClass.getMethod(methodName, null);

boolean annotPresent = method.isAnnotationPresent(annotClass);

if (annotPresent)
System.out.println(methodName + "() has annotation of type: "
+ annotClass.getName());
else
throw new Exception("No such Annotation present");
} catch (SecurityException se) {

} catch (NoSuchMethodException nsme) {

}
}

public void printAnnotations(String clsName, String methName,
AnnotationType annotType) {
try {
if (annotType.equals(AnnotationType.CLASS)) {
Class cls = Class.forName(clsName);
Annotation[] annots = cls.getAnnotations();

System.out.print("Annotations for: " + annotType + " are:");
for (Annotation annot : annots)
System.out.print(" " + annot);
System.out.println();
} else if (annotType.equals(AnnotationType.METHOD)) {
Class cls = Class.forName(clsName);
Method method = cls.getMethod(methName, null);

Annotation[] annots = method.getAnnotations();

System.out.print("Annotations for method: " + methName
+ " of class: " + clsName + " are:");
for (Annotation annot : annots)
System.out.print(" " + annot);
System.out.println();
}
} catch (Exception e) {
e.printStackTrace();
}
}

static public void main(String[] args) throws Exception {
MarkerAnnotationDemo demo = new MarkerAnnotationDemo();

demo.testMarkerMethod("markerMethod", TestMarkerAnnoationClass.class,
MyMarkerAnnotation.class);
// demo.testMarkerMethod("markerMethod", String.class);

demo.printAnnotations("com.TestMarkerAnnoationClass", null,
AnnotationType.CLASS);
demo.printAnnotations("com.TestMarkerAnnoationClass", "markerMethod",
AnnotationType.METHOD);
}
}

Output:
markerMethod() has annotation of type: com.MyMarkerAnnotation
Annotations for: CLASS are: @java.lang.Deprecated()
Annotations for method: markerMethod of class: com.TestMarkerAnnoationClass are: @com.MyMarkerAnnotation() @java.lang.Deprecated()

Single Member Annotation Example:

package com;

import java.lang.annotation.Annotation;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.reflect.Method;

@Retention(RetentionPolicy.RUNTIME)
@interface SingleMemberAnnotation {
String name();
}

class TestSingleMemberAnnot {
@SingleMemberAnnotation(name="Suresh Reddy")
public void singleMemMethod() {
}
}

public class SingleMemberAnnotDemo {
public void testSingleMemberMethod() throws Exception {
Class cls = Class.forName("com.TestSingleMemberAnnot");
Method method = cls.getMethod("singleMemMethod", null);

SingleMemberAnnotation singleMemAnnot = (SingleMemberAnnotation) method
.getAnnotation(SingleMemberAnnotation.class);

System.out.println(singleMemAnnot.name());
}

static public void main(String[] args) throws Exception {
SingleMemberAnnotDemo demo = new SingleMemberAnnotDemo();
demo.testSingleMemberMethod();
}
}

Output:
Suresh Reddy

Single Member Annotation with default value Example:
package com;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.reflect.Method;

@Retention(RetentionPolicy.RUNTIME)
@interface DefaultValAnnotation {
public String name() default "Reddy";
}

class DefaultValAnnotClass {
@DefaultValAnnotation()
public void testDefaultValMethod() {

}

@DefaultValAnnotation(name="Suresh Reddy")
public void testDefaultValMethod1() {

}
}

public class DefaultValAnnotDemo {
public void testSingleMemberMethod() throws Exception {
Class cls = Class.forName("com.DefaultValAnnotClass");
Method method = cls.getMethod("testDefaultValMethod", null);

DefaultValAnnotation singleMemAnnot = (DefaultValAnnotation) method
.getAnnotation(DefaultValAnnotation.class);

System.out.println(singleMemAnnot.name());

Method method1 = cls.getMethod("testDefaultValMethod1", null);

DefaultValAnnotation singleMemAnnot1 = (DefaultValAnnotation) method1
.getAnnotation(DefaultValAnnotation.class);

System.out.println(singleMemAnnot1.name());
}

static public void main(String[] args) throws Exception {
DefaultValAnnotDemo demo = new DefaultValAnnotDemo();
demo.testSingleMemberMethod();
}

}

Output:
Reddy
Suresh Reddy