Introduction to Java Annotations

  • Annotations, a form of metadata, provide data about a program that is not part of the program itself.
  • Annotations have no direct effect on the operation of the code they annotate.
  • Annotations have a number of uses, among them:
    • 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.

The format of an Annotation

  • Annotation looks like
  • @NameOfAnnotation
  • The at sign character (@) indicates to the compiler that what follows is an annotation.
  • In the following example, the annotation's name is Override:
  • @Override
    void mySuperMethod() { ... }
  • The annotation can include elements, which can be named or unnamed, and there are values for those elements:
  • @Author(
      name = "Benjamin Franklin",
      date = "3/27/2003"
    class MyClass() { ... }
    @SuppressWarnings(value = "unchecked")
    void myMethod() { ... }
  • If there is just one element named value, then the name can be omitted, as in:
  • @SuppressWarnings("unchecked")
    void myMethod() { ... }
  • If the annotation has no elements, then the parentheses can be omitted, example @Override.
  • It is also possible to use multiple annotations on the same declaration:
  • @Author(name = "Jane Doe")
    class MyClass { ... }
  • If the annotations have the same type, then this is called a repeating annotation:
  • @Author(name = "Jane Doe")
    @Author(name = "John Smith")
    class MyClass { ... }
  • Repeating annotations are supported as of the Java SE 8 release.
  • The annotation type can be one of the types that are defined in the java.lang or java.lang.annotation packages of the Java SE API.
  • In the previous examples, Override and SuppressWarnings are predefined Java annotations.
  • It is also possible to define your own annotation type.
  • The Author and Ebook annotations in the previous example are custom annotation types.

Where Annotation can be used

  • Annotations can be applied to declarations:
    • declarations of classes,
    • fields,
    • methods, and
    • other program elements.
  • When used on a declaration, each annotation often appears, by convention, on its own line.
  • As of the Java SE 8 release, annotations can also be applied to the use of types.
  • Here are some examples:
  • Class instance creation expression

    new @Interned MyObject();

    Type cast

    myString = (@NonNull String) str;

    implements clause

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

    Thrown exception declaration

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

Footer with Map