JSR 308: Annotations on Java Types

JSR 308, “Annotations on Java Types”, enriches the Java annotation system. It permits annotations to appear in more places than Java 6 permits; one example is generic type arguments (List<@NonNull Object>). These enhancements to the annotation system require minor, backward-compatible changes to the Java language and classfile format. These changes are planned to be part of the Java 7 language. At the 5th annual JCP Program Awards (in May 2007), JSR 308 received the Most Innovative Java SE/EE JSR of the Year award.

This webpage documents the current status of the JSR 308 proposal and its progress through the formal approval process. You can help to shape JSR 308!

Contents:

• Download
• How to help
  • Process
  • Scope

Download

• The JSR 308 proposal (PDF, HTML) describes the extensions to the Java language and classfile format.
  The changelog lists changes that have been made to the document. The original proposal appears at the Java Community Process (JCP) webpage for JSR 308, but it is out of date; please use the current proposal (PDF, HTML) instead.
• The JSR 308 prototype implementation is a slightly modified version of the OpenJDK Java platform. The JSR 308 compiler is fully backward-compatible: you can use it in place of javac without any change in behavior, except that you will be permitted to place annotations in more locations and to use type-checking plug-ins that take advantage of those new locations.
  • Stable release, 0.6.1, 26 Apr 2008
    • Download: jsr308-langtools.zip (includes source, platform-independent binary, and documentation)
    • Documentation: README-jsr308.html
    • Changelog: changelog-jsr308.txt
• Compiler plug-ins (checkers) demonstrate the usefulness of the new annotations. These plug-ins are bug-finding and verification tools. Currently, plug-ins for four type systems are distributed, for preventing and detecting null pointer errors, incorrect uses of equality operations, and side effect errors. There is a fifth plug-in for any type system that has no special semantics (the user specifies the annotations for the type system on the command-line), and we also distribute a framework for writing plug-ins.
  The framework and checkers are not officially part of JSR 308. However, they are useful in their own right and show the utility of the JSR 308 annotations; they are examples others can use as inspiration when writing additional plug-ins; and use of them helps to validate the JSR 308 design and implementation. If you have written an additional plug-in, let us know so we can link to it from here or include it in the checkers distribution.
  • Stable release, 0.6.1, 26 Apr 2008
    • Download: jsr308-checkers.zip (includes source, platform-independent binary, tests, and manual)
    • Documentation: the checkers manual (PDF, HTML)
    • Changelog: changelog-checkers.txt
  • A technical report describes case studies in which all 4 checkers found bugs in real programs.
• Annotation file utilities extract annotations from, and write annotations to, .java and .class files. This package also provides a representation (called an “annotation file”) for annotations that is outside the source code or the .class file. The tools support all of the JSR 308 annotations, and all pre-existing Java annotations.
  • Download: annotation-file-utilities.zip (28 April 2008)
  • Documentation is included in the zip archive.
• Inference tools
  • For @NonNull: The JastAdd Extensible Compiler for Java supports the JSR 308 syntax. It includes, for example, an inference tool and checker for @NonNull.
    • JastAdd homepage
    • Non-null checker and inferencer
  • For @Nullable: The Daikon invariant detector can be used to soundly infer some @Nullable annotations. Each annotation that it infers is correct, but the programmer may still need to write some additional @Nullable annotations. Inference of @Nullable annotations is particularly useful when running the null reference checker with a default annotation of @NonNull or non-null-except-locals.
    • Daikon homepage
  • For @ReadOnly (Javari): The Javarifier tool infers Javari annotations (both @ReadOnly and others).
    • Javari webpage

How to help

You can help to shape and improve this JSR, and thus to shape and improve Java. Here are some ways to do so.

• Read the JSR 308 proposal (PDF, HTML).
• Download the prototype implementation and the type-checking plug-ins that will help you detect errors in your code. We welcome bug reports, suggestions, bug fixes, new features, additional plug-ins, or other improvements to the prototype implementation.
• Participate in discussions. Join the jsr308@lists.csail.mit.edu mailing list, where all issues regarding the annotation design are discussed and decided. Also see the archives.
  Another mailing list, jsr308-statements@lists.csail.mit.edu, is specifically for the discussion of annotations on statements. A proposal is being formulated. Also see its archives.
  

Process

Discussions regarding JSR 308 will be open and transparent: any interested party will be permitted to participate, decisions will be made by consensus among all discussants (to the greatest extent possible), and discussions will be publicly archived. The Java Community Process requires that an expert group formally approve the JSR at each stage. The expert group is by necessity small, but we expect that the the broader public discussions will hash out most issues. The expert group members will participate in those discussions, and will only decide issues on which the group cannot obtain consensus.

The public mailing list for JSR 308 discussions is jsr308@lists.csail.mit.edu. You can subscribe at https://lists.csail.mit.edu/mailman/listinfo/jsr308/. Anyone can view the archives.

Only subscribers can post to the mailing list. When posting, please act professionally and courteously. For example, your arguments should be technical, specific, and based on logic; do not rely on your status or past accomplishments to convince others, and do give specific examples rather than vague descriptions. As another example, it is perfectly acceptable to criticize a technical proposal, but do not make personal attacks. Obviously, you should read the current proposal (and, preferably, try out the prototype implementation) before posting to the mailing list.

Scope

Any improvement to Java's annotation system is within bounds. The JSR is titled “Annotations on Java types” to avoid a vague and non-specific title such as “Extending Java's annotation system” or “Improvements to Java annotations”, and because we expect that most of the extensions will enable annotations on types. However, non-type-related improvements to annotations are within scope and will be considered. Some examples include permitting multiple instances of a given annotation at one location, and permitting annotations on statements.

The JSR proposal contains a fairly detailed technical proposal, and supporting documents develop that proposal further. However, all issues, including those for which the JSR lays out a proposed solution, are open for discussion. We expect that discussions will improve on various points of the initial proposal. The concrete proposal is presented, not to foreclose debate and improvement, nor as a fiat that the expert group members are required to endorse, but as a starting point for discussion. We provided this starting point because it is often easier to improve upon an existing proposal than to start from a blank slate.

Last updated: April 17, 2008