Changelog for Type Annotations (JSR 308) specification

This webpage lists changes made to the specification for Type annotations (JSR 308). The current stable version of the specification is available on the web (PDF, HTML).

2 May 2013

Grammar changes:

• Refactor JLS grammar to clarify that throws and catch clauses contain type uses that can be annotated, even though type parameters and arrays are forbidden in such locations. See the productions for QualifiedType, UnannQualifiedType, and QualifiedTypeList.

Classfile changes:

• Remove unused target_info method_reference_target.

Clarifications:

• Give examples of interaction between multiple @Target meta-annotations and fully-qualified type names.
• Explain why instanceof uses offset_target but cast uses type_argument_target.
• Move examples of classfile annotations, which are not normative, into an appendix so that Section 3 contains only normative text.

1 April 2013

Grammar changes:

• Add missing modified grammar productions for AnnotationTypeElementRest and LocalVariableDeclarationStatement.

Classfile changes:

• Fix bug in type_path_entry struct definition comments.

Clarifications:

• No dynamic dispatching occurs on the receiver of an inner constructor.
• Explain the rationale for the syntax java.lang.@NonNull String, as opposed to java.lang.@NonNull String.
• Explain why declaration annotations on a type parameter appear in the classfile in type_annotation elements rather than annotation elements.
• The receiver parameter is not persisted as a formal parameter in the bytecode.
• Remove text that says no changes are made, to reduce confusion and make it easier to integrate the text into the JLS.

Advice:

• In locations where all are permitted, type annotations should appear immediately before the type, after declaration annotations and modifiers.

15 March 2013

Classfile changes:

• Type annotations on the body of an initializer appear with the initializer code, not with the field being initialized.
• Change method_reference_receiver to method_reference, and change constructor_reference_receiver to constructor_reference.
• Change invocation_type_argument_target and method_reference_type_argument to type_argument_target.

Clarifications:

• Clarify the meaning of the receiver of an inner class constructor.

2 February 2013

Annotation syntax changes:

• In a qualified type, the type annotations appear before the simple name, not before the package names. For example, a programmer writes package1.package2. @Annotation SimpleName rather than @Annotation package1.package2.SimpleName.

Classfile changes:

• Change attribute_length from u2 to u4, for consistency with other attributes.
• Change target_type from u2 to u1; with less than 40 values currently used, the likelihood that more than 256 will be needed seems remote.
• Renumber target_type constannts to make uses within code blocks start at 0x40, and to number by ones instead of by twos.
• Move annotations that target instructions from method_info structure to Code attribute.
• In type_annotation structure, put the new JSR 308 fields at the beginning, not the end.
• Change the representation of compound types (parameterized, wildcard, array, and nested types), which have multiple annotatable parts. The path through the compound type, to the annotated part, is now specified by a type_path structure rather than a location_length and location field. This eliminates the need for the odd-numbered target_type values and also makes parsing easier.
• Annotations that target instructions must be sorted.
• Add new target_type constants, to support lambda: LAMBDA_FORMAL_PARAMETER and METHOD_REFERENCE_TYPE_ARGUMENT
• Handle the fact that Lambda allows a cast to an intersection type: use a single classfile representation for casts and type arguments. Also use a single classfile representation for instanceof, new, and constructor/method reference receivers. Renumber target_type for consistency.
• Rename target_type structure and field names.
  • §3.2
    TYPECAST → CAST
NEW_TYPE_ARGUMENT → CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT
METHOD_TYPE_ARGUMENT → METHOD_INVOCATION_TYPE_ARGUMENT
  • §3.3.1
    typeparam_target → type_parameter_target
param_index → type_parameter_index
  • §3.3.2
    type_index → supertype_index
  • §3.3.3
    typeparam_bound_target → type_parameter_bound_target
param_index → type_parameter_index
  • §3.3.5
    methodparam_target → method_parameter_target
parameter_index → method_parameter_index
  • §3.3.6
    exception_target → throws_target
type_index → throws_type_index
  • §3.3.10
    typearg_target → invocation_type_argument_target
type_index → type_argument_index
• The VM is not responsible for validating legality of all the new classfile constructs that do not affect runtime behavior.
• The class file changes apply to class file version 52 and higher.

Compilation:

• Explain how annotations are copied from an anonymous class to its desugaring.

Clarifications:

• Inferred type annotations (such as at the "diamond" in a class instance creation expression) are not stored in the class file.
• Implicit type uses are not annotatable.
• Example of syntax and semantics for multiple receivers on inner class methods.
• It is not permitted to write a declaration annotation on the receiver (this) formal parameter declaration.
• It is impossible to annotate the receiver of an anonymous class constructor or method.

Removed text from appendices:

• Removed Appendix B, "Interactions with other Java SE 8 language changes"
• Reduced Appendix C, "Discussion of tool modifications"
• Merged Appendix D, "Related work", into Appendix A

3 July 2012

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 are import 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?"

29 July 2010

Fix minor typos.

25 November 2009

Changes to normative section:

• Permit annotations on types in throws clause.
• If an annotation has no @Target meta-annotation, then it applies everywhere, not just the ElementTypes that were supported in Java SE 6.
• Changes to classfile format:
  • Change extends/implements from using u1 to u2.
  • Rename reference_info to target_info. Introduce names for each variant.
  • Clarify where attributes appear (on what element in the class file).
• Improve discussion of annotations on compiler-generated methods (such as bridge methods). Cut compiler-specific discussion.
• The grammar summary in Section 2.1 now separates type parameter declarations from type uses.

Changes to non-normative section:

• Add new section "Annotations on receiver type parameters" as a potential future extension to the syntax.

5 October 2009

Changes to normative section:

• Use terminology 'declaration annotation' for old Java SE 5/6 annotations.
• An annotation with no @Target meta-annotation is treated as a declaration annotation, compatibly with the current behavior of Java SE 6.
• Classfile format changes:
  • In classfile, put declaration annotations and type annotations in different places.
  • Better specification of array locations, which were only specified by example before.
  • Specify the reference_info for annotations on class literals.

4 September 2009

Changes to non-normative section:

• Expand discussion of subtyping/inheritance among annotations.
• Expand discussion of duplicate annotations at a location.
• Mention OpenJDK support for type annotations, since build M4.
• Update URLs to reflect that the JSR 308 webpages have moved.
• Clarify license terms.

Changes to FAQ:

• Move pluggable types questions into their own FAQ.

14 May 2009

Changes to non-normative section:

• Discuss handling of base case for recursive annotations (a potential future extension).
• Improve discussion of constructor receivers and results.

27 February 2009

Changes to normative section:

• Add new enum constant ElementType.TYPE_PARAMETER, to represent declarations of type variables.
• Allow annotations on wildcard bounds.

Changes to non-normative section:

• Add more examples: performance annotations, local/remote...
• Improve explanation of meta-annotating with @Target(ElementType.TYPE_USE).

14 November 2008

Changes to normative section:

• Allow annotations on type parameters.
• Clarify target_type for locations where Java 5 already allowed annotations: method return type, method parameter, field.

Changes to non-normative section:

• There is no commitment as to whether Oracle's javac will parse annotations in comments.

20 October 2008

Changes to non-normative section:

• Improve the discussion of repeated annotations and annotation inheritance, both adding new technical material and new motivating examples. (Thanks to Niko Matsakis, Jonathan Aldrich, and others for the raw material.)
• In “inheritance among annotations” section, separate discussion of two approaches: subclassing among annotations vs. extending/implementing interfaces.
• Mention two low-priority proposals for further annotation changes: nullable annotation fields and optional/default fields in annotations.
• Make “Annotations on statements” a subsection of “Locations for annotations”.

26 September 2008

Changes to normative section:

• In class file format, add missing fields from attributes for method parameter generic types and method type arguments. Also cross-reference between the table of target_type and sections explaining the reference_info definition.
• Add to-do item: ambiguity in class file format for annotations on inner classes.
• Provide a better citation for the JDK 1.5 class file format.
• Restructure introduction to section 4 (class file format), to separate the summary of the current class file from the summary of the changes. Clarify other parts of section 4 as well. This doesn't change the specification, just improves the writing.

Changes to non-normative section:

• Separate reflection section into things that need to be done, and things that need not be done — it's mostly the latter!. Also, delete old reflection proposal an replace it by a simpler yet more expressive one. (Both the old and the new are high-level and remain to be fleshed out.)
• Many writing improvements and clarifications, including discussions of duplicate annotations, subclassing annotations, and annotations as arguments to annotations, disambiguating type and declaration annotations, annotations on new, and receivers (including an explicit definition of the term “receiver”). Also expand several examples to show actual declarations instead of just explaining them in the text.
• More extensive explanation of duplication issues with subclassing annotations. Conclusion: this should be deferred to the specific annotation processor, since there is no one-size-fits-all solution. Also, suggest that annotations that can be duplicated should be explicitly so marked.
• Undo one level of sectioning in appendix D (about possible other annotation changes). Emphasize again that the specification is not set in stone. Add another possible (but currently out of scope) extension to annotations: the @ValueMember proposal for the SingleElementAnnotation grammar rule.
• Add quotations from the (rather obscure) JSR 175 Design FAQ, explaining the rationale for several JSR 175 annotation design decisions:
  • Why is it illegal [to] annotate a single element repeatedly with the same annotation type?
  • Why can't you annotate arbitrary program elements such as blocks and individual statements?
  • Why don't you support annotation subtyping (where one annotation type
  • Why is it illegal for an annotation type to contain an element of the same type?

Changes to introduction:

• Reference the FAQ.
• Explain the term “JSR” earlier in the document.

Changes to FAQ:

• Emphasize backward compatibility.
• New question on how to write a checker.
• New question on why the Type Annotations Specification doesn't define annotation types.
• New question on how to determine the annotation on an object.

12 September 2008

Changes to non-normative section:

• Slightly expand discussion of array syntax.
• Add examples of arrays with differing nullness annotations on different levels.
• Add a FAQ to the website that cross-references into the specification.
• Move discussion of JSR process into the specification document, to remove clutter from the webpage.

29 August 2008

Changes to normative section:

• Array syntax is now uniformly prefix: @English String @NonNull [] @Length(10) [] is a non-null array of length-10 arrays of English Strings. (This was already the default for the reference implementation.)
• Make description of varargs more explicit early in the document.

Changes to non-normative section:

• Remove long, distracting discussions of alternative syntax proposals. Retain high-level comments about the other alternatives.
• Add details about annotations in comments (which are supported by the Type Annotations compiler).
• Improve and lengthen comparison with JSR 305.
• Clarify that annotations must be stored in the classfile because the classfile is supposed to represent the full type of each expression.
• Clarify that Oracle's Tree API is javac-specific.
• Clarify that reflective invocation is not changed.
• Note that anonymous class constructors are analogous to bridge methods.

Editorial changes:

• Many small textual improvements, typo fixes, improved examples, new citations, new HTML links.
• Reinstate table of contents, for easier navigation.

12 November 2007

Changes to normative section:

• Change TYPEREF to TYPE_USE in ElementType enum.
• Note that class file format ought to store the annotations for stack elements, much as is done with types to ease bytecode verification.

Changes to non-normative section:

• Note that JSR 198 can permit creating cross-IDE plug-ins. Mention need to update JSR 198 AST with respect to Java syntax changes.
• Add further discussion of the two approaches to handling duplicate annotations at a single location.

Editorial changes:

• Re-organize Figure 1 (target_type table) to separate annotations that may appear on class/method/field declarations from those that only appear inside method bodies.

5 November 2007

Changes to normative section:

• Make local variable info an array, to handle separate live ranges.

Changes to non-normative section:

• Add new example of need for type qualifier annotations: ThreadSafe.
• Fix type in comment describing meaning of example variables.

29 October 2007

Changes to normative section:

• Use new ElementType.TYPEREF enum constant for type annotations, instead of overloading the existing ElementType.TYPE enum constant.

Changes to non-normative section:

• Add new example of need for annotations on array elements (non-null type system with non-null default).
• Clarify the principle that annotations should not affect behavior: in the absence of an annotation processor, the compiler produces the same bytecodes for annotated code as it would have for the same code without annotations.
• Discuss backward-compatibility with Java 5 annotation processors, including reading annotations from files produced by Java 5 compilers, and putting annotations in files when the -target 5 switch is supplied to javac.
• Note a problem with desugaring duplicate annotations into arrays: it loses ordering information among different annotations. Also add another approach to duplicate annotations: adding a getAnnotations method like the current getAnnotation method.
• Expand discussion of permitting annotations to subclass one another, including providing some use cases and explaining some potential problems.

Editorial improvements:

• Fix placement of figures in PDF version of document.

15 October 2007

Editorial improvements:

• Use names, not numbers, for array annotation syntax proposals. Add 2 missing possibilities to the list of alternatives.

10 October 2007

New material:

• Simplify JSR 308 webpage, and make proposal more self-contained, by moving “Open issues” into appendices of the design document.
• Reinstate design alternatives for array annotations.

Editorial improvements:

• Grammar changes now avoid deletions; annotations apply to a declaration whenever possible, and “Type” is used only in places that a pre-JSR308 annotation could not appear.
• Remove discussion of -typeprocessor; recent compiler changes make it unnecessary.

2 October 2007

New material:

• Add section giving Java grammar changes.
• Give syntax for varargs annotation.
• Expand list of target types for classfile format.

Editorial improvements:

• Split document into normative main text and non-normative appendices that explain or amplify. This makes the main text a manageable 8 pages (most of which is grammar changes anyway), which should be less off-putting to readers.
• Move design alternatives out of this document, for brevity.
• Rewrite old section on “Disambiguating type and declaration annotations” to be a new section “Target meta-annotation for type annotations”, to emphasize the purpose rather than the mechanism.

1 August 2007

New material:

• Explain why typecast annotations are attached to a single bytecode, not a range.
• More syntax examples; note they aren't exhaustive. Also make example syntax and example use sections consecutive.
• Add more out-of-scope items (and re-organize that section).
• Give examples of ambiguity problems for within-the-brackets syntax for arrays (from David Audel).

Editorial improvements:

• Fix incorrect statement about annotations as annotation parameters.
• Rewrite sections on casts and instanceof.
• Move some FAQ items into design documents, to enable maintaining one instead of two documents and to keep the webpage short.

5 July 2007

New material:

• Add ideas for array annotation that do not require new locations for annotations.
• Discuss principles for choosing syntax for array annotations.
• Explain checking as type-checking of a qualified type system.
• Discuss Javadoc and clutter-reduction abbreviations.

Editorial improvements:

• Many editorial changes suggested by Werner Dietl.
• Expand related work, particularly with respect to ownership types.
• Do not state that @DefaultAnnotation(@MyAnnotation(arg="foo")) is illegal.

7 June 2007

New material:

• Move resolved issues from the JSR 308 webpage into the design document (even those out of scope), so there is one place for people to look.
  • Dynamic proxy classes
  • Javadoc
  • Annotation inference
  • Annotation defaults
  • Expression annotations
  • Implicit Java types in casts
  • JSR 308 doesn't have to be the last annotations JSR
• Discuss restrictions on compiler optimizations.
• Clarify location of receiver annotation when a throws clause is present.
• Add additional to-do items for tools/APIs that must be updated, gleaned from Joseph D. Darcy's Oracle Weblog entry So you want to change the Java Programming Language.

Editorial improvements:

• Add section to design document for JLS changes and for JVMS changes.
• Refactor tools section to give Annotation processing its own subsection.
• Make “Disambiguating type and declaration annotations” into a section, and discuss potential disadvantages of using @Target meta-annotation to disambiguate target.
• Mention that JSR 308 won the Most Innovative JSR of the Year award.

1 May 2007

New material:

• Add related work on C#.
• Add discussion of test suite (TCK).
• Discuss bridge methods.
• Note Mirror API as an open question.
• Discuss -typeprocessor option to compiler for post-attribution annotation processors.
• Explain why JSR 269 is necessary but not sufficient for type-checking plug-ins (Tree API is necessary instead).
• Discuss a difference between typecast annotations and expression annotations.

Editorial improvements:

• Reorganize “Required Tool Modifications” section (no new content).
• For clarity, put examples of annotation syntax in their own section (used to be in section with description of source locations).

25 February 2007

Substantive changes:

• Add 2 new locations for type annotations:
  • generic type arguments in a generic method or constructor invocation
  • class literals
• Add 2 new possible syntaxes for array annotations; now there are 4 in total.

Minor enhancements:

• Add related work, and also mention the Access Intents mechanism of WebSphere Application Server.
• Add URLs for two ancillary documents.
• Put source-level type annotation locations in its own subsection.
• Clarify that type syntax follows a simple prefix rule, though with a few special cases.
• Clarify syntax for generic constructors.
• Clarify relationship between variable and declaration annotations, and lack of ambiguity therein.
• Expand explanation and justification of receiver annotations.
• Clarify that annotations are not part of the Java signature.
• Clarify that annotations do not affect bytecode, even though they appear in class files.
• Clarify that “annotation processor” and “type-checking plug-in” are synonyms.
• Explain that the file format must be readable and modifiable by people.

4 February 2007

This revision makes only minor editorial improvements.

• Improve text about multi-dimensional arrays.
• Add URL of JSR 308 webpage and PDF version.
• Clarify syntax for generic constructors.
• Clarify that annotations are not part of the Java signature.
• Clarify that “annotation processor” and “type-checking plug-in” are synonyms.
• Add URLs for two ancillary documents.

1 February 2007

First version tracked by this changelog.