Find JSRs
Submit this Search

Ad Banner

Summary  |  Proposal  |  Detail (Summary & Proposal)  |  Nominations
JSRs: Java Specification Requests
JSR 308: Annotations on Java Types

Stage Access Start Finish
Final Release Download page 04 Mar, 2014  
Final Approval Ballot View results 18 Feb, 2014 03 Mar, 2014
Proposed Final Draft Download page 14 Jan, 2014  
Public Review Ballot View results 10 Dec, 2013 23 Dec, 2013
Public Review Download page 04 Nov, 2013 04 Dec, 2013
Early Draft Review 3 Download page 20 Mar, 2013 19 Apr, 2013
Early Draft Review 2 Download page 30 Jan, 2012 29 Feb, 2012
Early Draft Review Download page 07 Nov, 2007 07 Dec, 2007
Expert Group Formation   31 Oct, 2006 03 Apr, 2007
JSR Review Ballot View results 17 Oct, 2006 30 Oct, 2006
Status: Final
JCP version in use: 2.8
Java Specification Participation Agreement version in use: 2.0

This JSR extends the Java annotation syntax to permit annotations on any occurrence of a type. Previously, annotations could not be placed on generic type arguments, type casts, etc.

Expert Group Transparency:
  Public Communications
  Issue Tracking


Specification Leads
  Alex Buckley Oracle
  Michael Ernst Ernst, Michael
Expert Group
  Werner Dietl Michael Ernst IBM
: Srikanth Sankaran
  Doug Lea Oracle
: Alex Buckley
Sun Microsystems, Inc.
: Alex Buckley

Updates to the Java Specification Request (JSR)

The following information has been updated from the original JSR:

The Expert Group and Specification Lead moved the JSR to JCP 2.8.

2.19 Please describe the communications channel you have established for the public to observe Expert Group deliberations, provide feedback, and view archives of all Expert Group communications.

EG communication archive:
Comments on draft specifications may be sent to for consideration by the EG. The web archives of this list will be public at

2.20 What is the URL of the Issue Tracker that the public can read, and how does the public log issues in the Issue Tracker?

2.21 Please provide the location of the publicly accessible document archive you have created for the Expert Group.

The Current proposal and other materials are available at

2010.02.16: The Specification Leads have changed.

Specification Lead: Alex Buckley (Oracle), Michael Ernst

E-Mail Address:,

Telephone Number: +1 408 276 3065, +1 617 253 0945

Fax Number: -, +1 617 258 8682

2007.12.18: The Specification Leads have changed.

Specification Lead: Alex Buckley, Michael Ernst

E-Mail Address:,

Telephone Number: +1 617 253 0945

Fax Number: +1 617 258 8682

2007.03.06: The Current proposal and other materials are available at

Note that out-of-date information has been crossed out. Current information is found at the top of this update section.

Original Java Specification Request (JSR)

Identification | Request | Contributions | Additional Information

Section 1. Identification

Submitting Member: Michael Ernst

Name of Contact Person: Michael Ernst, Danny Coward

E-Mail Address:, Danny.Coward@Sun.COM

Telephone Number: +1 617 253 0945, +1 415 294 5386

Fax Number: +1 617 258 8682, +1 408 276 7700

NOTE that out-of-date information has been crossed out; current contact information is found in the update section.

Initial Expert Group Membership:

Doug Lea
Michael Ernst
Ted Neward
William Pugh

Supporting this JSR:

Doug Lea
Michael Ernst
Ted Neward
William Pugh

Section 2: Request

2.1 Please describe the proposed Specification:

We propose an extension to Java's annotation system that permits annotations to appear on any use of a type, not just on class/method/field/variable declarations, as is the case in Java SE 6. Such a generalization removes arbitrary limitations of Java's annotation system, and it enables new uses of annotations.

This JSR specifies the syntax of extended Java annotations, but it makes no commitment as to their semantics. As with Java's existing annotations, the semantics is dependent on annotation processors (compiler plug-ins), and not every annotation is necessarily sensible in every location where it is syntactically permitted to appear. This proposal is compatible with existing annotations, such as those specified in JSR 250, "Common Annotations for the Java Platform", and JSR 305, "Annotations for Software Defect Detection".

This proposal does not change the compile-time, load-time, or run-time semantics of Java. It does not change the abilities of Java annotation processors. The proposal merely makes annotations more general --- and thus more useful for their current purposes, and also usable for new purposes that are compatible with the original vision for annotations.

The new Java syntax allows annotations in the following locations. (The specific annotation names, such as @NonNull, are examples only; this document does not propose any annotations, merely specifying where they can appear in Java code.)

    method receivers:
    public int size() @Readonly { ... }

    generic type arguments:
    Map<@NonNull String, @NonEmpty List<@Readonly Document>> files;

    Document[@Readonly] docs1;
    Document[][@Readonly] docs2 = new Document[2][@Readonly 12];
    (docs1 is an unmodifiable one-dimensional array of mutable Documents.
    docs2 is a mutable array whose elements are unmodifiable one-dimensional arrays of mutable Documents.)

    myString = (@NonNull String)myObject;

    type tests:
    boolean isNonNull = myString instanceof @NonNull String;

    object creation:
    new @NonEmpty @Readonly List(myNonEmptyStringSet)

    type parameter bounds:
    class Folder { ... }

    class inheritance:
    class UnmodifiableList implements @Readonly List<@Readonly T> { ... }

    throws clauses:
    void monitorTemperature() throws @Critical TemperatureException { ... }

Java annotations (including the extended annotations) must be stored in the class file for two reasons. First, they may be part of the interface of a class and, if so, must be available to the compiler (really, to the type-checking plug-in) when compiling clients of the class. Second, since class files may originate from any source, the information may be useful in other contexts, such as compile-time verification.

This JSR proposes conventions for storing the new annotations, as well as for storing local variable annotations, which are permitted in Java syntax but currently discarded by the compiler. Class files already store annotations in the form of ``attributes''. JVMs ignore unknown attributes. For backward compatibility, we use new attributes for storing the type annotations. In other words, our proposal merely reserves the names of a few attributes and specifies their layout. Our proposal does not alter the way that existing annotations on classes, methods, method parameters, and fields are stored in the class file. Class files generated from programs that use no new annotations will be identical to those generated by a standard Java SE 6 (that is, pre-extended-annotations) compiler.

This JSR introduces two new attributes: RuntimeVisibleTypeAnnotations and RuntimeInvisibleTypeAnnotations. These attributes are structurally identical to the existing RuntimeVisibleAnnotations and RuntimeInvisibleAnnotations attributes described above with one exception: rather than an array of annotation elements, RuntimeVisibleTypeAnnotations and RuntimeInvisibleTypeAnnotations contain an array of extendedannotation elements. An extendedannotation element is like an annotation element, but it adds a target_type field and a reference_info field.

The specification will also attempt to provide a simple approach for writing annotations with array-valued elements.

2.2 What is the target Java platform? (i.e., desktop, server, personal, embedded, card, etc.)

This technology targets all Java platforms that support Java annotations, as introduced in Java SE 5.

2.3 The Executive Committees would like to ensure JSR submitters think about how their proposed technology relates to all of the Java platform editions. Please provide details here for which platform editions are being targeted by this JSR, and how this JSR has considered the relationship with the other platform editions.

This technology should be deployed as part of Java SE 7.

2.4 Should this JSR be voted on by both Executive Committees?

No. The Java SE/EE executive committee is sufficient.

2.5 What need of the Java community will be addressed by the proposed specification?

Among other uses, annotations on Java types will enable the use of type qualifiers. Type qualifiers are modifiers that provide extra information about a type or variable; they can be thought of as a form of subtyping. A designer can define new type qualifiers using Java annotations, and can provide plug-ins to check their semantics (for instance, by issuing lint-like warnings during compilation). A programmer can then use these type qualifiers throughout a program to obtain additional guarantees at compile time about the program.

2.6 Why isn't this need met by existing specifications?

A system for custom type qualifiers requires extensions to Java's annotation system, to permit annotation of any use of a type in a program. The existing Java SE 6 annotations are inadequate, because many facts a programmer would like to specify are inexpressible. Similarly to type qualifiers, other pluggable type systems and similar lint-like checkers also require these extensions to Java's annotation system.

2.7 Please give a short description of the underlying technology or technologies:

The key underlying technology is Java SE and JSR 250 ("Common Annotations for the Java Platform"). Implementation of the JSR will require changes to Java compilers and other tools to recognize the new syntax and place attributes in classfiles.

2.8 Is there a proposed package name for the API Specification? (i.e., javapi.something, org.something, etc.)


2.9 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?


2.10 Are there any security issues that cannot be addressed by the current security model?

No known security problems.

2.11 Are there any internationalization or localization issues?


2.12 Are there any existing specifications that might be rendered obsolete, deprecated, or in need of revision as a result of this work?

This work may require updates to the Java SE core reflection APIs (in java.lang.* and java.lang.reflect.*), and updates to the Pluggable Annotation Processing API (JSR 269), to be determined with the appropriate expert groups.

2.13 Please describe the anticipated schedule for the development of this specification.

The intention is to deliver this JSR as a component of Java SE 7. Early Draft Review would occur in the second half of 2006, Public Review in the first half of 2007, and Proposed Final Draft in the second half of 2007.

2.14 Please describe the anticipated working model for the Expert Group working on developing this specification.

We will primarily use email, with conference calls and meetings as needed.

2.15 It is important to the success of the community and each JSR that the work of the Expert Group be handled in a manner which provides the community and the public with insight into the work the Expert Group is doing, and the decisions that the Expert Group has made. The Executive Committees would like to ensure Spec Leads understand the value of this transparency and ask that each JSR have an operating plan in place for how their JSR will address the involvement of the community and the public. Please provide your plan here, and refer to the Spec Lead Guide for a more detailed description and a set of example questions you may wish to answer in your plan.

The JSR process will be run in an open and transparent way, with drafts, discussion, and progress reports available for public view and comments via and our own websites. We also plan to provide a draft reference implementation for public use and comment, beginning with the early draft review, and fold that implementation into the Java SE 7 sources as soon as possible. We may also add a public Wiki or other web support to further involve the Java community.

2.16 Please describe how the RI and TCK will de delivered, i.e. as part of a profile or platform edition, or stand-alone, or both. Include version information for the profile or platform in your answer.

This JSR proposes a change to the Java language and thus can only be delivered in a Java SE platform release. It is targeted for Java SE 7.

2.17 Please state the rationale if previous versions are available stand-alone and you are now proposing in 2.13 to only deliver RI and TCK as part of a profile or platform edition (See sections 1.1.5 and 1.1.6 of the JCP 2 document).


2.18 Please provide a description of the business terms for the Specification, RI and TCK that will apply when this JSR is final.

The Reference Implementation and TCK will be made available as part of some future Java SE platform release, hence under the same terms.

Note that the following information was added when the JSR moved to JCP 2.8:

2.19 Please describe the communications channel you have established for the public to observe Expert Group deliberations, provide feedback, and view archives of all Expert Group communications.

EG communication archive:
Comments on draft specifications may be sent to for consideration by the EG. The web archives of this list will be public at

2.20 What is the URL of the Issue Tracker that the public can read, and how does the public log issues in the Issue Tracker?

2.21 Please provide the location of the publicly accessible document archive you have created for the Expert Group.

Section 3: Contributions

3.1 Please list any existing documents, specifications, or implementations that describe the technology. Please include links to the documents if they are publicly available.

Annotations on Java types
A longer and more technically detailed version of this JSR, which contains over two dozen references to related work, including examples of the utility of type qualifiers.

Custom type qualifiers via annotations on Java types
Describes one way that annotations on Java types could be used

Annotation index file specification
File format for describing annotations outside a .java file; useful for tools, though not necessarily a part of this JSR.

Related JSRs:

JSR 175: A Metadata Facility for the Java Programming Language

JSR 250: Common Annotations for the Java Platform

JSR 269: Pluggable Annotation Processing API

JSR 305: Annotations for Software Defect Detection

3.2 Explanation of how these items might be used as a starting point for the work.

The JSR will build directly on these documents, especially the first one listed above.

Section 4: Additional Information (Optional)

4.1 This section contains any additional information that the submitting Member wishes to include in the JSR.