Developed by Jaime Quinonez (jaimeq@mit.edu) for use in collaboration with JSR 308.
Contents:
Java annotations are meta-data about Java program elements, as in
“@Deprecated class Date {
... }”. 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 Specification” 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 standard Java SE 6 annotations and also the
extended annotations proposed in
JSR 308.
An annotation file
conventionally has the extension .jaif (for Java Annotation Index
File).
With three possible locations for annotations — source code, class files, and annotation files — one needs to be able to easily transfer annotations between these three file formats. 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. We 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 file
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 2.1.2, released April 28, 2008.
unzip annotation-file-utilities.zip
This command creates a directory named
annotation-file-utilities containing:
export PATH=${PATH}:/path/to/annotation-file-utilities/
setenv PATH=${PATH}:/path/to/annotation-file-utilities/
PATH system
variable by going to
Control Panel -> System -> Advanced -> Environment Variables PATH variable under “System variables”
and append to it the directory containing all the tools.
The annotation file utilities are pre-compiled (a jar file is included in the distribution), so most users will not need to compile it themselves.
Source code is provided in the workspace
directory. Compiling it requires the
Ant build system.
You can build a new distribution by running
ant zipfile in the workspace directory.
Alternately, you can run ant bin in any of the subdirectories
of workspace to recompile just part of 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 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).
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 mypackage/MyClass.java.with-annotations
will read all the annotations from indexFile.jaif, insert them
into their appropriate locations in mypackage/MyClass.java,
and write the results to
mypackage/MyClass.java.with-annotations. Run:
insert-annotations-to-source --help
for full usage information. Note that you must have the associated class mypackage.MyClass.class on your classpath for this tool to fully work.
Please send questions, comments, bug reports and feature requests to jsr308-bugs@lists.csail.mit.edu. For reporting bugs, please include exact instructions in how to reproduce a bug, including sending input files, so that we may resolve the issue quickly.
There are no known bugs at this time. Please report any bugs you encounter, along with instructions on how to reproduce them, to jsr308-bugs@lists.csail.mit.edu.
insert-to-annotations-sourceLast revised: April 28, 2008