When an annotation processor does not process...

In RHQ we have the rest-docs-generator that takes annotations from the code and turns them into xml. As you may have guessed from the last sentence this is implemented as a Java annotation processor and used to work quite well.

Yesterday I wanted to run it on the latest version of the code (we don't run it on every build, as it takes some time with all the backend processing) and it failed. Looking at the processor itself and its test runs did not reveal anything, as they continued to work.

As we use the maven processor plugin, I thought this may fail because we now use Java7 to build (but then I used that before too) and upgraded the plugin, but that did not help. In the end I switched to the maven compiler plugin, which spit out a ton of errors and stacktraces. It turned out, that one of the classes on the classpath had an unsatisfied dependency and the annotation processor just "died" silently before.

After adding the dependency, the errors were gone, but the Processor.init() method was still not called and no processing happened. Looking through tons of output I found this:

Processor <hidden to protect the innocent> matches 
[javax.persistence.PersistenceContext, 
   [……] 
javax.ws.rs.Consumes, 
javax.interceptor.Interceptors, com.wordnik.swagger.annotations.Api, 
javax.ejb.Startup] and returns true.

This "returns true" together with the list of annotations I am interested in means that this other processor that is now in the classpath (probably pulled in when we switched from as4 to as7) swallows all those annotations, so that they are not passed to our processor.

The solution in my case was to explicitly name the rest-docs-generator in the compiler plugin configuration and not to rely on the auto-discovery (I did that in the processor plugin already, but it looks like this had no effect in my case) :

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.0</version>
    <configuration>
      <annotationProcessors>
        <processor>org.rhq.helpers.rest_docs_generator.ClassLevelProcessor</processor>
      </annotationProcessors>
      <proc>only</proc>
      <compilerArguments>
        <AtargetDirectory>${project.build.directory}/docs/xml</AtargetDirectory>
        <AmodelPkg>org.rhq.enterprise.server.rest.domain</AmodelPkg>
        <!-- enable the next line to have the output of the processor shown on console -->
        <!--<Averbose>true</Averbose>-->
      </compilerArguments>
      <!-- set the next to true to enable verbose output of the compiler plugin -->
      <!--<verbose>false</verbose>-->
    </configuration>
    […]

Note that to find the above "Processor .. matches .." output, the compiler plugin must be set to verbose.

I meanwhile also heard that a newer version of that "rouge" processor only looks after its annotations now.