This is a collection of rules for how annotations should work.

Some of these duplicate what's in the specs (in particular,

the platform spec and the Common Annotations spec).

You can consider these to be rules about how annotations

currently work, as well as rules about how new annotations

should be designed to work to be consistent with current

annotations. Of course, there are exceptions, called out below.

This section describes how annotations interact with inheritance.

Note that, in general, we do not use the @Inherited annotation

on our annotations. @Inherited only applies to annotations at

the class level. If multiple classes in a hierarchy are annotated

with an @Inherited annotation, only the annotation furthest from

the base class is returned. For resource annotations, we want

all such annotations to apply, so @Inherited would give the wrong

results. For component-defining annotations, we don't want the

fact that a superclass is a component to cause all subclasses to

be components, so we don't use @Inherited for component-defining

annotations.

Some frameworks have defined additional annotations that specify

how **their** annotations behave with regard to inheritance.

For example, see the JPA @Inheritance and @DiscriminatorColumn

annotations.

Note that CDI is an exception to this, and recommends that scopes and interceptor bindings are declared @Inherited. It also recommends that stereotypes may be @Inherited depending on their intended usage. It recommends that qualifiers are not declared @Inherited.

A resource annotation (@Resource, @EJB, etc.) on a superclass

is **not** overridden by a similar annotation on a subclass.

In general, annotations on interfaces are ignored.

A method-level annotation on a superclass method is ignored if the

subclass overrides the method; only annotations on the subclass

method apply.

Since a class always "overrides" methods in an interface, annotations on

the interface method are ignored.

A method-level annotation on a superclass method or field that is **not**

overridden "shows through" and still applies. (Note that it is not possible

to override a field.)

A method-level annotation on a private superclass method or field remains

in effect.

JAX-RS allows per-method annotations on the methods of an interface.

If the implementing class doesn't declare **any** JAX-RS annotations

on a method (other annotations are allowed), the JAX-RS annotations

on the interface's method apply. Any JAX-RS annotation on a method

overrides **all** JAX-RS annotations on the corresponding interface method.

JAX-RS defines a similar rule for annotations on methods of a superclass,

again violating the general rule above. If a subclass overrides a method

but does not include any JAX-RS annotations on the method declaration, the

JAX-RS annotations from the superclass apply.

In some cases, an annotation on a method will "show through" to subclasses

that override the method. Since this prevents the normal approach of

"disabling" the annotation by omitting it, the annotation will need an

attribute that undoes its normal effect. For example, JAX-WS has

@WebMethod(exclude=true) and Connectors has @ConfigProprty(ignore=true).

Generally this style is discouraged.

EJB allows the @Local and @Remote annotations to appear on interfaces.

The JPA annotations @Table, @SecondaryTable, and @SecondaryTables

interact with the @Inheritance annotation to control how they behave

with respect to inheritance.

CDI producer fields or methods are not inherited by subclasses, even if they

are not overridden. The superclass would not know how to produce an

instance of the subclass.

CDI introduces specialization, which affects inheritance. If a subclass is defined @Specializes, then

* all qualifiers are inherited, regardless of whether they are declared @Inherited

* the EL name of the bean is inherited (@Named is not declared @Inherited)

The following component-defining annotations do have @Inherited on them due to historical accident. In common usage, these annotations are not involved in inheritance hierarchies so it was decided to leave them in a state of non-compliance with these rules rather than risk introducing unforeseen problems.

* javax.faces.validator.FacesValidator

* javax.faces.view.facelets.FaceletsResourceResolver

* javax.faces.render.FacesBehaviorRenderer

* javax.faces.render.FacesRenderer

* javax.faces.convert.FacesConverter

* javax.faces.component.behavior.FacesBehavior

* javax.faces.component.FacesComponent

Many annotations are used to effect the implementation of a class.

For example, the Resource annotations define resources that are

used by the implementation of the class. The resources used by a

class are rarely part of the API specification of the class.

In some cases, annotations add to the API specification of a class,

and contain important information that a user of the class will need

to know. Annotations of this sort should be marked with @Documented;

these annotations will then appear in the javadoc for the class.

All CDI annotations are marked @Documented.

A component-defining annotation (e.g., @Stateless, @WebService) on a

superclass does not apply to a subclass.

A component-defining annotation (e.g., @Stateless, @WebService) on an

interface does not apply to a class that implements the interface.

(This is an instance of the general rule that annotations on interfaces

are ignored.)

Class level annotations that effect the semantics of the class

are local to the defining class.

These class level annotations are a shorthand for annotating

methods defined in that class. Class level annotations

play no direct role in inheritance unless the annotation

is marked @Inherited. See above for why we don't use

@Inherited for annotations that need to combine, although

it is useful for annotations that simply need to override

the same annotation in a superclass (e.g., @ServletSecurity).

After the effect of class level annotations is considered

for each class, the methods defined on that class end up

with attributes that are a result of a direct annotation

or a result of applying the class level annotation.

When a subclass overrides a method, none of the attributes

of the superclass method apply. When a subclass does not

override a method, the attributes of the method are the

effective attributes for the method from the parent class.

A method default rule such as "all public methods are web

service methods" acts as an implicit class level annotation.

Some class level annotations don't effect the semantics of

the class, but are just attached to some class "for convenience".

For example, @Resource doesn't effect the semantics of the class.

Many JPA annotations don't effect the specific class they're

attached to, but instead effect the persistence unit the class

is a part of.

In some cases, annotations on subclass and superclass methods

"combine". For example, the interceptor annotations on superclass

methods apply even if the subclass overrides the method and provides

its own interceptor annotations. The interceptors from both the

superclass and the subclass are invoked, from superclass down to

subclass.

We've made very little use of package level annotations in Java EE.

Where they are used, they effectively act as another level of defaulting

above classes. That is, package level annotations are overridden by

class level annotations, which in turn are overridden by method level

annotations.

For annotations that can be used at the class level and at the package

level, the implementation should look for the annotation on the class

first [XXX - possibly following the superclass hierarchy if the annotation is not

marked @Inherited]. If the annotation isn't found, the implementation

should look for the annotation on the package for the class [XXX - possibly

following the superclass hierarchy and considering the package for each

superclass if the annotation isn't marked @Inherited].

JAXB uses package level annotations in this way.

In general, information in deployment descriptors should override

information in annotations. In some cases, the information combines,

such as for injection target specifications or for interceptors.

In rare cases, an annotation can override a deployment descriptor entry;

see the web fragments section below.

From (the proposed update to) the Java EE platform spec:

The following list describes the rules for how a deployment

descriptor entry may override a Resource annotation.

- The relevant deployment descriptor entry is located based on

the JNDI name used with the annotation (either defaulted or

provided explicitly).

- The type specified in the deployment descriptor must be

assignable to the type of the field or property.

- The description, if specified, overrides the description

element of the annotation.

- The injection target, if specified, defines additional

injection points for the resource.

- The mapped-name element, if specified, overrides the

mappedName element of the annotation.

- The res-sharing-scope element, if specified, overrides the

shareable element of the annotation. In general, the

Application Assembler or Deployer should not change this

value as doing so is likely to break the application.

- The res-auth element, if specified, overrides the

authenticationType element of the annotation. In general, the

Application Assembler or Deployer should not change this

value as doing so is likely to break the application.

- The lookup-name element, if specified, overrides the lookup

element of the annotation

It is an error to request injection of two resources into the

same target. The behavior of an application that does so is

undefined.

An ejb-jar.xml in a war file is treated the same as a web-fragment.xml

in terms of the interaction with web.xml for resources.

A Resource entry in a web fragment descriptor overrides annotations

**only in the corresponding library**, using the rules above.

A Resource entry in a web.xml file overrides **all** attributes of any

corresponding Resource entry in a web fragment descriptor, **except**

for the injection targets, which are combined.

A Resource entry in a web.xml file overrides a Resource annotation on a

class in WEB-INF/classes using the rules above.

A Resource annotation on a class in WEB-INF/classes overrides **all**

attributes of any corresponding Resource entry in a web fragment descriptor.

**This may be the only place where an annotation overrides a deployment

descriptor entry.**

In some cases it's desirable to allow a particular annotation to

occur multiple times on a single element, usually with different

parameters. The convention for allowing @SomeAnnotation to be

repeated is to define a pluralized version of the annotation:

public @interface SomeAnnotations {

SomeAnnotation[] value();

}

Used as:

@SomeAnnotations({

@SomeAnnotation("value1"),

@SomeAnnotation("value2")

})

public class MyClass { ... }

We're hoping that Java SE 8 will support this style more directly

in the compiler, allowing:

@SomeAnnotation("value1")

@SomeAnnotation("value2")

public class MyClass { ... }

In some cases we use annotations to mark which classes and which methods

should be used by the container for which purposes, and in other cases we

specify this interface with a Java language interface. The following rules are

used to choose which to use when:

1. When defining an API that an application is going to implement and

the container is going to call, use an interface, unless one of the

following rules applies.

2. If an application class is providing an API that's exposed to other

applications, and that class also needs to provide methods that the

container will call for lifecycle functions (or other container support

or management functions), use an annotation to mark those methods so

that the application has flexibility in the choice of names for those

methods.

3. If an application is going to expose an interface that another

application (or user) is going to use **without** Java, use annotations

to mark the methods that correspond to this interface. This avoids the

need to define a Java interface that's never going to be used by anyone

other than the one class implementing the interface.

4. If there can be more than one occurrence of a method for a given

purpose, use an annotation.

5. If an interface is chosen and the interface has many methods,

consider providing an "adapter" class that implements all the methods

with nop implementations. Applications can then subclass this adapter

class to avoid the need to implement all methods. It's often better to

decompose the interface into multiple smaller interfaces.

Use correct types instead of strings for annotation attributes when possible.

For optional attributes, prefer these default values:

* String - ""

* int - -1

* Class - void.class

* [] - \{ }

Use enumerated types rather than magic String values when the set of

possible options is finite and fairly small.

Avoid nesting annotations more than one level.

Rather than adding more and more different aspects to an annotation,

try to separate the concerns by creating different annotations that

may be applied together or independently.

Use "value()" as the element name in an annotation that only has one

element or if, when using the annotation, that one element is the

one most commonly specified.

Need to check JAXB annotations.

Need to write up something that describes when it's appropriate to only

add an annotation, or only add a deployment descriptor entry, vs. having

both.