(3618) Writing a Java Annotation Processor for Eclipse

Walter Harley (BEA Systems Inc.), Jess Garms (BEA Systems), Gary Horen (BEA)

Java Development · Short Tutorial
Presentation File
Monday, 08:00, 2 hours | Room 207

Walter Harley

Jess Garms

A Java annotation processor is a compiler plug-in that can read source code as it is being compiled, generate additional Java types or other resource files, and post warnings and errors. With annotation processors, programming problems that might otherwise require convoluted class hierarchies, code preprocessing with scripts, or other techniques that make for unreadable and undebuggable code may be solved with clean, simple syntax that is now a standard part of the Java language. Wrapper and proxy classes can be generated automatically. Semantic inspections such as checking value ranges can be done at compile time rather than at runtime. Annotation processing was introduced in Eclipse 3.2 and has been substantially enhanced in Eclipse 3.3.

However, writing an annotation processor is not easy. Both the com.sun.mirror.apt API supported in Eclipse 3.2, and the new JSR-269 API introduced in Java 6 and Eclipse 3.3, are broad, complex interfaces requiring a sophisticated understanding of how the compiler views and processes Java types. It's easy to call the wrong method and get something that's almost, but not quite, what you need. Furthermore, to provide a good experience for an Eclipse user editing annotated code, you need to consider some IDE-specific matters in your processor design.

Join the team that wrote the Eclipse annotation processing infrastructure for this in-depth tutorial on how to write an efficient annotation processor. Using examples that highlight the real-world issues we've encountered over two years of supporting and writing processors, we'll lead you through:

deciding whether annotation processing is the right solution for you, and which of the available APIs best meets your needs
architecting a processor that it can run both within Eclipse and at the command line
navigating the type model, including generified code
understanding how and when generated types can in turn generate additional types
avoiding pitfalls that can severely affect your processor's performance
efficiently generating files that have multiple parents, such as ejb.xml

To get the most out of this tutorial, you'll need to know how to write Java code, and it will help if you're familiar with Java 5 generics and annotations. You'll leave with an understanding of what problems annotation processors can and cannot solve, and concrete techniques and examples for writing and deploying your own annotation processors to run efficiently in Eclipse.

Walter Harley is a senior software engineer on the BEA Weblogic Workshop Compiler Team, and a committer on the Eclipse APT project. Prior to this, he worked on XML data integration, cryptography, and old-timey things like mainframe terminal emulation and macro assemblers.

Jess Garms is the Eclipse development lead at BEA Systems. Prior to that, he worked on BEA's Java IDE, WebLogic Workshop. Additionally, he has worked extensively with cryptography, and co-authored "Professional Java Security", published by Wrox Press.

Gary Horen is the Program Manager for the BEA Weblogic Workshop Compiler Team. He has been recently focused on the introduction of language technologies into Eclipse, including the Java annotation processing feature.