Contents:
Java annotations are meta-data about Java program elements, as in
“@Deprecated class Date
{ ... }
” or “List<@NonNull String>
”.
Ordinarily, Java annotations are
written in the
source code of a .java
Java source file. When
javac
compiles the source code, it inserts the annotations in
the resulting .class
file (as
“attributes”).
Sometimes, it is convenient to specify
the annotations outside the source code or the .class
file.
The document
“Annotation File Format Specification” (PDF, HTML)
defines a textual format for annotations,
and it also motivates reasons why such a file format is necessary in
addition to the .java
and .class
formats. The
file format supports both the declaration annotations introduced in Java 5, and also the
type annotations that
will appear in Java 8.
An annotation file
conventionally has the extension .jaif
(for Java Annotation Index
File).
Programmers need to be able to transfer annotations between the three possible locations for annotations — source code, class files, and annotation files. Programmers will want to extract annotations from source and class files to an annotation file in order to easily read annotations, while various tools will only read annotations from source and class files. The Annotation File Utilities provide three tools to read and write annotation files.
insert-annotations
reads annotations from an annotation file
and inserts them into a class fileextract-annotations
reads annotations from a class file
and writes them out to an annotation fileinsert-annotations-to-source
reads annotations from an
annotation file and inserts them into a Java source fileA diagram showing the interactions betweeen these tools is below.
There is no
extract-annotations-from-source
tool: one can
compile the source code and then use
extract-annotations
to read the annotations from the class
file.
The following instructions assume either a Linux or Windows system using a command-line environment.
The current distribution is Annotation File Utilities version
3.6.5, 02 Jun 2014.
annotation-tools
by
unpacking the distribution zipfile (a standard place to do this is in a
directory ~/jsr308/
):
unzip annotation-tools.zip
The annotation-tools
directory must be in the parent directory (for example, in ~/jsr308/
) of the jsr308-langtools
directory (available at http://types.cs.washington.edu/jsr308/).
Alternatively, Unix (including Linux and MacOS) users may set the LANGTOOLS
environment variable to
the location of the jsr308-langtools
directory:
export LANGTOOLS=/path/to/jsr308-langtools
annotation-file-utilities
directory to your path.
export PATH=${PATH}:/path/to/annotation-tools/annotation-file-utilities/scripts
PATH
system
variable by going to
Control Panel -> System -> Advanced -> Environment Variables
From there, find the PATH
variable under “System variables”
and append to it the directory path\to\annotatation-tools\annotation-file-utilities\scripts
.
The annotation file utilities are pre-compiled (a jar file is included in the distribution), so most users do not need to compile it themselves.
There are two ways to obtain the source code. Source code is provided in the distribution. Alternately, see the source code repository at http://code.google.com/p/annotation-tools/.
To compile, run
ant jarfile
from the annotation-file-utilities
subdirectory. If the javac
and java
programs are
not on your execution path, see the notes near the top of
annotation-file-utilities/tests/Makefile
.
To use the tools, simply run them from the command-line with the
appropriate arguments. The following instructions are for running the
tools on a Linux/Unix/MacOS machine.
The tools work identically on Windows, except
the extension .bat
needs to be appended to the tool name (for
example, Windows users would execute insert-annotations.bat
instead of insert-annotations
).
For all the tools, arguments starting with a single
‘@
’ are recognized as argument files
(argfiles
), the contents of which get expanded into the
command line. (Initial @@
represents a literal
@
in the argument text.) For additional details of argfile
processing, refer to Oracle's
javac
documentation.
To insert annotations specified by an annotation file into a class file, use the insert-annotations tool. Running:
insert-annotations mypackage.MyClass indexFile.jaif
will read in all the annotations from the annotation file
indexFile.jaif
and insert those annotations pertaining to
mypackage.myClass
into the class file for
mypackage.MyClass
, outputting the final class file to
mypackage.MyClass.class
in the present working directory.
Note that the class file for mypackage.MyClass
must be located
on your classpath. Run:
insert-annotations --help
for full usage information.
To extract annotations from a class file and write them to an annotation file, use the extract-annotations tool. Running:
extract-annotations mypackage.MyClass
will locate the class file for mypackage.MyClass
, read all
annotations from it, and write the results in annotation file format to
mypackage.MyClass.jaif
in the present working directory. Note
that mypackage.MyClass
must be located on your classpath.
Run:
extract-annotations --help
for full usage information.
To insert annotations specified by an annotation file into a Java source file, use the insert-annotations-to-source tool. Running:
insert-annotations-to-source indexFile.jaif mypackage/MyClass.java
will read all the annotations from indexFile.jaif
, insert them
into their appropriate locations in mypackage/MyClass.java
,
and write the results to annotated/mypackage/MyClass.java
.
For full usage information, run:
insert-annotations-to-source --help
If you wish to insert annotations into method bodies, you must have the
associated class mypackage.MyClass.class
on your classpath.
You can insert annotations on class/field/method declarations and
signatures without the class on your classpath.
Your source code needs to contain the locations that your
.jaif
file references. In particular, if the
.jaif
file contains annotations for a type parameter, but the
source code uses a raw type, then you will get an error such as
Found class Edge, but unable to insert @checkers.nullness.quals.Nullable: @checkers.nullness.quals.Nullable (nl=true) @ [GenericArrayLocationCriterion at ( [TYPE_ARGUMENT(0)] ), ...
In this case, you should add type arguments, such as changing
public void pushNonezeroRing(Stack stack, Hashtable seen) {
to
public void pushNonezeroRing(Stack<Edge> stack, Hashtable<Edge, ?> seen) {
To submit a bug report or request a new feature, use the issue tracker. When reporting a bug, please include exact instructions in how to reproduce it, and please also attach relevant input files. This will let us resolve the issue quickly.
You can also reach the developers at annotation-tools-dev@googlegroups.com. But please use the issue tracker for bug reports and feature requests.
The changelog describes what is new in each release.
Last revised: March 9, 2013