Java Annotations Tutorial

1- What is annotation

Java annotations are used to provide meta data for your Java code. Being meta data, the annotations do not directly affect the execution of your code, although some types of annotations can actually be used for that purpose.Java annotations were added to Java from Java 5.
Java annotations are typically used for the following purposes:
  1. Compiler instructions
  2. Build-time instructions
  3. Runtime instructions

 

1.1- Instructions for compiler

Java has 3 built-in annotations that you can use to give instructions to the Java compiler.
  • @Deprecated
  • @Override
  • @SuppressWarnings
These annotations are explained in more detail later in this document.

1.2- Instruction in Build-time

Java annotations can be be used at build-time, when you build your software project. The build process includes generating source code, compiling the source, generating XML files (e.g. deployment descriptors), packaging the compiled code and files into a JAR file etc. Building the software is typically done by an automatic build tool like Apache Ant or Apache Maven. Build tools may scan your Java code for specific annotations and generate source code or other files based on these annotations.

1.3- Instructions in runtime

Normally, Java annotations are not present in your Java code after compilation. It is possible, however, to define your own annotations that are available at runtime. These annotations can then be accessed via Java Reflection, and used to give instructions to your program, or some third party API.

2- Build-in Annotations

There are 3 important available Annotation of Java
  • @Deprecated
  • @Override
  • @SuppressWarnings

2.1- @Deprecated

This is an Annotation used to annotate something deprecated like class or method; and for the best, we should not use it any more.
If you use something deprecated, the compiler will notify you should use an alternative way . Or with programming IDE like Eclipse, it also shows you visual notifications.
  • DeprecatedMethodDemo.java
package org.o7planning.tutorial.ann.builtin;

import java.util.Date;

public class DeprecatedMethodDemo {

   /**
    * @deprecated replaced by {@link #todo(String,Date)}
    */
   @Deprecated
   public void todoJob(String jobName) {
       System.out.println("Todo " + jobName);
   }

   public void todo(String jobName, Date atTime) {
       System.out.println("Todo " + jobName + " at " + atTime);
   }

   public void todoNothing() {
       System.out.println("Todo Nothing");
   }

   public static void main(String[] args) {

       DeprecatedMethodDemo obj = new DeprecatedMethodDemo();

       obj.todoJob("Java coding");

       obj.todoNothing();
   }
}
Here are picture, Eclipse inform you:

2.2- @Override

The @Override annotation is used above methods that override methods in a superclass. If the method does not match a method in the superclass, the compiler will give you an error.

The @Override annotation is not necessary in order to override a method in a superclass. It is a good idea to use it still, though. In case someone changed the name of the overridden method in the superclass, your subclass method would no longer override it. Without the @Override annotation you would not find out. With the @Override annotation the compiler would tell you that the method in the subclass is not overriding any method in the superclass.
See an Example:
  • Job.java
package org.o7planning.tutorial.ann.builtin;

public class Job {

    // This is method of Job class.
    public String getName() {
        return null;
    }

}
  • JavaCoding.java
ckage org.o7planning.tutorial.ann.builtin;

public class JavaCoding extends Job {

 
    // This method is overridden method getName() of the superclass.
    // @Override not required to write on this method.
    // But it is necessary if someone changed the name of the method getName()
    // in parent class, an error message will tell you.
    @Override
    public String getName() {
        return "Java Coding";
    }
}
 
And here is the alert of the Java Compiler:

2.3- @SuppressWarnings

The @SuppressWarnings annotation makes the compiler suppress warnings for a given method. For instance, if a method calls a deprecated method, or makes an insecure type cast, the compiler may generate a warning. You can suppress these warnings by annotating the method containing the code with the @SuppressWarnings annotation.
See an Example:
  • SuppressWarningsDemo.java
package org.o7planning.tutorial.ann.builtin;

import java.util.Date;

public class SuppressWarningsDemo {

   @SuppressWarnings("deprecation")
   public Date getSomeDate() {

       Date date = new Date(2014, 9, 25);
       return date;
   }

}
See the compiler warning:
  • SuppressWarningsDemo2.java
package org.o7planning.tutorial.ann.builtin;

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

public class SuppressWarningsDemo2 {

  public List<?> getDatas() {
      List<String> list = new ArrayList<String>();
      list.add("One");
      return list;
  }

  @SuppressWarnings({ "deprecation", "unused", "unchecked" })
  public void processDatas() {  

     
      // You use deprecated Constructor
      // Variable 'date' was created, but not used      
      Date date = new Date(2014, 9, 25);

      // Cast unsafe.
      // Variable 'datas' is created, but not used in the code.      
      List<String> datas= (List<String>) this.getDatas();        
  }

}
The warning from the compiler:

3- Write Your Annotation

Using  @interface is a keyword of declaring an Annotation, and this annotation is quite similar to an interface. An annotation may have or not have elements in it. Characteristics of elements of an annotation:
  • There is no function body
  • There is no functional parameter
  • The returning declaration must be a specific type:
    • Primitive type (boolean, int, float,...)
    • Enum
    • Annotation
    • Class (eg: String.class)
  • Element can have default values

3.1- Your first Annotation

  • MyFirstAnnotation.java
package org.o7planning.tutorial.ann1;

public @interface MyFirstAnnotation {

    // element name.
    public String name();

    // Element description, default value "".
    public String description() default "";  
}
Annotation can be used on:
  1. TYPE - Class, interface (including annotation type), or enum declaration
  2. FIELD - Field declaration (includes enum constants)
  3. METHOD - Method declaration
  4. PARAMETER - Parameter declaration
  5. CONSTRUCTOR - Constructor declaration
  6. LOCAL_VARIABLE - Local variable declaration
  7. ANNOTATION_TYPE - Annotation declaration
  8. PACKAGE - Package declaration
  • UsingMyFirstAnnotation.java
package org.o7planning.tutorial.ann1;

@MyFirstAnnotation(name = "Some name", description = "Some description")
public class UsingMyFirstAnnotation {

    // Annotation on Constructor.
    // The value of the element name is "John"
    // Value element description is "Write by John".
    @MyFirstAnnotation(name = "John", description = "Write by John")
    public UsingMyFirstAnnotation() {

    }
   
    // Annotation tied up method.
    // The value of the element name is "Tom"
    // Description element is not declared, it will be assigned a default value    
    @MyFirstAnnotation(name = "Tom")
    public void someMethod() {

    }

    // An Annotation on parameter of method.
    public void todo(@MyFirstAnnotation(name = "none") String job) {

        // An annotation on local variable.
        @MyFirstAnnotation(name = "Some name")
        int localVariable = 0;

    }

}

3.2- Annotation with element value. (Special!)

An Annotation has an element named value that has some special characteristics:
  • AnnWithValue.java
package org.o7planning.tutorial.ann2;

public @interface AnnWithValue {

 
    // Element named 'value'
    // There is a bit special when using this element.    
    public int value();

    // Element 'name'.    
    public String name() default "";

}
  • UsingAnnWithValue.java
package org.o7planning.tutorial.ann2;

public class UsingAnnWithValue {

    @AnnWithValue(name = "Name1", value = 100)
    public void someMethod1() {

    }
   
    // Initialize the elements of Annotation in the usual way.
    // Element 'name' using default.
    @AnnWithValue(value = 100)
    public void someMethod2() {

    }

 
    // With element 'value', you can just write out the value of it.    
    @AnnWithValue(100)
    public void someMethod3() {

    }
}

3.3- @Retention & @Target

@Retention & @Target is two available annotation of Java.

@Retention: Used to note the existence level of some annotation.
Particularly, there are 3 levels of existence awareness of the noted thing:
  1. RetentionPolicy.SOURCE: Exists on source code, and free from recognition of compiler.
  2. RetentionPolicy.CLASS: Its existence is identified by the compiler, but not by the virtual machine at the Runtime.
  3. RetentionPolicyRUNTIME: reaches the highest level of existence, is identified by compiler and by the virtual machine at the Runtime.
@Target: is used to note another annotation and its using scope.
  1. ElementType.TYPE - attached on the declaration of Class, interface, enum, annotation.
  2. ElementType.FIELD -attached on the declaration of field and the enum constant.
  3. ElementType.METHOD -attached on the declaration of method.
  4. ElementType.PARAMETER - attached on the declaration of parameter
  5. ElementType.CONSTRUCTOR - attached on the declaration of constructor
  6. ElementType.LOCAL_VARIABLE - attached on the local variable
  7. ElementType.ANNOTATION_TYPE -attached on the declaration of Annotation
  8. ElementType.PACKAGE - attached on the declaration of package.
  • AnnFM.java
package org.o7planning.tutorial.ann3;

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

// Annotation are to be discarded by the compiler.
@Retention(value = RetentionPolicy.SOURCE)

// AnnFM will only be used on FIELD or  METHOD.
@Target(value = { ElementType.FIELD, ElementType.METHOD })
public @interface AnnFM {

}
  • UsingAnnFM.java
package org.o7planning.tutorial.ann3;

public class UsingAnnFM {

    // AnnFM will only be used on FIELD or  METHOD.
    @AnnFM
    protected int someField = 100;

    // AnnFM will only be used on FIELD or  METHOD.
    @AnnFM
    public void someMethod() {

    }

}

3.4- Annotation & Reflection

Java Reflection can identify things like Class, field, method annotated by some Annotation. And of course it can recognize only Annotation with  @Retention(RetentionPolicy.RUNTIME)
The below example describes a program reading annotations on original Java files and creating Html files. Each class is equivalent to a html file.
  • AnnHtmlUL.java
package org.o7planning.tutorial.ann4;

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

@Retention(RetentionPolicy.RUNTIME)
 
// Using for Class, interface, annotation, enum.
@Target(value = { ElementType.TYPE })

 
// Simulating the <UL> in HTML.
public @interface AnnHtmlUL {

    public String border() default "border:1px solid blue;";
}
  • AnnHtmlLI.java
package org.o7planning.tutorial.ann4;

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


@Retention(RetentionPolicy.RUNTIME)
@Target(value = { ElementType.FIELD,ElementType.METHOD })

 
// Simulating the <LI> in HTML.
public @interface AnnHtmlLI {

    public String background();

    public String color() default "red";
}
  • DocumentClass.java
package org.o7planning.tutorial.ann4;

@AnnHtmlUL(border = "1px solid red")
public class DocumentClass {

    private String author;

    @AnnHtmlLI(background = "blue", color = "black")
    public String getDocumentName() {
        return "Java Core";
    }

    @AnnHtmlLI(background = "yellow")
    public String getDocumentVersion() {
        return "1.0";
    }

    @AnnHtmlLI(background = "green")
    public void setAuthor(String author) {
        this.author = author;
    }

    @AnnHtmlLI(background = "red", color = "black")
    public String getAuthor() {
        return author;
    }
    
    // This method is not annotated
    public float getPrice()  {
        return 100;
    }

}
  • HtmlGenerator.java
package org.o7planning.tutorial.ann4;

import java.lang.reflect.Method;

public class HtmlGenerator {

    public static void main(String[] args) {

        Class<?> clazz = DocumentClass.class;

         // Check if this class is annotated by Annotation AnnHtmlUL or not.
        boolean isHtmlUL = clazz.isAnnotationPresent(AnnHtmlUL.class);

        StringBuilder sb = new StringBuilder();
        if (isHtmlUL) {
            // Get the AnnHtmlUL annotation on this class.
            AnnHtmlUL annUL = clazz.getAnnotation(AnnHtmlUL.class);

            sb.append("<H3>" + clazz.getName() + "</H3>");
            sb.append("\n");


            // Get the value of the element 'border'.
            String border = annUL.border();

            sb.append("<UL style='border:" + border + "'>");
            
            // Add new line
            sb.append("\n");

            Method[] methods = clazz.getMethods();

            for (Method method : methods) {
                // Check if this method is annotated by Annotation AnnHtmlLI or not.
                if (method.isAnnotationPresent(AnnHtmlLI.class)) {

                    // Get the annotation
                    AnnHtmlLI annLI = method.getAnnotation(AnnHtmlLI.class);

                    // Get the values of elements.
                    String background = annLI.background();
                    String color = annLI.color();

                    sb.append("<LI style='margin:5px;padding:5px;background:"
                            + background + ";color:" + color + "'>");
                    sb.append("\n");
                    sb.append(method.getName());
                    sb.append("\n");
                    sb.append("</LI>");
                    sb.append("\n");
                }
            }
            sb.append("</UL>");
        }
        writeToFile(clazz.getSimpleName() + ".html", sb);
    }
   
    // Write to Console (Or file)
    private static void writeToFile(String fileName, StringBuilder sb) {
        System.out.println(sb);
    }

}
Results of running the example:
Write to a html file:

4- Annotation Processing Tool (Advanced Knowledge)

The situation is that:

You create your own Annotations and use them in your Java application. You set using rules for these Annotations. You want the Java Compiler to notify the error of applying the rules wrongly, if any, at the compile-time. If you use Eclipse for writing codes, you want Eclipse will notify the using error right on IDE.
You can see the study guide APT at: