Thursday, October 25, 2012

Writing an Annotation Based Processor in Java

The code for this tutorial is on GitHub: https://github.com/travisdazell/Annotation-Based-Processor

Annotations have been around since Java 5. They provide a way to mark (i.e. annotate) Java code in a clean and concise manner. With Java 6 and 7, we can do even more with annotations. The most exciting of which, in my opinion, is the ability to write our own annotations and even process our own annotations to detect code issues or even generate source code at compile time.

In this example, we'll create an annotation named @Metrics. We'll be able to mark Java classes with @Metrics and at compile-time, generate a report of all methods defined in the class. To create your own annotation and its corresponding processor, follow these steps.

  1. Define the annotation. This is done by defining the annotation with @interface.
     public @interface Metrics {
     }

  
     2. We can now annotate any class in our project with our new annotation.

     import net.travisdazell.annotations.Metrics;

     @Metrics
     public class CustomerDaoImpl implements CustomerDao {
        public Customer getCustomer(int customerId) {
           // return Customer record
        }
     }


     3. The next step is to write a processor that, at compile time, will report all of the methods defined in CustomerDaoImpl.java. Here's our processor in its entirety.


package net.travisdazell.annotations.processors;

import java.lang.reflect.Method;
import java.util.Set;

import javax.annotation.processing.AbstractProcessor;
import javax.annotation.processing.RoundEnvironment;
import javax.annotation.processing.SupportedAnnotationTypes;
import javax.annotation.processing.SupportedSourceVersion;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.TypeElement;
import javax.tools.Diagnostic;

import net.travisdazell.annotations.Metrics;

@SupportedAnnotationTypes("net.travisdazell.annotations.Metrics")
@SupportedSourceVersion(SourceVersion.RELEASE_6)
public class MetricsProcessor extends AbstractProcessor {
   
    @Override
    public boolean process(Set<? extends TypeElement> arg0,
            RoundEnvironment roundEnv) {

        StringBuilder message = new StringBuilder();

        for (Element elem : roundEnv.getElementsAnnotatedWith(Metrics.class)) {
            Metrics implementation = elem.getAnnotation(Metrics.class);

            message.append("Methods found in " + elem.getSimpleName().toString() + ":\n");

            for (Method method : implementation.getClass().getMethods()) {
                message.append(method.getName() + "\n");
            }

            processingEnv.getMessager().printMessage(Diagnostic.Kind.NOTE, message.toString());
        }

        return false; // allow others to process this annotation type
    }
}


    4. Next, we need to package our annotation processor and annotation in a JAR file. We must also include a META-INF\services directory in our JAR file. Within the services directory, include a file named javax.annotation.processing.Processor. In that file, type the fully qualified name of the annotation processor.



Here's what my JAR file looks like when exploded in Eclipse.



5. Next, to test our annotation processor, create a class and annotate it with @Metrics.

package net.travisdazell.projects.testproject.dao.impl;

import net.travisdazell.annotations.Metrics;

@Metrics
public class CustomerDaoImpl {
}



6.When we compile this class, we'll get a message displaying the list of methods in the class. As expected, we see what's been inherited from java.lang.Object.




9 comments:

  1. Thanks. Article was informative.

    ReplyDelete
  2. Thanks. Very good tutorial.

    ReplyDelete
  3. I was using java 6 compiler and building using maven butt when I try to build it gives me following exception

    Bad service configuration file, or exception thrown while constructing Processor object: javax.annotation.processing.Processor

    ReplyDelete
    Replies
    1. I'll try it with Java 6 and see if I can recreate the issue. I assume you're using the HotSpot compiler?

      Delete
  4. How can I check whether if its working? can you provide sample classes? there's no CustomerDaoImpl.. thank you.

    ReplyDelete
  5. Please make a sample of working sample annotation processor with test java classes. thank you. will be waiting for your reply.

    ReplyDelete
  6. Very nice.. Thanks

    ReplyDelete
  7. Nice article:

    Without eclipse, to create jar file command-line

    1.) I had to compile annotation processors inside src directory using:
    javac $(find . -name '*.java') -proc:none

    2.) Copy META-INF inside src directory and then inside src directory
    jar -cvf annotationprocessor.jar *

    3.) Compile the demo class :

    javac -cp annotationprocessor.jar





    ReplyDelete