Core Java

Java Annotation Processors

This article is part of our Academy Course titled Advanced Java.

This course is designed to help you make the most effective use of Java. It discusses advanced topics, including object creation, concurrency, serialization, reflection and many more. It will guide you through your journey to Java mastery! Check it out here!

1. Introduction

In this part of the tutorial we are going to demystify the magic of annotation processing, which is often used to inspect, modify or generate source code, driven only by annotations. Essentially, annotation processors are some kind of plugins of the Java compiler. Annotation processors used wisely could significantly simplify the life of Java developers so that is why they are often bundled with many popular libraries and frameworks.

Being compiler plugins also means that annotation processors are a bit low-level and highly depend on the version of Java. However, the knowledge about annotations from the part 5 of the tutorial How and when to use Enums and Annotations and Java Compiler API from the part 13 of the tutorial, Java Compiler API, is going to be very handy in the understanding of intrinsic details of how the annotation processors work.

2. When to Use Annotation Processors

As we briefly mentioned, annotations processors are typically used to inspect the codebase against the presence of particular annotations and, depending on use case, to:

  • generate a set of source or resource files
  • mutate (modify) the existing source code
  • analyze the exiting source code and generate diagnostic messages

The usefulness of annotation processors is hard to overestimate. They can significantly reduce the amount of code which developers have to write (by generating or modifying one), or, by doing static analysis, hint the developers if the assumptions expressed by a particular annotation are not being hold.

Being somewhat invisible to the developers, annotation processors are supported in full by all modern Java IDEs and popular building tools and generally do not require any particular intrusion. In the next section of the tutorial we are going to build own somewhat naïve annotation processors which nonetheless will show off the full power of this Java compiler feature.

3. Annotation Processing Under the Hood

Before diving into implementation of our own annotation processors, it is good to know the mechanics of that. Annotation processing happens in a sequence of rounds. On each round, an annotation processor might be asked to process a subset of the annotations which were found on the source and class files produced by a prior round.

Please notice that, if an annotation processor was asked to process on a given round, it will be asked to process on subsequent rounds, including the last round, even if there are no annotations for it to process.

In essence, any Java class could become a full-blow annotation processor just by implementing a single interface: javax.annotation.processing.Processor. However, to become really usable, each implementation of the javax.annotation.processing.Processor must provide a public no-argument constructor (for more details, please refer to the part 1 of the tutorial, How to create and destroy objects) which could be used to instantiate the processor. The processing infrastructure will follow a set of rules to interact with an annotation processor and the processor must respect this protocol:

  • the instance of the annotation processor is created using the no-argument constructor of the processor class
  • the init method is being called with an appropriate javax.annotation.processing.ProcessingEnvironment instance being passed
  • the getSupportedAnnotationTypes, getSupportedOptions, and getSupportedSourceVersion methods are being called (these methods are only called once per run, not on each round)
  • and lastly, as appropriate, the process method on the javax.annotation.processing.Processor is being called (please take into account that a new annotation processor instance is not going to be created for each round)

The Java documentation emphasizes that if annotation processor instance is created and used without the above protocol being followed then the processor’s behavior is not defined by this interface specification.

4. Writing Your Own Annotation Processor

We are going to develop several kinds of annotation processors, starting from the simplest one, immutability checker. Let us define a simple annotation Immutable which we are going to use in order to annotate the class to ensure it does not allow to modify its state.

@Target( ElementType.TYPE )
@Retention( RetentionPolicy.CLASS )
public @interface Immutable {
}

Following the retention policy, the annotation is going to be retained by Java compiler in the class file during the compilation phase however it will not be (and should not be) available at runtime.

As we already know from part 3 of the tutorial, How to design Classes and Interfaces, immutability is really hard in Java. To keep things simple, our annotation processor is going to verify that all fields of the class are declared as final. Luckily, the Java standard library provides an abstract annotation processor, javax.annotation.processing.AbstractProcessor, which is designed to be a convenient superclass for most concrete annotation processors. Let us take a look on SimpleAnnotationProcessor annotation processor implementation.

@SupportedAnnotationTypes( "com.javacodegeeks.advanced.processor.Immutable" )
@SupportedSourceVersion( SourceVersion.RELEASE_7 )
public class SimpleAnnotationProcessor extends AbstractProcessor {
  @Override
  public boolean process(final Set< ? extends TypeElement > annotations, 
      final RoundEnvironment roundEnv) {
	    
    for( final Element element: roundEnv.getElementsAnnotatedWith( Immutable.class ) ) {
      if( element instanceof TypeElement ) {
        final TypeElement typeElement = ( TypeElement )element;
				
        for( final Element eclosedElement: typeElement.getEnclosedElements() ) {
	   if( eclosedElement instanceof VariableElement ) {
           final VariableElement variableElement = ( VariableElement )eclosedElement;
		
           if( !variableElement.getModifiers().contains( Modifier.FINAL ) ) {
             processingEnv.getMessager().printMessage( Diagnostic.Kind.ERROR,
               String.format( "Class '%s' is annotated as @Immutable, 
                 but field '%s' is not declared as final", 
                 typeElement.getSimpleName(), variableElement.getSimpleName()            
               ) 
             );						
           }
         }
       }
    }
		
    // Claiming that annotations have been processed by this processor 
    return true;
  }
}

The SupportedAnnotationTypes annotation is probably the most important detail which defines what kind of annotations this annotation processor is interested in. It is possible to use * here to handle all available annotations.

Because of the provided scaffolding, our SimpleAnnotationProcessor has to implement only a single method, process. The implementation itself is pretty straightforward and basically just verifies if class being processed has any field declared without final modifier. Let us take a look on an example of the class which violates this naïve immutability contract.

@Immutable
public class MutableClass {
    private String name;
    
    public MutableClass( final String name ) {
        this.name = name;
    }
    
    public String getName() {
        return name;
    }
}

Running the SimpleAnnotationProcessor against this class is going to output the following error on the console:

Class 'MutableClass' is annotated as @Immutable, but field 'name' is not declared as final

Thus confirming that the annotation processor successfully detected the misuse of Immutable annotation on a mutable class.

By and large, performing some introspection (and code generation) is the area where annotation processors are being used most of the time. Let us complicate the task a little bit and apply some knowledge of Java Compiler API from the part 13 of the tutorial, Java Compiler API. The annotation processor we are going to write this time is going to mutate (or modify) the generated bytecode by adding the final modifier directly to the class field declaration to make sure this field will not be reassigned anywhere else.

@SupportedAnnotationTypes( "com.javacodegeeks.advanced.processor.Immutable" )
@SupportedSourceVersion( SourceVersion.RELEASE_7 )
public class MutatingAnnotationProcessor extends AbstractProcessor {
  private Trees trees; 
    
  @Override
  public void init (ProcessingEnvironment processingEnv) {
    super.init( processingEnv );
    trees = Trees.instance( processingEnv );        
  }
    
  @Override
  public boolean process( final Set< ? extends TypeElement > annotations, 
      final RoundEnvironment roundEnv) {
	    
    final TreePathScanner< Object, CompilationUnitTree > scanner = 
      new TreePathScanner< Object, CompilationUnitTree >() {
        @Override
    	 public Trees visitClass(final ClassTree classTree, 
           final CompilationUnitTree unitTree) {

         if (unitTree instanceof JCCompilationUnit) {
           final JCCompilationUnit compilationUnit = ( JCCompilationUnit )unitTree;
                        
           // Only process on files which have been compiled from source
           if (compilationUnit.sourcefile.getKind() == JavaFileObject.Kind.SOURCE) {
             compilationUnit.accept(new TreeTranslator() {
               public void visitVarDef( final JCVariableDecl tree ) {
                 super.visitVarDef( tree );
                                    
                 if ( ( tree.mods.flags & Flags.FINAL ) == 0 ) {
                   tree.mods.flags |= Flags.FINAL;
                 }
               }
             });
           }
         }
    
        return trees;
      }
    };
	    
    for( final Element element: roundEnv.getElementsAnnotatedWith( Immutable.class ) ) {    
      final TreePath path = trees.getPath( element );
      scanner.scan( path, path.getCompilationUnit() );
    } 
		
    // Claiming that annotations have been processed by this processor 
    return true;
  }
}

The implementation became more complex, however many classes (like TreePathScanner, TreePath) should be already familiar. Running the annotation processor against the same MutableClass class will generate following byte code (which could be verified by executing javap -p MutableClass.class command):

public class com.javacodegeeks.advanced.processor.examples.MutableClass {
  private final java.lang.String name;
  public com.javacodegeeks.advanced.processor.examples.MutableClass(java.lang.String);
  public java.lang.String getName();
}

Indeed, the name field has final modifier present nonetheless it was omitted in the original Java source file. Our last example is going to show off the code generation capabilities of annotation processors (and conclude the discussion). Continuing in the same vein, let us implement an annotation processor which will generate new source file (and new class respectively) by appending Immutable suffix to class name annotated with Immutable annotation.

@SupportedAnnotationTypes( "com.javacodegeeks.advanced.processor.Immutable" )
@SupportedSourceVersion( SourceVersion.RELEASE_7 )
public class GeneratingAnnotationProcessor extends AbstractProcessor {
  @Override
  public boolean process(final Set< ? extends TypeElement > annotations, 
      final RoundEnvironment roundEnv) {
	    
    for( final Element element: roundEnv.getElementsAnnotatedWith( Immutable.class ) ) {
      if( element instanceof TypeElement ) {
        final TypeElement typeElement = ( TypeElement )element;
        final PackageElement packageElement = 
          ( PackageElement )typeElement.getEnclosingElement();

        try {
          final String className = typeElement.getSimpleName() + "Immutable";
          final JavaFileObject fileObject = processingEnv.getFiler().createSourceFile(
            packageElement.getQualifiedName() + "." + className);
                    
          try( Writer writter = fileObject.openWriter() ) {
            writter.append( "package " + packageElement.getQualifiedName() + ";" );
            writter.append( "\\n\\n");
            writter.append( "public class " + className + " {" );
            writter.append( "\\n");
            writter.append( "}");
          }
        } catch( final IOException ex ) {
          processingEnv.getMessager().printMessage(Kind.ERROR, ex.getMessage());
        }
      }
    }
		
    // Claiming that annotations have been processed by this processor 
    return true;
  }
}

As the result of injecting this annotation processor into compilation process of the MutableClass class, the following file will be generated:

package com.javacodegeeks.advanced.processor.examples;

public class MutableClassImmutable {
}

Nevertheless the source file and its class have been generated using primitive string concatenations (and it fact, this class is really very useless) the goal was to demonstrate how the code generation performed by annotation processors works so more sophisticated generation techniques may be applied.


 

5. Running Annotation Processors

The Java compiler makes it easy to plug any number of annotation processors into the compilation process by supporting –processor command line argument. For example, here is one way of running MutatingAnnotationProcessor by passing it as an argument of javac tool during the compilation of MutableClass.java source file:

javac -cp processors/target/advanced-java-part-14-java7.processors-0.0.1-SNAPSHOT.jar 
  -processor com.javacodegeeks.advanced.processor.MutatingAnnotationProcessor    
  -d examples/target/classes
  examples/src/main/java/com/javacodegeeks/advanced/processor/examples/MutableClass.java 

Compiling just one file does not look very complicated but real-life projects contain thousands of Java source files and using javac tool from command line to compile those is just overkill. Likely, the community has developed a lot of great build tools (like Apache Maven, Gradle, sbt, Apache Ant, …), which take care of invoking Java compiler and doing a lot of other things, so nowadays most of Java project out there use at least one of them. Here, for example, is the way to invoke MutatingAnnotationProcessor from Apache Maven build file (pom.xml):

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.1</version>
  <configuration>
    <source>1.7</source>
    <target>1.7</target>
    <annotationProcessors>
<proc>com.javacodegeeks.advanced.processor.MutatingAnnotationProcessor</proc>
    </annotationProcessors>
  </configuration>
</plugin>

6. What’s next

In this part of the tutorial we have taken a deep look on annotation processors and the ways they help to inspect the source code, mutate (modify) resulting bytecode or generate new Java source files or resources. Annotation processors are very often used to free up Java developers from writing tons of boilerplate code by deriving it from annotations spread across codebase. In the next section of the tutorial we are going to take a look on Java agents and the way to manipulate how JVM interprets bytecode at runtime.

7. Download the source code

You can download the source code of this lesson here: advanced-java-part-14

Andrey Redko

Andriy is a well-grounded software developer with more then 12 years of practical experience using Java/EE, C#/.NET, C++, Groovy, Ruby, functional programming (Scala), databases (MySQL, PostgreSQL, Oracle) and NoSQL solutions (MongoDB, Redis).
Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

8 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Viktor
Viktor
8 years ago

Excelent article!

Jacques
Jacques
7 years ago

Very clear, thank you

Gerald
Gerald
7 years ago

Excellent fundamentals of annotation processing

Greg Hall
Greg Hall
7 years ago

Good article.

Your SimpleAnnotationProcessor example assumes all VariableElements are fields – but acc to JavaDocs this type also refers to method parameters and local variables. So you’re really forcing all of those things to be final, not just fields. I assume for fields, that the VariableEment.getEnclosingElement() is the TypeElement of the class containing the field, so you should add a check for that.

Andriy Redko
7 years ago
Reply to  Greg Hall

Hi Greg,

Thank you for your comment. Yes, you are right, the variable declaration is not applied to fields only. The SimpleAnnotationProcessor should either do the check (as you pointed out) or change error message to be more generic. Thank you.

Diana Eftaiha
Diana Eftaiha
6 years ago

Thank you for sharing, Andrey

Massimo
5 years ago

Great article, thank you.
I want to point out that marking every field as final is not enough to ensure immutability. A mutable final field can change its state.

Andriy Redko
5 years ago
Reply to  Massimo

Thank you, you are absolutely correct. But, if the object behind the final field does also declare its field as final (and so on down the hierarchy of composition), there won’t be a suitable operation to change the state. However, as you pointed out, there is no easy way to enforce that and, by and large, any final field may change its state.

Back to top button