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.