JSR 308 Prototype Implementation README

Version 0.1.1 (7 Jun 2007)

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

Contents:

• Introduction
• Differences from the OpenJDK compiler
  • The -typeprocessor command-line option
  • Writing annotations on types in a backward-compatible manner
  • Determining a diff against the OpenJDK compiler
• Contributing
  • How to report bugs
  • Credits

Introduction

This distribution contains the JSR 308 compiler, also known as the “prototype implementation” or “reference implementation”. JSR 308 is a backward-compatible extension of the Java language that permits annotations to appear on types.

The JSR 308 compiler is a modified version of the OpenJDK compiler for the Java 7 language. You may use this compiler as a drop-in replacement for the OpenJDK javac compiler or any other Java compiler.

The instructions for building, running, and testing the JSR 308 javac compiler are identical to those for the OpenJDK compiler. See the OpenJDK README file for those instructions.

Differences from the OpenJDK compiler

The JSR 308 compiler differs from Sun's OpenJDK javac compiler, on which it is built, in the following ways:

• The compiler source code has been modified to implement the JSR 308 specification (PDF, HTML), which permits annotations to appear on any occurrence of a type.
• The -typeprocessor command-line option, which runs an annotation processor after types have been resolved, has been added.
• Five 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.
  Note that not all tests remaining pass -- but all failing tests also fail for the OpenJDK compiler. The JSR 308 changes do not introduce any test failures..
• This documentation file has been included.

The -typeprocessor command-line option

The JSR 308 compiler adds the -typeprocessor command-line option for running annotation processors immediately after the compiler's attribution phase (also known as type resolution) instead of immediately before it. This is necessary for annotation processors that need completed symbols (which are determined by the attribute phase).

The -typeprocessor option is semantically similar to the standard -processor option: it is followed by a list of the (fully-qualified) class names of the annotation processors to run. The -typeprocessor option is functionally identical to -processor, except that annotation processors passed to the former are invoked at a later stage than those passed to the latter.

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.

Determining a diff against the OpenJDK compiler

The JSR 308 compiler is a modification of Sun's OpenJDK javac compiler. The version of OpenJDK on which the JSR 308 compiler is based is:

r174 (2007-02-07 20:23:37)

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-compiler
                   svn co https://openjdk.dev.java.net/svn/openjdk/compiler/trunk $VENDOR -r174 --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 -r174
                   

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 $JSR308
                   diff -urN -x .svn -x dist -x build $VENDOR $JSR308
                   

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:

• Any inconsistency between the JSR 308 compiler and the JSR 308 design (PDF, HTML).
• Any annotation-related problem.
• Any problem that occurs with the JSR 308 compiler but does not occur with the OpenJDK Java 7 compiler on which the JSR 308 compiler is built.

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

If you have any problems with the compiler, please let us know; we welcome bug reports and suggestions.

Problems that occur in the standard Java 7 compiler should be reported at http://bugs.sun.com/; use 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:

• Indicate exactly what you did. Show the exact commands (don't merely describe them in words). Don't skip any steps.
• Include all files that are necessary to reproduce the problem. This includes every file that is used by any of the commands above, and possibly other files as well.
• Indicate exactly what the result was (don't merely describe it in words). Also indicate what you expected the result to be — remember, a bug is a difference between desired and actual outcomes.
• Indicate which version of the JSR 308 compiler you are using. You can determine that by running javac -version.

Credits

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.