Java Language Annotations Defining annotation types

Help us to keep this website almost Ad Free! It takes only 10 seconds of your time:
> Step 1: Go view our video on YouTube: EF Core Bulk Extensions
> Step 2: And Like the video. BONUS: You can also share it!

Example

Annotation types are defined with @interface. Parameters are defined similar to methods of a regular interface.

@interface MyAnnotation {
    String param1();
    boolean param2();
    int[] param3();  // array parameter 
}

Default values

@interface MyAnnotation {
    String param1() default "someValue";
    boolean param2() default true;
    int[] param3() default {};
}

Meta-Annotations

Meta-annotations are annotations that can be applied to annotation types. Special predefined meta-annotation define how annotation types can be used.

@Target

The @Target meta-annotation restricts the types the annotation can be applied to.

@Target(ElementType.METHOD)
@interface MyAnnotation {
    // this annotation can only be applied to methods
}

Multiple values can be added using array notation, e.g. @Target({ElementType.FIELD, ElementType.TYPE})

Available Values

ElementTypetargetexample usage on target element
ANNOTATION_TYPEannotation types
@Retention(RetentionPolicy.RUNTIME) 
@interface MyAnnotation
CONSTRUCTORconstructors
@MyAnnotation
public MyClass() {}
FIELDfields, enum constants
@XmlAttribute
private int count;
LOCAL_VARIABLEvariable declarations inside methods
for (@LoopVariable int i = 0; i < 100; i++) {
@Unused
String resultVariable;
}
PACKAGEpackage (in package-info.java)
@Deprecated
package very.old;
METHODmethods
@XmlElement
public int getCount() {...}
PARAMETERmethod/constructor parameters
public Rectangle(
@NamedArg("width") double width,
@NamedArg("height") double height) {
...
}
TYPEclasses, interfaces, enums
@XmlRootElement
public class Report {}
Java SE 8
ElementTypetargetexample usage on target element
TYPE_PARAMETERType parameter declarations
public <@MyAnnotation T> void f(T t) {}
TYPE_USEUse of a type
Object o = "42";
String s = (@MyAnnotation String) o;

@Retention

The @Retention meta-annotation defines the annotation visibility during the applications compilation process or execution. By default, annotations are included in .class files, but are not visible at runtime. To make an annotation accessible at runtime, RetentionPolicy.RUNTIME has to be set on that annotation.

@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    // this annotation can be accessed with reflections at runtime
}

Available values

RetentionPolicyEffect
CLASSThe annotation is available in the .class file, but not at runtime
RUNTIMEThe annotation is available at runtime and can be accessed via reflection
SOURCEThe annotation is available at compile time, but not added to the .class files. The annotation can be used e.g. by an annotation processor.

@Documented

The @Documented meta-annotation is used to mark annotations whose usage should be documented by API documentation generators like javadoc. It has no values. With @Documented, all classes that use the annotation will list it on their generated documentation page. Without @Documented, it's not possible to see which classes use the annotation in the documentation.

@Inherited

The @Inherited meta-annotation is relevant to annotations that are applied to classes. It has no values. Marking an annotation as @Inherited alters the way that annotation querying works.

  • For a non-inherited annotation, the query only examines the class being examined.
  • For an inherited annotation, the query will also check the super-class chain (recursively) until an instance of the annotation is found.

Note that only the super-classes are queried: any annotations attached to interfaces in the classes hierarchy will be ignored.

@Repeatable

The @Repeatable meta-annotation was added in Java 8. It indicates that multiple instances of the annotation can be attached to the annotation's target. This meta-annotation has no values.



Got any Java Language Question?