Friday, November 12, 2010

Annotations in Java

BASICS OF ANNOTATIONS

Introduced newly in JDK 5 as part of new ease-of-development features
  • Annotations provide data about a program that is not part of the program itself
  • Inserting arbitrary data into your source code
  • They have no direct effect on the operation of the code they annotate
  • Annotations complement javadoc tags
  • If the markup is intended to affect or produce documentation it should be a javadoc tag, otherwise it should be an annotation
  • Annotations are like meta-tags that you can add to your code and apply them to package declarations, type declarations, constructors, methods, fields, parameters and variables. As a result, you will have helpful ways to indicate whether your methods are dependent on other methods, whether they are incomplete, whether your classes have references to other classes, whether they are deprecated, and so on

USES OF ANNOTATION

  • Information for the compiler - Annotations can be used by the compiler to suppress warnings or detect errors
  • Compiler-time and deployment-time processing - Software tools can process annotation information to generate code, XML files etc..
  • Runtime processing - Some annotations are available to be examined at runtime
  • Automatic generation of auxiliary files, such as deployment descriptors or bean information classes.
  • Automatic generation of code for testing, logging, transaction semantics, and so on.
STANDARD ANNOTATION TYPES

  • DOCUMENTATION
Many annotations replace comments in code. Traditionally,

public class StdWayOfDocumentationHeader {
//Author: Soumya Kandimalla
//Date: Nov 12th 2010
//Version: 1

//class code goes here
}

Using ANNOTATIONS --> 1) Define Annotation Type 2) Use Annotations 3) Make it available for JavaDoc

1) Define Annotation Type: Syntax is shown below
@interface AuthorOfProgram 
{    
 String author();   //Annotation type element declarations    
 String date();    
 int currentRevision() default 1; 
} 

2) Use annotations of the above type with values filled in

@AuthorOfProgram (    
 author = "Soumya Kandimalla",    
 date = "11/12/2010",    
 currentRevision = 1, 
)
public class StdWayOfDocumentationHeader {
//class code goes here
}

3) To Make the annotations appear in Javadoc generated documentation

You must annotate @

AuthorOfProgram with @Documented
import java.lang.annotation.*; // import this to use @Documented
@interface AuthorOfProgram {
 String author();   //Annotation type element declarations    
 String date();    
  int currentRevision() default 1; 
}
Another example is as follows
1) @interface MyAnnotations {
 String whatIsThis();
}
2) @MyAnnotations (whatIsThis = "Description goes here") //Full value
     @MyAnnotations("Description goes here") //Single Element
     @MyAnnotations //Marker
public void myMethod() {
 //method implementation goes here
}

  • ANNOTATIONS USED BY COMPILER
  • @Deprecated
  • @Override
  • @SuppressWarnings

@Deprecated—the @Deprecated annotation indicates that the marked element is deprecated and should no longer be used. The compiler generates a warning whenever a program uses a method, class, or field with the @Deprecated annotation. When an element is deprecated, it should also be documented using the Javadoc@deprecated tag, as shown in the following example. Also, note that the Javadoc tag starts with a lowercase "d" and the annotation starts with an uppercase "D".

   // Javadoc comment follows     /**      * @deprecated      * explanation of why it was deprecated      */     @Deprecated     static void deprecatedMethod() { } } 

@Override—the @Override annotation informs the compiler that the element is meant to override an element declared in a superclass (overriding methods will be discussed in the the lesson titled "Interfaces and Inheritance").

   // mark method as a superclass method    // that has been overridden    @Override     int overriddenMethod() { } 
While it's not required to use this annotation when overriding a method, it helps to prevent errors. If a method marked with @Override fails to correctly override a method in one of its superclasses, the compiler generates an error.

@SuppressWarnings—the @SuppressWarnings annotation tells the compiler to suppress specific warnings that it would otherwise generate. In the example below, a deprecated method is used and the compiler would normally generate a warning. In this case, however, the annotation causes the warning to be suppressed.

   // use a deprecated method and tell     // compiler not to generate a warning    @SuppressWarnings("deprecation")     void useDeprecatedMethod() {         objectOne.deprecatedMethod(); //deprecation warning - suppressed     } 

Every compiler warning belongs to a category. The Java Language Specification lists two categories: "deprecation" and "unchecked." The "unchecked" warning can occur when interfacing with legacy code written before the advent of generics. To suppress more than one category of warnings, use the following syntax:

@SuppressWarnings({"unchecked", "deprecation"})
SYNTAX RULES
  1. Annotation declaration should start with an 'at' sign like @, following with an interface keyword, following with the annotation name.
  2. Method declarations should not have any parameters.
  3. Method declarations should not have any throws clauses.
  4. Return types of the method should be one of the following:
    • primitives
    • String
    • Class
    • enum
    • array of the above types