The @Inherited Meta-Annotation
By default, an annotation applied on a class is not inherited by its subclasses. However, this can be changed by applying the meta-annotation @Inherited on the declaration of the annotation type. Such an annotation will automatically be inherited by subclasses when this annotation is present in their superclass. It has no effect if the annotation is applied to program elements other than classes. Note also that a class cannot inherit annotations from interfaces it implements, nor can a subinterface inherit annotations from superinterfaces it extends, regardless of the fact that these annotations are marked with the meta-annotation @Inherited.
The meta-annotation @Inherited is of type java.lang.annotation.Inherited, which is a marker meta-annotation type.
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Playable {}
______________________________________
@MusicMeta
@Playable
public class Composition {}
______________________________________
public class Song extends Composition {}
In the code above, the annotations @MusicMeta and @Playable are applied to the class Composition, but only the annotation @Playable is inherited by the subclass Song because only the @Playable annotation is applied to the meta-annotation @Inherited in its type declaration. This means that the Composition class has two annotations, but the subclass Song has only one, namely the inherited annotation @Playable.
The @Documented Meta-Annotation
By default, annotations are not processed by the javadoc tool when generating API documentation from the source code, unless the declaration of the annotation type is marked with the meta-annotation @Documented. This meta-annotation is of type java.lang.annotation.Documented which is a marker meta-annotation type.
import java.lang.annotation.*;
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented // (1)
public @interface Pending {}
_____________________________________
import java.lang.annotation.*;
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Verified {} // (2)
_____________________________________
@Documented
@Verified
public class Gizmo {} // (3)
In the code above, the declaration of the annotation type Pending is marked with the meta-annotation Documented at (1), but this is not the case for the declaration of the annotation type Verified at (2). Both annotations are applied to the class Gizmo at (3). As a result, the generated Javadoc documentation for the class Gizmo will only show the presence of the @Pending annotation, but not the @Verified annotation. Thus the @Documented annotation gives annotation developers full control over the process of including annotations in the generated API documentation.
For another example of using the meta-annotation @Documented, see the discussion about the @Deprecated annotation (Example 25.1, p. 1580).