Java annotation

From Wikipedia, the free encyclopedia

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

 @Twizzle public void toggle() { }
 // @Twizzle is an annotation to method toggle().
  
 public @interface Twizzle { }
 // Declares the annotation 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 are annotated to indicate where and when they can be used:

 @Retention(RetentionPolicy.RUNTIME) // Retain this annotation in the VM for use at runtime.
 @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 associating behaviors with user-defined classes and methods that must otherwise be declared in some external source (like 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;
   }
 }

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.

1 History
2 Processing
3 See also
4 References
5 External links

[edit] 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. ^[3] 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.

[edit] 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 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.