A Java annotation processor is a compiler plug-in that can gather information about source code as it is being compiled, generate additional Java types or other resource files, and post warnings and errors. Eclipse 3.2 provided support for annotation processors using the Java 5 Mirror APIs, and Eclipse 3.3 added support for processors using the Java 6 annotation processing APIs.
Both Java 5 and Java 6 annotation processors can be called during a build. Errors and warnings produced by the processors will be reported in the Problems view, and build artifacts will be created just as if you were running Sun's apt tool (for Java 5) or javac compiler (for Java 6) from the command line.
Java 5 processors can also be executed as you are typing in the editor. This permits processors
to report errors during editing, which may be helpful. This feature can
be enabled or disabled via the annotation processor properties dialog.
In addition to reporting errors, Java 5 processors can also generate files as you are typing in the editor.
This feature is only enabled if the processor includes "enableTypeGenerationInEditor" in
the set of strings it returns from its implementation of
AnnotationProcessorFactory.supportedOptions(). This string is defined in
the class org.eclipse.jdt.apt.core.AptPreferenceConstants.
Eclipse does not support executing Java 6 processors while typing in the editor; you must save and build in order for Java 6 processors to report errors or generate files.
For more detailed information about how the APT plugins work and how to write annotation processors of your own, you can view the JDT-APT project web site.
javax.tools.JavaCompiler interface. Java 5 annotation processors
are not available in this way, but Java 6 annotation processors are fully supported.
Java 6 processors will only be run if the project's Java compiler compliance level is set to Java 6 or higher, and Eclipse is running on a Java 1.6 or higher JVM.
Next you need to enable annotation processing under Java->Compiler->Annotation Processing:
In this dialog you can also specify the generated source directory if desired, and provide any processor options that are necessary.
For details, see the documentation on the annotation processing preferences.
Processors can be contained in jar files or in Eclipse plug-ins. The Factory Path list includes both Java 5 and Java 6 processors.
The annotation processors used in a project must exist in binary form (as jar files or plug-ins) before the project is built. Therefore it is not possible to include both processor code and code to be processed within the same project. Developers of annotation processors are advised to keep annotation processor projects separate from the projects containing the target code that is to be processed. Indeed it may be preferable to keep them in separate workspaces, to facilitate debugging.
The factory path is stored in a file named ".factorypath" at the project root, similar to the classpath, and should be treated the same way as the classpath with regard to version control. In order to avoid hard-coding paths to factory jars, you can either use project-relative jars via the "Add Jars..." button, or use a classpath variable via the "Add Variable..." button.
Processor options are stored in the .settings folder within each project, which is also where other compiler options are stored. All files within the .settings folder are typically managed with source control. You may need to use paths as some of the options passed to your annotation processors. Again, by avoiding hard-coding of absolute paths you'll be able to share your configuration in source control. To permit this, Eclipse supports using variables in processor options. For details, see the processor options documentation.