In Java, annotations and annotation processors are surrounded by a shroud of mystery for most. They seem like a subject reserved for "experts". On top of that, I believe there’s also some FUD around them.

Annotations are available since Java version 5, codenamed Tiger, and released in 2004.

In the Java computer programming language, an annotation is a form of syntactic metadata that can be added to Java source code. Classes, methods, variables, parameters and Java packages may be annotated.
— Wikipedia
//en.wikipedia.org/wiki/Java_annotation

@MyAnnotation public class Foo {}

Replacement of marker interfaces

Since Java’s inception, there has been a need to mark a class, or a hierarchy
of classes. Before Java 5, this has been done through interfaces with no methods.

Serializable

Cloneable

public class Foo implements MarkerInterface {} // 1

@MyAnnotation
public class Foo {}         // 2                   

1. Marker interface
2. Annotation equivalent to the marker interface

Better metadata management

/**
 * Blah blah JavaDoc.
 *
 * @deprecated As of JDK version 1.1,
 */
public class DeprecatedApi {}

Obviously, this is a very fragile approach: the only way to leverage it is via the

javadoc

javadoc

@deprecated

Java 5, deprecation is flagged with the provided

@Deprecated

/**
 * Blah blah JavaDoc.
 */
@Deprecated
public class DeprecatedApi {}

NOTE: Old deprecated APIs keep the old approach, so they use both metadata and annotation.

Additionally, since Java 9,

@Deprecated

1. forRemoval

   (of type

   boolean

   ): indicates whether the annotated element is subject to removal in a future version

2. since

   (of type String): returns the version in which the annotated element became deprecated

@Deprecated(since="1.2", forRemoval=true)
public abstract class IdentityScope extends Identity {}

Creating an annotation

To create an annotation, one uses the

@interface

public @interface MyAnnotation {}

• A target: this defines where the annotation can be set
• A retention: this describes up to which step in the compilation process the annotation will be available

We will get into more detail later. As for now, we first need to
understand how annotations work. While classes inherit code from their
parent class(es), annotations are composed.

@Target(ElementType.ANNOTATION_TYPE)  // 1     
@interface Foo {}

@Target(ElementType.ANNOTATION_TYPE)  // 1   
@interface Bar {}

@Foo
@Bar
@interface Baz {}                      // 2

1. This is the required

   @Target

   , it will be explained further down
2. Something annotated with

   @Baz

   is transitively annotated with both

   @Foo

   and

   @Bar

Here’s the source code of

@Target

@Retention

@Retention(RetentionPolicy.RUNTIME)    // 2
@Target(ElementType.ANNOTATION_TYPE)   // 1
public @interface Target {           
    ElementType[] value();
}@Retention(RetentionPolicy.RUNTIME)   // 2
@Target(ElementType.ANNOTATION_TYPE)  // 1
public @interface Retention {        
    RetentionPolicy value();
}

1. The

   @Target

   annotations tells on which element the annotation can be set:

• On a type e.g. a class or an interface
• On another annotation
• On a field
• On a method
• On a constructor
• On a method parameterOn a local variableOn a moduleetc.

1. The

   @Retention

   annotation defines up to which step in the compilation process the annotation will be available:

• Only the source code
• In the class file
• At runtime

Annotation parameters

Annotations can define parameters. Parameters allow to add some level of configuration at the time the annotation is used. A parameter accepts a type and an optional default value. If the value is not set when the annotation is defined, it needs to be when it is used.

• Any primitive type e.g.

  int

  ,

  long

  , etc.

• String

• Class<T>

• Any

  enum

  type
• Another annotation type
• Any array of the above

@Target(ElementType.CLASS)
@interface Foo {
  int bar();
  Class<? extends Collection> baz() default List.class;
  String[] qux();
}@Foo(bar = 1, qux = { "a", "b", "c" })
class MyClass {}

If there’s a single parameter and it’s named value, its name can be omitted when set:

@Target(ElementType.CLASS)
@interface Foo {
    int value();
}@Foo(1)
class MyClass {}

Handling annotations at runtime: reflection

Since its inception, Java has allowed reflection: reflection is the capacity to get information about the code at runtime. Here’s a sample:

var session = request.getHttpSession();
var object = session.getAttribute("objet");  // 1       
var clazz = object.getClass();               // 2       
var methods = clazz.getMethods();            // 3       
for (var method : methods) {
    if (method.getParameterCount() == 0) {   // 4       
        method.invoke(foo);                  // 5       
    }
}

1. Get an object stored in the session
2. Get the runtime class of the object
3. Get all

   public

   methods available on the object
4. If the method has no parameter
5. Call the method

With
annotation, frameworks started to make use of them for different
use-cases. Among them, configuration was one of the most used: for
example, instead of (or more precisely in addition to) XML, the added a configuration option based on annotations.

Handling annotations at compile-time: annotation processors

An alternative to cope with that issue is to process annotations at compile-time. For that to happen, the compiler must be configured to use specific annotation processors. Those can have different outputs: simple files, generated code, etc. The tradeoff of that approach is that compilation takes a performance hit every time, but then startup time is not impacted.

However, recently, back-end frameworks such as and
also adopted this approach. The aim is to reduce application startup time through compile-time code generation in replacement of runtime introspection. Additionally, Ahead-of-Time compilation of the resulting bytecode to native code further reduces startup time, as well as memory consumption.

The world of annotation processors is huge: this section is a but a very
small introduction so one can proceed further if wanted.

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.8.1</version>
      <configuration>
        <annotationProcessors>
          <annotationProcessor>
            ch.frankel.blog.SampleProcessor
          </annotationProcessor>
        </annotationProcessors>
      </configuration>
    </plugin>
  </plugins>
</build>

The processor itself needs to implement

Processor

AbstractProcessor

AbstractProcessor

Let’s create a very simple processor. It should only lists classes that
are annotated with specific annotations. Real-world annotation
processors would probably do something useful e.g. generate code, but this additional logic goes well beyond the scope of this post.

@SupportedAnnotationTypes("ch.frankel.blog.*")                  // 1          
@SupportedSourceVersion(SourceVersion.RELEASE_8)
public class SampleProcessor extends AbstractProcessor {  @Override
  public boolean process(Set<? extends TypeElement> annotations,// 2       
               RoundEnvironment env) {
    annotations.forEach(annotation -> {                         // 3       
      Set<? extends Element> elements =
                      env.getElementsAnnotatedWith(annotation); // 4
      elements.stream()
        .filter(TypeElement.class::isInstance)                   // 5               
        .map(TypeElement.class::cast)                           // 6       
        .map(TypeElement::getQualifiedName)                      // 7       
        .map(name -> "Class " + name + " is annotated with " + annotation.getQualifiedName())
        .forEach(System.out::println);
    });
    return true;
  }
}

1. Processor

   will be called for every annotation that belongs to the

   ch.frankel.blog

   package

2. process()

   is the main method to override
3. The loop will be called for each annotation
4. The annotation is not as interesting as the element annotated with it. This is the way to get the annotated element.
5. Depending on which element is annotated, it needs to be cast to the correct

   Element

   subinterface. Here, only classes can be annotated, hence, the variable needs to be tested to check whether it’s assignable

   TypeElement

   to access its additional attributes further down the operation chain
6. We want the qualified name of the class the annotation is set on, so it’s
   necessary to cast it to the type that makes this specific attribute
   accessible
7. Get the qualified name from

   TypeElement

Conclusion

Annotations are very powerful, whether used at runtime or at compile-time. On the flip side, the biggest issue is that they seem to work like magic: there’s no easy way to know which reflection-using class or annotation processor is making use of them. It’s up to everyone in one’s own context to decide whether their pros out-weight their cons. To use them without any forethinking does a great disservice to one’s code…​ a
disservice just as great as discarding them because of misplaced
ideology.

To go further:

First published on April 26th 2020 on