Skip to content

Annotations

A form of metadata, provide data about a program that is not part of the program itself.

  • Information for the compiler — Annotations can be used by the compiler to detect errors or suppress warnings.
  • Compile-time and deployment-time processing — Software tools can process annotation information to generate code, XML files, and so forth.
  • Runtime processing — Some annotations are available to be examined at runtime.
  • stronger type checking

  • extend java.lang.annotation to form your own annotations

  • repeated are allowed

Annotations can be applied to declarations: declarations of classes, fields, methods, and other program elements.

@Entity

@Override
void mySuperMethod() { ... }

@Author(
   name = "Benjamin Franklin",
   date = "3/27/2003"
)
class MyClass { ... }

@SuppressWarnings(value = "unchecked")
void myMethod() { ... }

@Author(name = "Jane Doe")
@EBook
class MyClass { ... }

@Author(name = "Jane Doe")
@Author(name = "John Smith")
class MyClass { ... }

Class instance creation expression:

new @Interned MyObject();

Type cast:

myString = (@NonNull String) str;

implements clause:

class UnmodifiableList<T> implements
        @Readonly List<@Readonly T> { ... }

Thrown exception declaration:

void monitorTemperature() throws
    @Critical TemperatureException { ... }

Annotation Type

Many annotations replace comments in code.

@Documented
@interface ClassPreamble {
   String author();
   String date();
   int currentRevision() default 1;
   String lastModified() default "N/A";
   String lastModifiedBy() default "N/A";
   // Note use of array
   String[] reviewers();
}
@ClassPreamble (
   author = "John Doe",
   date = "3/17/2002",
   currentRevision = 6,
   lastModified = "4/12/2004",
   lastModifiedBy = "Jane Doe",
   // Note array notation
   reviewers = {"Alice", "Bob", "Cindy"}
)
public class Generation3List extends Generation2List {

// class code goes here

}
java inbuilt
@Deprecated 

@Override 

@SuppressWarnings({"unchecked", "deprecation"})

@SafeVarargs - avoid unsafe operations

// TODO @FunctionalInterface 

Meta annotations

@Retention:

specifies how the marked annotation is stored:

RetentionPolicy.SOURCE – The marked annotation is retained only in the source level and is ignored by the compiler. RetentionPolicy.CLASS – The marked annotation is retained by the compiler at compile time, but is ignored by the Java Virtual Machine (JVM). RetentionPolicy.RUNTIME – The marked annotation is retained by the JVM so it can be used by the runtime environment.

@Documented - included in javadoc
@Target - on which it is allowed
@Inherited - sub class inherets super class's annotion.
@Repeatable - more than once

Type Annotations and Pluggable Type Systems

expressions (new), casts, implements clauses, and throws clauses.

@NonNull String str;
Checker Framework

Repeating Annotations

@Schedule(dayOfMonth="last")
@Schedule(dayOfWeek="Fri", hour="23")
public void doPeriodicCleanup() { ... }
@Alert(role="Manager")
@Alert(role="Administrator")
public class UnauthorizedAccessException extends SecurityException { ... }

For compatibility reasons, repeating annotations are stored in a container annotation that is automatically generated by the Java compiler. In order for the compiler to do this, two declarations are required in your code:

  1. Declare a Repeatable Annotation Type
import java.lang.annotation.Repeatable;

@Repeatable(Schedules.class)
public @interface Schedule {
  String dayOfMonth() default "first";
  String dayOfWeek() default "Mon";
  int hour() default 12;
}
  1. Declare the Containing Annotation Type
public @interface Schedules {
    Schedule[] value();
}

Retrieving Annotations

AnnotatedElement.getAnnotation(Class<T>)
AnnotatedElement.getAnnotationsByType(Class<T>)

Design Considerations

you must consider the cardinality of annotations of that type. to be as flexible and powerful as possible.