New release of the Type Annotations (JSR 308) Specification

[Michael Ernst]

A new version of the Type Annotations (JSR 308) specification is available.

You can find it in PDF and HTML at these URLs:

http://types.cs.washington.edu/jsr308/specification/java-annotation-design.pdf

http://types.cs.washington.edu/jsr308/specification/java-annotation-design.html

This is the first release of the specification in nearly two years, and it contains significant changes.  The changelog appears at

http://types.cs.washington.edu/jsr308/specification/jsr308-changes.html

and the most recent entry appears below.

        -Mike

Annotation syntax changes:

• New receiver syntax. It is permitted to write an explicit first formal parameter for the method receiver (this), which has no run-time effect nor any purpose other than serving as a place for the receiver annotation. Then, no special case for receiver annotations is needed. For example, what was previously written as

    public String toString() @Readonly { ... }

  is now written as

    public String toString(@Readonly MyClass this) { ... }

  The syntax enables annotations on type parameters, outer this types, etc.
• Annotations are not permitted on class literals, nor arrays thereof.
• A type annotation on a nested type before the type's simple name, as in Map.@NonNull Entry.
• If an annotation has no @Target meta-annotation, then it applies only to the ElementTypes that were supported in Java SE 5. An annotation that is applicable to both types and declarations (which would be bad style) is permitted to be written on a void-returning method.

Classfile changes:

• Rename extended_annotation to type_annotation.
• Add a class file format for annotations on static nested classes.
• Change the class file format for exception parameters (catch clauses).
• Remove wildcard_bound and wildcard_bound_target. Wildcards are instead expressed in the location array used for type arguments, array element types, and static nested types.
• Make typeparam_bound_target reserve an index for an implicit type variable upper bound of java.lang.Object.
• Change the target_type field of type_annotation from u1 to u2, to permit future expansion and to improve word-alignment of the classfile.
• Renumber all the enumeration constants of target_type.
• Bug fix: Java forbids type parameters in catch, not in throws.

Specification clarifications:

• Clarify the difference between type uses and other type names that appear in Java code. Examples of type names that are not type uses areimport statements and class constants such as int.class. Type annotations cannot be written on these type names. This distinction now appears in the Java Language Specification as well.
• Clarify that for a constructor result, there is no source code syntax for annotating its type parameters. Constructor result annotations are stored in the classfile the same place as method return type annotations, using the METHOD_RESULT TargetType.
• Improve discussion of compiler optimizations that remove an annotated cast.
• The classfile representation of annotations does not depend on the source code representation. Annotations that are implicit in the source code are present in the classfile. Classfile indexing is with respect to the complete type, regardless of abbreviated types written in source code. Classfile indexing assumes that all optional extends Object clauses are present.

Other specification document changes:

• Change grammar productions to be compatible with the grammar in chapter 18 of the Java Language Specification, Java SE 7 version. Remove section 5, merging the two lists of grammar changes into one list. Separate the declaration annotation on type parameters from the list of type annotations.
• Remove two incorrect examples of inner class syntax.
• Add an appendix "Interactions with other Java SE 8 language changes".
• Remove the "Other possible extensions to Java annotations" appendix. It will be maintained as a separate document. Also remove the "Logistical matters" appendix (Appendix E). Move all discussion of compiler modifications into an appendix. Eliminate Appendix B (discussion of changes), distributing its parts to section 2 (description of changes) and to Appendix A (motivation).
• Change "Java SE 7" to "Java SE 8". Change "Sun" to "Oracle". Update URLs.

FAQ:

• Add section "What is the relationship between the Type Annotations compiler and the OpenJDK compiler?"