Java Annotation Processors

Annotation processors may be used to generate codes.

http://deors.wordpress.com/2011/09/26/annotation-types/

http://deors.wordpress.com/2011/10/08/annotation-processors/

http://deors.wordpress.com/2011/10/31/annotation-generators/

Annotation Processor

• implements javax.annotation.processing.Processor
• for convenience, common function is provided in javax.annotation.processing.AbstractProcessor
  • processEnv - the ProcessingEnvironment
• configure custom processor with three annotations
  • javax.annotation.processing.SupportedAnnotationTypes - register the annotations this processor handles; values are fully qualified names of annotation types, wildcards are allowed
  • javax.annotation.processing.SupportedSourceVersion - register the source version
  • javax.annotation.processing.SupportedOptions - supported options may be passed through command line
• implement the process() method
  • the annotation processing is done in one or several rounds, in each round the processors are called
  • parameters:
    • Set<? extends TypeElement> annotations - annotations being processed in the current round
    • RoundEnvironment roundEnv - gives access to the annotated source elements being processed in the current and previous round
  • ProcessingEnvironment - obtain from RoundEnvironment
    • access to log - getMessager().printMessage()
    • get Element
      • reflective methods - getAnnotation, etc.

Packaging:

• package in a JAR
• include a directory META-INF/services
  • include a file named javax.annotation.processing.Processor
  • white the fully qualified names of the processors contained in the JAR file, one per line

Eclipse Note

Add dependent jars also to factory path

Round Processing Mechanism

(refers to Processor JavaDoc)

Each round:

• one processor is asked to process a subset of annotations
  • then the processor will also process subsequent rounds, even no annotation to process
  • same processor instance is not used (not new instances)
• discovery for processor to run, depends on tools and specific configuration, and is a function of:
  • annotation in root elements
  • annotation types the processor processes
  • whether the processor claims the annotation type

Generate Source Code

MDE

• model : represents the abstraction of the software system
• meta-model : rules that use to write the models
  • in this case, annotation types will act as meta-models

Filer (javax.annotation.processing.Filer)

• defines some methods for creating source files, class files or generic resources
• take care of the right directories for source codes

(bad) Sample: generating code

 if (e.getKind() == ElementKind.CLASS) {

     TypeElement classElement = (TypeElement) e;

     PackageElement packageElement =

         (PackageElement) classElement.getEnclosingElement();

     JavaFileObject jfo = processingEnv.getFiler().createSourceFile(

         classElement.getQualifiedName() + "BeanInfo");

     BufferedWriter bw = new BufferedWriter(jfo.openWriter());

     bw.append("package ");

     bw.append(packageElement.getQualifiedName());

     bw.append(";");

     bw.newLine();

     bw.newLine();

     // rest of generated class contents

Using Apache Velocity

• Velocity Template Language (VTL)

the approach:

• write template
  • refer to http://velocity.apache.org/engine/devel/vtl-reference-guide.html
• Annotation Processor (AP) read the round environment, save in easy to access Java objects
  • maps of fields, methods, class and package names, and so forth
• AP initialize Velocity context
• AP load Velocity template
• AP create source file using Filer, pass writer to Velocity Template with context
• Velocity engine generate source code

(samples at http://deors.wordpress.com/2011/10/31/annotation-generators/)

Limitations

• No way to obtain the annotated class - remember this is in compiling process!
• Can only use Element API

Problem Note

Oracle JDK javac 1.7.0_51

• messenger from environment don't work well - javac only outputs messages when all is right. then when something is wrong, debug information is not shown. have to use System.out.....
• one javac session only invokes one processor, even multiple is given in javax.annotation.processing.Processor, or multiple entry in -processor parameter...; have to call javac multiple times from shell command

Debugging

Eclipse annotation processor feature is only suitable for running annotation processors, not developing and debugging.

To develop and debug,

1. run javac and pass debugger parameters, to suspense the process and open a debug port
2. debug remote application in Eclipse

to achieve (1), I created a shell script. Note DEBUGJAVAC is not used, which is to be put in Eclipse external tools environment. To create Eclipse external tools entry, "Run -> External Tools -> External Tools Configurations"

to achieve (2), "Project (context menu) -> debug -> debug configurations"

#!/bin/sh

# usage: debug.sh [-verbose]

export CURPATH=`pwd`

cd ..

# Project base

export PROJBASE="."

# Project MDE(Annotation) build target

export PROJANNOBIN="$PROJBASE/target/mdebin"

# Folder to place the generated source codes

export GENTARGET="$PROJBASE/target/generated-sources/mde"

# Common annotation processor project

export ANNOPROJ="/home/bing/git/EastIPAnnotationProcessor"

# A temp folder, to place the compiled classes

export TEMP="/home/bing/tmp/annotationProc"

# The generated Annotation Processor jar file

export JARFILE="$TEMP/AnnotationProcessor.jar"

# Other dependencies

export CLASSPATH_DEP="/home/bing/Software_n_Docs/Development/Velocity/velocity-1.7/velocity-1.7.jar:/home/bing/Software_n_Docs/Development/Velocity/velocity-1.7/velocity-1.7-dep.jar:/home/bing/.m2/repository/javax/javaee-api/6.0/javaee-api-6.0.jar"

# path to the source to be compiled (processed)

export SOURCEPATH="/home/bing/workspace/VaadinJeeIntestEjbBackend/ejbModule"

###################################################################################

export CLASSPATH="$JARFILE:$CLASSPATH_DEP"

echo "CLASSPATH=$CLASSPATH"

export WARNINGLEVEL=""

# export WARNINGLEVEL="-Xlint:-cast,-classfile,-deprecation,-dep-ann,-divzero,-empty,-fallthrough,-finally,-options,-overrides,-path,processing,-rawtypes,-serial,-static,-try,-unchecked,-varargs"

# DEBUGJAVAC can be put into Eclipse External Tool environment, for command line, just run

# export DEBUGJAVAC="-J-Xdebug -J-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005"

rm -fr $TEMP/*

rm -fr $GENTARGET/*

if [ -f $JARFILE ];then

    rm -f $JARFILE;

fi

jar -cf $JARFILE -C $ANNOPROJ/bin .

jar -uf $JARFILE -C $PROJANNOBIN .

for p in `cat MDEProcessorList`; do

echo "Processor: $p"

echo "--------------------------------------------------------------------------------------"

    for i in `cat MDETargetList`;do

        echo "Compiling $i"

        javac $DEBUGJAVAC -XprintRounds -XprintProcessorInfo -proc:only -processor $p $WARNINGLEVEL -g $1 -d $TEMP -s $GENTARGET -sourcepath $SOURCEPATH $i

        echo "Compiling done."

    done

done

echo "**** Checking temp *****"

ls $TEMP

echo "**** Checking test/generated *****"

ls $GENTARGET

cd $CURPATH