Java Reference
In-Depth Information
Chapter 15. Annotations
I don't like spinach, and I'm glad I don't, because if I liked it I'd eat
it, and I just hate it.
Clarence Darrow
The source code for our programs is usually accompanied by copious
amounts of informal documentation that typically is contained within
comments in the source code file. For example, many organizations have
a standard preamble that they place at the top of class source files that
contains things like copyright information, the programmers name, the
date the class was created, the date the class was last modified, the cur-
rent revision number, and so forth. Other comments may reflect intended
usage of a class or a method, or usage limitations, such as documenting
that the instances of a class are not thread-safe and so shouldn't be used
concurrently. Other comments may be provided for processing by extern-
al tools that assist in the management and deployment of an application,
such as version control in a source code management system, or deploy-
ment descriptors on how a class should be managed by an application
server. These comment-based annotations serve a useful purpose, but
they are informal and ad hoc. A better way to document these things is
to annotate the program elements directly using
annotation types
to de-
scribe the form of the annotations. Annotation types present the inform-
ation in a standard and structured way that is amenable to automated
processing by tools.
While this chapter presents the syntax and semantics of using annota-
tions and defining annotation types, it can't tell you what annotations to
use when because very few such annotations exist within the language.
The annotations you use will be those supported by the tools in your de-
velopment or deployment environment. Annotation is centered on types
in the package
java.lang.annotation
, and the standard types introduced
in this chapter come from this package.
