For the latest version, see the Type Annotations (JSR 308) webpage.
Contents:
(If you are impatient, you can skip to the installation instructions.)
The Type Annotations compiler is a version of the OpenJDK Java 7 compiler that supports some extra features for type annotations. The OpenJDK Java 7 compiler already supports the Type Annotations (JSR 308) syntax, which permits annotations to appear on types. The extra features in the Type Annotations compiler make it possible for you write (and type-check) type annotations, while still permitting your code to be compiled with a Java 4/5/6 compiler.
You may use the Type Annotations compiler as a replacement for the
OpenJDK javac compiler or any other Java compiler.
Pluggable type-checking is made possible by the Type Annotations syntax. Pluggable type-checking is made easy by the Checker Framework. It includes several example type qualifiers that you can start using right away, and it enables you to create your own new compiler plug-ins that check user-defined type qualifiers.
The “Installing the Type Annotations compiler” section below contains instructions for installing, running, and testing the compiler.
IntelliJ IDEA (Maia release) supports the Type Annotations (JSR-308) syntax. Other IDEs (such as Eclipse and NetBeans) are being updated to support the Type Annotations syntax. For Eclipse, write an Ant buildfile that compiles your project using the Type Annotations compiler (and maybe does pluggable type-checking too), then build by running Ant. Problem markers will show up in the Eclipse IDE as normal. (You will lose a few Eclipse features, such as error checking as you type, until Eclipse's internal compiler is updated for to support type annotations.)
The easiest way to install the Type Annotations compiler, which is sufficient for most users, is to install the Checker Framework binary distribution.
The remainder of this section gives instructions for installing the Type Annotations compiler from source.
Note that while these instructions install the Type Annotations compiler, you do not have to make it your default compiler. For example, you could use the Type Annotations compiler only for running pluggable type-checkers. Also, you can use javac's -target argument to generate bytecodes that are compatible with earlier JVMs, so that you can work seamlessly with colleagues who are using an earlier version of Java.
If you use an Apple Macintosh (Mac OS X) computer, you must build the compiler from source.
Requirements: These instructions assume that Ant is installed. If you use an Apple Macintosh computer, you must build the compiler from source.
~/jsr308. We will call that directory
$JSR308.
.exe, .sh, or .bin
file that you downloaded and follow the directions.
JAVA_HOME environment variable to the top-level
directory of the JDK 7 installation /path/to/jdk1.7.0, and
augment your PATH with
/path/to/jdk1.7.0/bin. Example:
export JSR308=$HOME/jsr308 export JAVA_HOME=$JSR308/jdk1.7.0 export PATH=$JAVA_HOME/bin:$PATHThe shell uses the
PATH variable to locate java,
while Ant uses JAVA_HOME.
c:\Program
Files\Java\jdk1.7.0\) becomes the default.
If you wish to retain an older version of Java as the default, then
do the following:
javac -version, and the output should be javac
1.7.0-ea.
langtools directory. Do not do this inside the
JDK 7 installation (directory jdk1.7.0) that you
downloaded in the preceding step.
Example commands:
mkdir ~/jsr308 cd ~/jsr308 wget http://groups.csail.mit.edu/pag/jsr308/current/jsr308-langtools.zip unzip jsr308-langtools.zip
JAVA_HOME environment variable points to the
JDK you wish to patch, then patch your JDK 7 installation by running:
cd langtools/binary ant installThis step makes a backup copy of tools.jar and then modifies the original by copying some new .class files into it.
(You shouldn't need to undo this step, but you can do so by running ant uninstall which puts back the original version of the tools.jar file.)
If you get this error message:
c:\jsr308\langtools\binary\build.xml:29: Unable to rename old file (c:\Program Files\Java\jdk1.7.0\lib\tools.jar.patched) to new file (c:\Program Files\Java\jdk1.7.0\lib\tools.jar)
then rename the file manually using the shell. (This error occurs under Windows when some other process, such as an anti-virus program or another Java process, is accessing the given file.)
javac -versionand confirm that the output contains the string
jsr308, such as javac 1.7.0-jsr308-0.9.2.
jsr308
(e.g., javac 1.7.0-ea), but you are using the
correct javac binary (in langtools/dist/bin),
then it is possible that
tools.jar is on your classpath. You should either remove
tools.jar from your classpath, or else put
langtools/dist/lib/javac.jar and/or
langtools/dist/lib/javap.jar
on your classpath before tools.jar.
When updating to a newer version of the Type Annotations compiler, you only have to follow steps 2, 3, and 4. In other words, you only have to redo step 1 if you want a newer version of OpenJDK.
To build the Type Annotations compiler from source, replace step 3 from above by the following. Building from source is useful mainly for people who are developing compiler plug-ins or modifying the compiler itself. If you only want to use the compiler and plug-ins, it is sufficient to install the pre-compiled version.
Requirements: These instructions assume that Ant (version 1.7 or later) and JDK 6 are installed. You will use JDK 6 to compile OpenJDK, but will not use it thereafter. You can get JDK 6 from Sun or elsewhere. If you use an Apple Macintosh (Mac OS X), then depending on your hardware and operating system, you can either use Apple's implementation or SoyLatte.
JAVA_HOME environment file to the location of
your JDK 6 or 7 installation. Most likely it is already set for
Ant to work.
langtools/make:
cd langtools/make ant clean build-javac build-javap
langtools/dist/bin directory to the front of your
PATH environment variable.
The effect of the above commands is that the javac
command invokes the Type Annotations Java compiler and the javap
command invokes the Type Annotations javap, but the Java 7 OpenJDK
is used for everything else.
The new type annotations features (which appear in both OpenJDK and in the Type Annotations compiler) are:
langtools/src/share/classes) supports the Type Annotations
syntax. This syntax
permits annotations to appear on any occurrence of a type, not just on
declarations as the original Java 5 annotations (also known as JSR 175
annotations) did. For details of the syntax, see the Type Annotations
(JSR 308) specification
(PDF,
HTML).The Type Annotations distribution includes only the langtools
portion of OpenJDK. The Type Annotations compiler
makes no modifications in other parts of OpenJDK, and the
remaining parts of OpenJDK are not necessary to build and use the
Type Annotations tools.
This Type Annotations distribution differs from the langtools
portion of Sun's OpenJDK distribution
in the following ways:
The Type Annotations compiler (that is distributed by
researchers at MIT and the University of Washington) allows annotations to
be written in “/* */“ (C-style) comments, for example:
List</*@NonNull*/ String> strings;
There must be no whitespace within the comment. For additional information about this feature, see the Checker Framework Manual.
These mechanism allows developers to use type annotations while maintaining the ability to compile their code with an unmodified Java compiler, including compilers for earlier versions of the Java language (such as Java 4, Java 5, or Java 6).
A related mechanism, that also facilitates compatibility with compilers that do not support the Type Annotations syntax, is the ability to specify imported packages from the command line. It is also documented in the Checker Framework Manual.
The Type Annotations distribution is a modification of the
langtools portion of Sun's
OpenJDK
javac distribution.
The following commands determine the differences between the Type Annotations compiler and the OpenJDK compiler.
hg clone https://jsr308-langtools.googlecode.com/hg/ jsr308-langtools
hg pull; hg up
hg log | less" to find the last changeset with an author
other than mali or mernst. The changeset
identifier would be in format of:
450:143956db282e
hg diff to generate the diff.
hg diff -r450:tip
We welcome bug fixes, new features, type-checking plug-ins, and other
improvements.
All contributions to javac (annotation-related or not) should follow the
guidelines
for contributing to javac.
Any code contributed to javac or to the Type Annotations compiler is
contributed to Sun under Sun's Contributor Agreement
(SCA).
If you have any problems with the compiler, please let us know. We welcome bug reports and suggestions, and we want to help. We will fix all reported bugs in the Type Annotations compiler. Examples of bugs include:
The Type Annotations compiler is built on Sun's OpenJDK compiler. If you find a bug in the Type Annotations compiler:
In some cases (such as a problem with processing annotations on types), the responsibility is clearly with the JSR 308 modifications. Otherwise, please determine who is responsible for the bug using this procedure:
If the problem is present in the Type Annotations compiler, but not in the OpenJDK compiler, then please report it to us by creating a new issue in the issue tracking system. (Search the issue tracker first, to avoid reporting a duplicate. But feel free to augment an existing issue with more information.) The issue tracker is not intended for general support or questions.
Please ensure that your bug report is clear and that it is complete. Otherwise, we may be unable to understand it or to reproduce it, either of which would prevent us from fixing the bug. Sun has a description of how to write a helpful bug report. Here are some crucial points:
javac -version.
Finally, thanks for reporting the bug!
The Type Annotations compiler was implemented by Matthew M. Papi and Mahmood Ali as a modification of the Sun OpenJDK compiler. See above for how to report bugs.
Differences from previous versions may be found in the changelog.