This document supplements the OpenJDK compiler README file included in the Sun OpenJDK distribution.
Contents:
The JSR 308 “prototype implementation” (also called the “reference implementation”) is a version of the OpenJDK Java 7 platform implementation that has been updated to support JSR 308. JSR 308 is a backward-compatible extension of the Java language that permits annotations to appear on types.
You may use the JSR 308 implementation as a replacement for the
OpenJDK or any other Java implementation.
In particular, you may use the JSR 308 compiler as a drop-in
replacement for the OpenJDK javac
compiler or any
other compiler for the Java 7 language.
The "Building the compiler" section below contains instructions for building, running, and testing the compiler. (These are slightly different than those found in the OpenJDK compiler README.)
IDEs such as Eclipse have not yet been updated to support JSR 308. To use the JSR 308 compiler with Eclipse, write an Ant buildfile that compiles your project (using the JSR 308 compiler), then build by running Ant. Problem markers will show up in the Eclipse IDE as normal. (You will lose a few Eclipse features until its internal compiler is updated for JSR 308, however.)
The JSR 308 prototype implementation is a Java compiler that supports the JSR 308 specification (PDF, HTML), which permits annotations to appear on any occurrence of a type.
-typeprocessor
command-line optionThe JSR 308 compiler adds the -typeprocessor
command-line option for running annotation processors.
The -typeprocessor
option is semantically
similar to the standard -processor
option: either option is
followed by a list of the (fully-qualified) class names of the annotation
processors to run. An example (using the
NonNull checker) is:
javac -typeprocessor checkers.nonnull.NonnullChecker MyFile.java
Annotation processors specified using the -typeprocessor
option are invoked after the compiler's attribution phase (also known as
type resolution), giving the processor access to completed symbols. By
contrast, processors specified using the -processor
option are
invoked before the compiler's attribution phase.
Note: In the prototype implementation, the
-typeprocessor
and -processor
options are mutually exclusive and should not be used
simultaneously.
The prototype implementation of the JSR 308 compiler
allows annotations to be written in "/* */
"
(C-style) comments, without
whitespace between the comment delimiters and the
annotation name, e.g., /*@NonNull*/
.
This mechanism allows developers to use JSR 308 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 5 or
Java 6). This temporary mechanism will not
be part of the official Java language when JSR 308 is incorporated
into it.
The JSR 308 prototype compiler implementation differs from the design specified in the JSR 308 proposal in the following ways, which will be corrected in the future:
It can be difficult to build the entire OpenJDK. For example, to build on Linux requires a specific operating system version, and attempts to build on any other version are likely to fail. Therefore, we suggest the following approach:
PATH
with the location of the newly-installed
java
executable, and your JAVA_HOME
environment
variable to point to the top-level directory of the JDK 7 installation.
(The shell uses the PATH
variable to locate java
,
while Ant uses JAVA_HOME
.)
openjdk
directory when extracted.
ant
in
directory openjdk/j2se/src/share/opensource/javac
.
openjdk/j2se/src/share/opensource/javac/dist/bin
directory to the front of your PATH
environment variable.
Now, the javac
command invokes the JSR 308 Java compiler,
but uses the Java 7 OpenJDK for everything else.
javac -version
contains the
string jsr308
, such as javac 1.7.0-jsr308-0.2.2
.
javac 1.7.0-ea
, but you are using the
correct javac
binary, then it is possible that
tools.jar
is on your classpath. You should either remove
tools.jar
from your classpath, or else put
openjdk/j2se/src/share/opensource/javac/dist/lib/javac.jar
on your classpath before tools.jar
.
In the future, we will distribute binary versions of the JSR 308 prototype implementation, which will simplify the installation process.
This JSR 308 distribution differs from Sun's OpenJDK distribution, on which it is based, in the following ways:
openjdk/j2se/src/share/classes
) supports the JSR 308; it
permits annotations to appear on any occurrence of a type.-typeprocessor
command-line option, which runs an annotation processor
after types have been resolved, has been added to the compiler.javac
test cases are skipped by
the test runner due to failures caused by JSR 308
modifications. These test cases will be corrected and
re-enabled in a future release.build.xml
file in
openjdk/j2se/src/share/opensource/javac
has been
patched so that the compiler can be built separately from the
rest of OpenJDK.The JSR 308 distribution is a modification of Sun's
OpenJDK
javac
distribution. The version of OpenJDK on which the
JSR 308 distribution is based is:
r246 (Thu, 02 Aug 2007)
The following commands determine the differences between the JSR
308 compiler and the OpenJDK compiler.
The shell variable $VENDOR
refers
to the location of the unmodified source code and
$JSR308
refers to the location of the
extracted JSR 308 compiler distribution.
guest
):
export VENDOR=vendor-openjdk
svn co https://openjdk.dev.java.net/svn/openjdk/jdk/trunk $VENDOR -r246 --username guest
If you already have a checkout of the OpenJDK compiler, ensure that it is at the same revision as the modifications, using the following command in the $VENDOR directory:
svn update -r246
diff
commands to generate the
differences. The second shows the contents of new files,
whereas the first only reports that the new file exists.
diff -ur -x .svn -x dist -x build $VENDOR/j2se/src $JSR308/j2se/src
diff -urN -x .svn -x dist -x build $VENDOR/j2se/src $JSR308/j2se/src
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 JSR 308 prototype implementation 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. We will fix all reported bugs in the JSR 308 prototype implementation. Examples of bugs include:
The JSR 308 compiler is built on Sun's OpenJDK compiler. If you find a bug in the JSR 308 compiler, it might be due to a bug in the OpenJDK compiler (in which case it should be reported to Sun), or it might be due to the JSR 308 modifications (in which case it should be reported to the JSR 308 compiler implementers). 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 JSR 308 compiler, but not in the OpenJDK compiler, then please report it to us. Send your bug report to jsr308-bugs@lists.csail.mit.edu. This is not a mailing list 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
.
The JSR 308 compiler was implemented by Matthew M. Papi as a modification of the Sun OpenJDK compiler. See above for how to report bugs.
Differences from previous versions of the JSR 308 implementation may be found in the changelog.