Find JSRs
Submit this Search

Ad Banner

JSRs: Java Specification Requests
JSR 175: A Metadata Facility for the JavaTM Programming Language

Updates to the Original Java Specification Request (JSR)

The following updates have been made to the original JSR.

Maintenance Lead: Alex Buckley, Oracle
E-Mail Address:
Telephone Number: +1 408 276 3065


Maintenance Lead: Danny Coward

E-Mail Address:

Telephone Number: +1 408 276 7049

Fax Number: +1 408 276 7700

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

It is intended that this JSR will be delivered as part of the J2SETM "Tiger" release.

Original Java Specification Request (JSR)

Identification | Request | Contributions

Section 1. Identification

Submitting Member: Sun Microsystems, Inc.

Name of Contact Person: Joshua Bloch

E-Mail Address:

Telephone Number: +1 408 276 7022

Fax Number:

Specification Lead: Joshua Bloch

E-Mail Address:

Telephone Number: +1 408 276 7022

Fax Number:

Initial Expert Group Membership:

Supporting this JSR:

BEA Systems
Borland Software Corporation
Oracle Corporation
Sun Microsystems, Inc.

Section 2: Request

2.1 Please describe the proposed Specification:

There has been a growing trend towards annotating fields, methods, and classes as having particular attributes that indicate they should be processed in special ways by development tools, deployment tools, or run-time libraries. We call such annotations metadata.

For example, the JavaBeansTM architecture introduced various stylistic naming patterns (such as getFoo/setFoo method names) that could be used to indicate that particular methods were used for accessing properties, for registering event handlers, and so forth. Similarly the Enterprise JavaBeans architecture introduced various stylistic patterns that allow methods to be marked as remote methods, home methods, and the like. The EJB architecture defines significant extra information in its deployment descriptors that is used to provide information on things like the persistence relationships of fields, the transactional properties of methods, and so forth. Source code defining web services components has similar needs.

Custom tools may use metdata to generate auxillary source files to be used in conjunction with the source file containing the annotation. For example, a stub generator could generate remote procedure call stubs based on annotations indicating that certain methods are designed for remote use.

In general, the need to provide auxiliary information for program elements appears to be growing. While the existing mechanisms have been adequate for simple uses, they are becoming increasingly awkward for more complicated uses. In light of this situation, it seems appropriate to add to the Java programming language a means of associating arbitrary attribute information with particular classes/interfaces/methods/fields. We refer to this mechanism as the Java programming language metadata facility. This facility is meant to replace the various ad hoc metadata facilities in use today.

We believe there are several elements needed as part of this JSR:

  • Definition of a Java programming language feature that allows medatadata information to be supplied for (at least) classes, interfaces, methods, and fields. This language extension will allow metadata to be recognized by development tools. It appears likely that it will be useful to allow attribute values to be associated with given metadata attributes.

    The exact syntax will need to be determined by the expert group. There appear to be a number of possibilities, including (but not limited to!) using a doc comment tag @meta or adding a new Java programming language keyword meta.

  • Definition of a runtime delivery format for metadata and of runtime APIs so that tools and libraries can accesss metadata information at deployment time and at runtime.

  • Definition of rules for the attribute namespace so as to avoid accidental collisions over the same attribute name. Details will be determined by the expert group, but it seems that a mechanism leveraging the class naming conventions might be useful.

This list is not meant to be exhaustive. For example, if it is determined that there is a need for the compiler to do some validity checking on metadata, we will need a mechanism for communicating restrictions on the use of a particular attribute (such as "The attribute com.acme.Remote may be used on methods, but not on classes, interfaces, or fields"). Metadata processing tools such as stub generators, however, are outside the scope of this JSR. The JSR is intended to enable such tools, but not to define them.

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

Java 2, Standard Edition.

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

As described above, this specification will make it easier to provide auxiliary information for classes, interfaces, fields, and methods.

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

There is no existing language mechanism for providing this kind of information.

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

A Java programming language feature for metadata, plus a runtime format for metadata information, plus runtime APIs for accessing metadata information.

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


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


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


2.9 Are there any internationalization or localization issues?


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

No existing mechanisms will be altered or deprecated. However, it is anticipated that some specifications (such as the EJB or JAX-RPC specifications) may make use of this feature in future revisions.

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


Note that this section has been updated since the original JSR.

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

It is anticipated that most of the work will be done by email with occasional teleconferences and perhaps face-to-face meetings where appropriate.

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.

The JavaTM Language Specification.

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

The existing JavaTM Language Specification will be used as the basis for this work, and will be amended to include any language changes that results from this effort.