Previous |
Next |
Annotations were a featured introduced with Java 5 (JDK 1.).
Java 6 API
http://java.sun.com/javase/6/docs/api/java/lang/annotation/Annotation.html
http://java.sun.com/docs/books/tutorial/java/javaOO/annotations.html
According to Kyle Downey
“annotations are code fragments that elaborate upon and describe Java classes, methods, and fields. They're implemented as a special kind of interface and can be packaged, compiled, and imported like any other class.”
http://www.onjava.com/pub/a/onjava/2004/10/06/anno1.html
Annotations give a programmer the ability to create their own “meta data”, i.e. data about data. If that sounds peculiar, one of the best analogies is the idea of JavaDoc comments. As you probably know Java doc comments are a form of standard code comment that is designed to be pulled out and used to create API documents. In fact the standard Java API docs that are used to see how parts of the Java system work are all automatically created from Java doc comments in the source code. Thus to give an example
/** * This is a <b>doc</b> comment. * @see java.lang.Object */
Note that Java doc is not actually part of the program, whatever you do to change or update the Javadoc will not change how the program runs, because it is information about the program not part of the program itself. Annotations extend this idea so you can create your own meta information. You may never create your own annotations but you will almost certainly use ones that have been created by other people, so it is worth while seeing how and why they are created.
Annotations are particularly useful in situations where external configuration files are used. There has been a huge growth in Java frameworks and they almost all use xml based configuration files. These files contain meta information, information about the program, not code for the program itself. One of the problems with configuration files is that programmers have to edit two sets of code and need to understand the syntax of both types of code.
Thus Java EJB applications must have access to a a correctly configured xml file before it they will run. The use of annotations allows the default configuration to be embedded within the Java source code and removes the need to create an external file. Note that I said “default configuration”, because one of the benefits of an external configuration file is that can be changed without the need to recompile the source. This can be a significant benefit because compiling a large application can be much more complex than simply typing javac programname.java from the command prompt.
As the use of EJB's is beyond the scope of an introduction to Java I will cover the use of some annotations that almost any style of Java programming can use. There are three annotation types that are defined by the language specification and which you will almost certainly come across no matter what type of Java programming you do. These are
@Deprecated
@Override
@SuppressWarnings
The meanings of these annotations should be fairly obvious.
http://java.sun.com/javase/6/docs/api/java/lang/SuppressWarnings.html
Suppress warnings is an instruction to the compiler to suppress warnings. Generally a compiler gives warnings for good reason and its a good idea not to ignore them. However you might for some reason want to suppress compile time errors. For example if you were compiling some old pre JDK 1.5 Java code that uses collections you will probably get some compile time error messages about unsafe operations. This is because JDK 1.5 expects you to use parameterised types with collections so the collection knows the type of the objects added. It might make sense to move your code to the new safer style, but in the meantime it is very useful to be able to suppress these warnings so the real warnings do not get lost “in the noise.
If you compile the following code
import java.util.*;
public class WarningSuppress {
public static void main(String argv[]){
WarningSuppress ws = new WarningSuppress();
ws.collectionTest();
}
public void collectionTest() {
List l = new ArrayList();
l.add("one");
l.add("two");
}
}You will get a compile time error something like
Note: C:\Documents and Settings\marcus\nbprojects\Annotations\src\com\examulator\WarningSuppress.java uses unchecked or unsafe operations. Note: Recompile with -Xlint:unchecked for details.
However if you modify the code to include
@SuppressWarnings("unchecked")on the line immediately before the collectionTest method. Now when you compile the code the warnings about unchecked operations will be suppressed.
http://www.onjava.com/pub/a/onjava/2004/10/06/anno1.html
The Override and Deprecated annotations are like the ability to have a comment that also affects compilation. Thus by default you expect to use them as a comment to tell other programmers that the methods should be overridden or that the method is deprecated. If however another programmer ignores the annotations there will be a compile time error. Thus if you try to compile the following code.
public class OverTest{
@Override
public void shouldbeover(){}
}You will get the following error message.
OverTest.java:2: method does not override or implement a method from a supertype @Override ^ 1 error
The following code illustrates how the Deprecated annotation works.
public class DepTest{
public static void main(String argv[]){
OtherClass oc = new OtherClass();
oc.depMethod();
}
}
class OtherClass{
@Deprecated public void depMethod(){}
}
If you attempt to compile this code you will get the following error message.
C:\Documents and Settings\marcus>javac DepTest.java Note: DepTest.java uses or overrides a deprecated API. Note: Recompile with -Xlint:deprecation for details.
It is very common and probably a good idea to use both the Deprecated annotation and the deprecated JavaDoc comment together, note the JavaDoc comment begins with a lower case letter d.
The three annotations described are marker annotations in that they don't take any additional information. For example it might have been nice if the Deprecated annotation took a parameter to explain why the method was deprecated or under when it was likely to be removed entirely from the API.
Programmers can define their own annotations but many programmers will manage to write very large amounts of code without ever creating any annotations of their own. Annotations are a key part of many technologies introduced since JDK 1.5. For example EJB3 was a huge change by contrast with EJB2.X, and part of that change was a move to using annotations. Doing even the most trivial task with EJB2.X involved the creation of a myriad of XML configuration files. The creation of these files was such a chore that there was a cottage industry of creating utilities for generating those files. With EJB3 the configuration information can be embedded in the source code via annotations. Note that I said it can be embedded, the annotations can be effectively overridden by XML files, and this means that you can re-configure an application without having to recompile the source code.
With EJB3 annotations can be used instead of XML configuration files
Overrides
Documented
Inherited
Retention
Target
Previous |
Next |