Annotation File Utilities

Contents:

• Motivation
  • External storage of annotations
  • Annotation File Utilities
• Installation
  • Building from source
• Using the Annotation File Utilities
  • Insert-annotations
  • Extract-annotations
  • Insert-annotations-to-source
• Feedback and bug reports
  • Changelog

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 and type annotations.

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.

• insert-annotations reads annotations from an annotation file and inserts them into a class file
• extract-annotations reads annotations from a class file and writes them out to an annotation file
• insert-annotations-to-source reads annotations from an annotation file and inserts them into a Java source file

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

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.7.0, 30 Oct 2014.

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

   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

3. Add the annotation-file-utilities directory to your path.
   • For Unix (including Linux and MacOS), add the directory to your PATH environment variable. If your shell is sh or bash, add to your ~/.bashrc or ~/.bash_profile file:

     export PATH=${PATH}:/path/to/annotation-tools/annotation-file-utilities/scripts

   • For Windows, add the directory to your 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.

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

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.

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.

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

Feedback and bug reports

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.

Changelog

The changelog describes what is new in each release.

Last revised: March 9, 2013