Java annotation

An annotation, in the Java computer programming language, is a special form of syntactic metadata that can be added to Java source code. Classes, methods, variables, parameters and packages may be annotated. Unlike Javadoc tags, Java annotations can be reflective in that they can be embedded in class files generated by the compiler and may be retained by the Java VM to be made retrievable at run-time.

Examples

  // @Twizzle is an annotation to method toggle().
  @Twizzle
  public void toggle() {
  }

  // Declares the annotation Twizzle.
  public @interface Twizzle {
  }

Annotations may include an optional list of key-value pairs:

  // Same as: @Edible(value = true)
  @Edible(true)
  Item item = new Carrot();

  public @interface Edible {
    boolean value() default false;
  }

  @Author(first = "Oompah", last = "Loompah")
  Book book = new Book();

  public @interface Author {
    String first();
    String last();
  }

Annotations themselves may be annotated to indicate where and when they can be used:

  @Retention(RetentionPolicy.RUNTIME) // Make this annotation accessible at runtime via reflection.
  @Target({ElementType.METHOD})       // This annotation can only be applied to class methods.
  public @interface Tweezable {
  }

The compiler reserves a set of special annotations (including @Deprecated, @Override and @SuppressWarnings) for syntactic purposes.

Annotations are often used by frameworks as a way of conveniently applying behaviours to user-defined classes and methods that must otherwise be declared in some external source (such as an XML configuration file) or programmatically (with API calls). The following, for example, is an annotated EJB 3.0 data class:

  @Entity                                           // Declares this an entity bean
  @Table(name = "people")                           // Maps the bean to SQL table "people"
  class Person implements Serializable {
    @Id                                             // Map this to the primary key column.
    @GeneratedValue(strategy = GenerationType.AUTO) // Database will generate new primary keys, not us.
    private Integer id;

    @Column(length = 32)                            // Truncate column values to 32 characters.
    private String name;

    public Integer getId() {
      return id;
    }

    public void setId(Integer id) {
      this.id = id;
    }

    public String getName() {
      return name;
    }

    public void setName(String name) {
      this.name = name;
    }
  }

A complete example is given below:

package com.annotation;

import java.lang.annotation.Documented;
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;


@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE,ElementType.METHOD,
 ElementType.CONSTRUCTOR,ElementType.ANNOTATION_TYPE,
 ElementType.PACKAGE,ElementType.FIELD,ElementType.LOCAL_VARIABLE})
@Inherited
 
public @interface Unfinished {
	public enum Priority { LOW, MEDIUM, HIGH }
	String value();
	String[] changedBy() default "";
	String[] lastChangedBy() default "";
	Priority priority() default Priority.MEDIUM;
	String createdBy() default "prabir karmakar";
	String lastChanged() default "01/01/2009";
}

package com.annotation;

public @interface UnderConstruction {
	String owner() default "PrabirK";
	String value() default "Object is Under Construction.";
	String createdBy() default "Prabir Karmakar";
	String lastChanged() default "01/01/2009";
}

package com.validators;

import javax.faces.application.FacesMessage;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import javax.faces.validator.Validator;
import javax.faces.validator.ValidatorException;

import com.annotation.UnderConstruction;
import com.annotation.Unfinished;
import com.annotation.Unfinished.Priority;
import com.util.Util;

@UnderConstruction(owner="Prabir Karmakar")
public class DateValidator implements Validator{
	
	public void validate(FacesContext context, UIComponent component, Object value)
			throws ValidatorException 
	{
		String date = (String) value;
		String errorLabel = "Please enter a valid date.";
		if(!component.getAttributes().isEmpty())
		{
			errorLabel = (String) component.getAttributes().get("errordisplayval");
		}
		
		if(!Util.validateAGivenDate(date))
		{
			@Unfinished(changedBy = "prabirk"
				,value="whether to add message to context or not, confirm"
				,priority=Priority.HIGH
			)
			FacesMessage message = new FacesMessage(); 
			message.setSeverity(FacesMessage.SEVERITY_ERROR); 
			message.setSummary(errorLabel); 
			message.setDetail(errorLabel); 
			throw new ValidatorException(message); 
		}
		
	}
}

The annotations are not method calls and will not, by themselves, do anything. Rather, the class object is passed to the EJB implementation at run-time, which then extracts the annotations to generate an ORM.

Processing

When Java source code is compiled, annotations can be processed by compiler plug-ins called annotation processors. Processors can produce informational messages or create additional Java source files or resources, which in turn may be compiled and processed, but annotation processors cannot modify the annotated code itself. The Java compiler conditionally stores annotation metadata in the class files if the annotation has a RetentionPolicy of CLASS or RUNTIME. Later, the JVM or other programs can look for the metadata to determine how to interact with the program elements or change their behavior.

History

The Java platform has always had various ad-hoc annotation mechanisms—for example, the transient modifier, or the @deprecated javadoc tag. The general purpose annotation (also known as metadata) facility was introduced to the Java Community Process as JSR-175 in 2002 and approved in September 2004. Annotations became available in the language itself beginning with version 1.5 of the JDK. A provisional interface for compile-time annotation processing was provided by the apt tool in JDK version 1.5, and was formalized through JSR-269 and integrated into the javac compiler in version 1.6.

See also

• Java programming
• Model-driven architecture
• Java virtual machine
• .NET Attributes

External links

• Introduction to Java 5.0 Annotations by Joy Christy
• Of Java Annotations by John Hunt
• An Introduction to Java Annotations by M. M. Islam Chisty