Summary

Extend the set of annotatable locations in the syntax of the Javaprogramming language to include names which indicate the use of a typeas well as (per Java SE 5.0) the declaration of a type.

Goals

Allow development of useful pluggable type checkers that refine Java'sbuilt-in type system.

Non-Goals

Standardization of pluggable type checkers.

Success Metrics

• Three major pluggable type checkers built on Java SE 8 with aframework such as Ernst's "Checker Framework".

• Possibly, application of at least one annotation scheme (e.g. forcontrolling null values) to parts of the JDK 8 codebase. This might(or might not) entail standardizing the definition of usefulannotation types (e.g. @Nullable) in Java SE.

Motivation

Java's annotation system has been an unquestioned success. Programmerscan write annotations on type names which appear in the declaration ofvariables, methods, and classes, which are then read by enterpriseframeworks for configuration purposes and by compilers/IDEs forsoftware quality purposes. Annotations allow boilerplate to be removedfrom code, and enable basic errors to be detected at compile-time.

Annotations on type uses, not just type declarations, enable errordetection by "pluggable type checkers" which strengthen and refineJava's built-in type system. The strengthened type system prevents, atcompile-time, the kind of software quality errors which wouldotherwise manifest themselves at run time. Examples include nullpointer errors, side effects on immutable data, race conditions,information leakage, and non-internationalized strings.

Description

JSR 308 makes targeted, low-level changes to the grammar of the Javalanguage to allow annotations on the names of types in most placesthose names can be used. This includes the names of types occurring inJava SE 7 language constructs like try-with-resources and multi-catch.

JSR 308 defines new attributes for the JVM class file format to storethese annotations on type names. Finally, it makes targeted changes tothe java.lang.reflect and javax.lang.model API so that annotations onspecific instances of type names can be retrieved.

Alternatives

• Idiomatic compile-time software quality can be assessed by toolslike FindBugs without programmer-supplied annotations.

• Notation that suggests an annotation could be placed in /* */-stylecomments adjacent to a type name, thus "hiding" the "annotation"from the language proper. This increases visual clutter and stillnecessitates class file and reflection changes.

Testing

• JCK tests on newly-annotatable constructs of the Java language,newly-generated class file attributes for annotated constructs abovethe method body level, and the new reflection API.

• SQE tests on newly-generated class file attributes for annotatedconstructs below the method body level. (Method body compilation iscompiler-specific and hence not standardized, so annotations onconstructs within method bodies are outside JCK's scope.)

• SQE tests are possible on individual pluggable type checkers, butthey are not part of JDK 8 or Java SE 8.

Risks and Assumptions

• Risk: That the broad Java development community is not interested indeveloping or using pluggable type systems.

• Assumption: That the utility of pluggable type checking is worthmaking significant changes to the Java grammar, class file, andAPI. (In addition to annotations on type uses, JSR 308 makesimprovements to annotations on type declarations which by commonconsent should have occurred in JSR 175. These improvements do notby themselves justify or predict the broader changes in JSR 308, butby the same token, the improvements are unlikely to occur without308's "sponsorship".)

Impact

• Other JDK components: If annotated for a specific Checker.
• Compatibility: Any Java language or class file parser.
• Documentation: javadoc must display annotations on type uses.
• TCK: Language, class file, and reflection changes.