Annotation File Utilities

Contents:


Motivation

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

External storage of annotations

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 a forthcoming version of Java.

An annotation file conventionally has the extension .jaif (for Java Annotation Index File).

Annotation File Utilities

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.

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.


Installation

The following instructions assume either a Linux or Windows system using a command-line environment.

The current distribution is Annotation File Utilities version 3.4, released September 11, 2012.

  1. Download annotation-tools.zip.
  2. Creade a directory named annotation-tools by unpacking the distribution zipfile (a standard place to do this is in a directory ~/jsr308/:
    unzip annotation-tools.zip
  3. Add the annotation-file-utilities directory to your path.

Building from source

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.


Using the Annotation File Utilities

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

Insert-annotations

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.

Extract-annotations

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.

Insert-annotations-to-source

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.


Feedback

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.

Change Log

The changelog describes what is new in each release.


Last revised: June 18, 2011