Changelog for type annotations (JSR 308)
This webpage lists changes made to the specification
for Type annotations (JSR 308).
Please always refer to the
current version of the specification
(PDF,
HTML).
- 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 annotions, local/remote...
-
Improve explanation of meta-anotating 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 Sun'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 prototype implementation).
-
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 Sun'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 Sun 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.