Standard annotation types are those that are provided "out of the box" in Tiger. There are three of these, and all three are defined in the java.lang package. These annotation types can be used without any extra work on your part in your own programs.
The three standard annotation types that are pre-defined in Tiger are listed here, detailed briefly, and then covered more fully in the following labs:
NOTE
None of these have to be imported, as they are all in the "java.lang" package, and are automatically available.
java.lang.Override is used to indicate that a method overrides a method in its superclass.
java.lang.Deprecated indicates that use of a method or element type is discouraged.
java.lang.SuppressWarnings turns off compiler warnings for classes, methods, or field and variable initializers..
Here's an example of using the Override annotation type:
@Override
public String toString( ) {
return super.toString( ) + " [modified by subclass]";
}Here's a sample of using Deprecated:
@Deprecated public class Betamax { ... }And finally, here's SuppressWarnings in action:
@SuppressWarnings("unchecked")
public void nastyMethod( ) {
// body omitted
}I realize that I really haven't told you how these workthat's intentional. Now that you've seen each annotation in use, you should realize that each has an entirely different syntax. To get a handle on annotations, we'll have to delve into just a bit of theory, and then there are labs going into each of the standard annotations in detail. Buckle up for a moment, let's deal with some technical details, and then you'll be ready for some more practical instruction.
First, you need to understand the difference between an annotation and an annotation type. Taking the last part first, an annotation type is a specific name of an annotation, along with any default values and related information. You just saw three annotation types: Override, Deprecated, and SuppressWarnings. An annotation, then, uses an annotation type to associate some piece of information with a Java program element (methods, classes, variables, etc.). So your code might only use one annotation type, like Override, and yet have ten or fifteen annotations (if it used Override ten or fifteen times).
Annotation types can have values as wellnote that SuppressWarnings passed in the valued "unchecked", which would be used by the annotation type to process or store information. This passed-in value, along with any default values, all make up the annotation's members. This is where the name=value syntax comes in that I mentioned in the early part of this labit allows for an annotation's members to be set.
In addition to the three standard annotation types, there are three categories of annotations:
Marker annotations are used with annotation types that define no members. They simply provide information contained within the name of the annotation itself. An annotation whose members all have default values can also be used as a marker, since no information must be passed in. The syntax of a marker is simply:
@MarkerAnnotation
Single-value annotations have just a single member, named value. The format of a single-value annotation is:
@SingleValueAnnotation("some value")
A full annotation really isn't a category, as much as it is an annotation type that uses the full range of annotation syntax. Here parentheses follow the annotation name, and all members are assigned values:
@Reviews({ // Curly braces indicate an array of values
@Review(grade=Review.Grade.EXCELLENT, reviewer="df"),
@Review(grade=Review.Grade.UNSATISFACTORY, reviewer="eg",
comment="This method needs an @Override annotation")
})NOTE
There are no semicolons at the end of annotation lines.
With each category, there is a slightly different syntaxwhich is why each standard annotation type is used a little differently. Each of the following three labs will detail one of the standard annotation types, indicate the category it falls into, and give you further details about using that annotation type.
...tools like XDoclet (xdoclet.sourceforge.net) that already handle this sort of analysis, especially in enterprise programming. XDoclet already provides for much of the same information, reading metadata in source code and managing dependences (especially between the numerous source file listings required for EJBs), all through Javadoc parsing and some nifty class generation tools.
These tools are actually great examples of why annotations are needed. While XDoclet parses Javadoc, it can't figure out if the Javadoc syntax is correct or notif it finds matching tags, it uses them, and a misspelling is ignored without a peep. However, annotations are checked by the Java compilermeaning you can't have something like this in your code:
@Overridde // Note the misspelling
The compiler will complain about this misspelling, meaning you're protected not only at the code level, but at the annotation level as well. Now, take this extra checking, and pair it with the associations, analysis, and code generation that XDoclet does. Suddenly, a great tool becomes even better, even more user-friendly, even more a part of the standard suite of Java tools. In short, annotations could be the real breakthrough in making tools such as XDoclet a part of every programmer's toolkit.