Java 1.5 Tiger A Developers Notebook [Electronic resources] نسخه متنی

6.1 Using Standard Annotation Types

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.

6.1.1 How do I do that?

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.

Override

java.lang.Override is used to
indicate that a method overrides a method in its superclass.

Deprecated

java.lang.Deprecated indicates that use of a method or element
type is discouraged.

SuppressWarnings

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.

6.1.2 What just happened?

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.

6.1.3 What about...

...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.