Question

I am considering starting a project which is used to generate code in Java using annotations (I won’t get into specifics, as it’s not really relevant). I am wondering about the validity and usefulness of the project, and something that has struck me is the dependence on the Annontation Processor Tool (apt).

What I’d like to know, as I can’t speak from experience, is what are the drawbacks of using annotation processing in Java?

These could be anything, including the likes of:

• it is hard to do TDD when writing the processor
• it is difficult to include the processing on a build system
• processing takes a long time, and it is very difficult to get it to run fast
• using the annotations in an IDE requires a plugin for each, to get it to behave the same when reporting errors

These are just examples, not my opinion. I am in the process of researching if any of these are true (including asking this question 😉 )

I am sure there must be drawbacks (for instance, Qi4J specifically list not using pre-processors as an advantage) but I don’t have the experience with it to tell what they are.

The ony reasonable alternative to using annotation processing is probably to create plugins for the relevant IDEs to generate the code (it would be something vaguely similar to override/implement methods feature that would generate all the signatures without method bodies). However, that step would have to be repeated each time relevant parts of the code changes, annotation processing would not, as far as I can tell.

In regards to the example given with the invasive amount of annotations, I don’t envision the use needing to be anything like that, maybe a handful for any given class. That wouldn’t stop it being abused of course.

Answer 1

I created a set of JavaBean annotations to generate property getters/setters, delegation, and interface extraction (edit: removed link; no longer supported)

Testing

Testing them can be quite trying…

I usually approach it by creating a project in eclipse with the test code and building it, then make a copy and turn off annotation processing.

I can then use Eclipse to compare the "active" test project to the "expected" copy of the project.

I don’t have too many test cases yet (it’s very tedious to generate so many combinations of attributes), but this is helping.

Build System

Using annotations in a build system is actually very easy. Gradle makes this incredibly simple, and using it in eclipse is just a matter of making a plugin specifying the annotation processor extension and turning on annotation processing in projects that want to use it.

I’ve used annotation processing in a continuous build environment, building the annotations & processor, then using it in the rest of the build. It’s really pretty painless.

Processing Time

I haven’t found this to be an issue – be careful of what you do in the processors. I generate a lot of code in mine and it runs fine. It’s a little slower in ant.

Note that Java6 processors can run a little faster because they are part of the normal compilation process. However, I’ve had trouble getting them to work properly in a code generation capacity (I think much of the problem is eclipse’s support and running multiple-phase compiles). For now, I stick with Java 5.

Error Processing

This is one of the best-thought-through things in the annotation API. The API has a "messenger" object that handles all errors. Each IDE provides an implementation that converts this into appropriate error messages at the right location in the code.

The only eclipse-specific thing I did was to cast the processing environment object so I could check if it was bring run as a build or for editor reconciliation. If editing, I exit. Eventually I’ll change this to just do error checking at edit time so it can report errors as you type. Be careful, though — you need to keep it really fast for use during reconciliation or editing gets sluggish.

Code Generation Gotcha

[added a little more per comments]

The annotation processor specifications state that you are not allowed to modify the class that contains the annotation. I suspect this is to simplify the processing (further rounds do not need to include the annotated classes, preventing infinite update loops as well)

You can generate other classes, however, and they recommend that approach.

I generate a superclass for all of the get/set methods and anything else I need to generate. I also have the processor verify that the annotated class extends the generated class. For example:

@Bean(...) public class Foo extends FooGen 

I generate a class in the same package with the name of the annotated class plus "Gen" and verify that the annotated class is declared to extend it.

I have seen someone use the compiler tree api to modify the annotated class — this is against spec and I suspect they’ll plug that hole at some point so it won’t work.

I would recommend generating a superclass.

Overall

I’m really happy using annotation processors. Very well designed, especially looking at IDE/command-line build independence.

For now, I would recommend sticking with the Java5 annotation processors if you’re doing code generation – you need to run a separate tool called apt to process them, then do the compilation.

Note that the API for Java 5 and Java 6 annotation processors is different! The Java 6 processing API is better IMHO, but I just haven’t had luck with java 6 processors doing what I need yet.

When Java 7 comes out I’ll give the new processing approach another shot.

Feel free to email me if you have questions. ([e-mail])

Hope this helps!