JSR 308 Prototype Implementation README

Version 0.2.2 (16 Aug 2007)

This document supplements the OpenJDK compiler README file included in the Sun OpenJDK distribution.

Contents:

Introduction

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

Features of the JSR 308 prototype implementation

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.

The -typeprocessor command-line option

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

Writing annotations on types in a backward-compatible manner

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.

Differences from the JSR 308 proposal

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:

Building the compiler

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:

  1. Download a JDK 7 (not JRE 7) binary snapshot, and follow the installation instructions. Be sure to update your 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.)
  2. Download the JSR 308 prototype implementation, and unpack it (somewhere different than the JDK 7 installation you downloaded in the preceding step). By default, the archive will create a openjdk directory when extracted.
  3. Compile only the JSR 308 compiler, by running ant in directory openjdk/j2se/src/share/opensource/javac .
  4. Add the 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.
  5. Confirm that the output of javac -version contains the string jsr308, such as javac 1.7.0-jsr308-0.2.2.
    If the output is 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.

Differences from the OpenJDK distribution

This JSR 308 distribution differs from Sun's OpenJDK distribution, on which it is based, in the following ways:

Determining a diff against the OpenJDK distribution

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.

  1. If you do not have a checkout of the OpenJDK compiler, obtain one (use an empty password for username 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
      
  2. Use one of these 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
      

Contributing

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

How to report bugs

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:

  1. Obtain a copy of version 246 of the OpenJDK compiler, using the commands in the diff section of this document.
  2. Try your test case using the OpenJDK compiler. If the problem is present, then search the bug database (use the “Java” category). If the problem is not in the bug database, then report your bug to Sun, using category “Java” and subcategory “compiler”.

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:

Credits and changelog

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.