Introduction to Annotation Processing in Eclipse

Disclaimer

This is a BETA release. All APIs contained herein are provisional, and subject to change with subsequent updates.

Testing your APT installation

The APT feature is part of Eclipse 3.2, as of M5a and later. If you wish to use Eclipse 3.1, see the 3.1 installation instructions.

You can verify the installation on either version this way:

  • Create a Java project which contains the file APTDemo.jar in its filesystem.
  • Open the project properties dialog, and go to the Java Compiler / Annotation Processing panel.
  • Check "Enable Project Specific Settings" and "Enable Annotation Processing".
  • Now open the Java Compiler / Annotation Processing / Factory Path panel.
  • Click on Add Jars... and add the APTDemo.jar.
  • Create a new Class, and annotate the class in the source file with @DemoAnnotation(what = "spam").

The "spam" value should be squiggled, with the message "I don't like spam".

  • Annotate the same class with @TypeGeneratingAnnotation
  • Build the project.

A new source directory should appear in the project, named .apt_generated, that will contain a generated Java source file called GeneratedFileTest.java. The generated source directory will not be visible by default in the Package Explorer, because it starts with a '.', but it will be visible in the Navigator.

Installing and Configuring Annotation Processors

An annotation processor can run in Eclipse from a .jar file contained in a project, a .jar file external to the workspace, or a plugin. Jars are added to a workspace or project though the Properties Dialog, Factory Path pane:

For an example of how to set up a plugin project to develop a processor, download APTDemo.jar and explode it into a workspace and import it as an existing project. Eclipse locates plugins along a factory path, which can be configured at the workspace or project level. Workspace configuration is picked up as the default for projects that have annotation processing enabled (see the Properties dialog shown above). If the factory path is configured for an individual project, that project will no longer see changes to the workspace configuration; you will have to update it manually.

A plugin that contains a factory must extend the annotationProcessorFactory extension point. Here is the example from the plugin in APTDemo.jar. Each Factory class contained in the plugin must be named in the class=attribute.

   <extension
         point="org.eclipse.jdt.apt.core.annotationProcessorFactory">
      <factories enableDefault="true">
	      <factory
	         class="demo.TypeGeneratingAnnotationProcessorFactory">
	      </factory>
	      <factory
	         class="demo.DemoAnnotationProcessorFactory">
	      </factory>
      </factories>
   </extension>
			

More details about this will follow when we deliver an SDK version of the feature.

Debugging Annotation Processors in Eclipse

To debug an annotation processor it must be run from a plugin. You develop your code in the plugin, and then debug it by annotating source code in a spawned instance of Eclipse. The debugging instance needs the annotation declaration, the factory, and the processor. The spawned instance only needs access to the declaration.

Problems and Bugs

Symptom: nothing happens, no errors in log file.

  • Make sure that annotation processing is enabled in the Project Properties.

Symptom: annotations not getting processed, log file contains "Bundle not resolved" warnings, ClassNotFound errors or "No Classloader found" errors.

  • Make sure that you are using a 1.5 JVM to run Eclipse. Although most of Eclipse can run on a 1.4 JVM, the APT plugins require a 1.5 JVM.

Please post questions to the JDT newsgroup (eclipse.tools.jdt). Post bugs related to this feature in Bugzilla, under Product JDT, Component APT.

Feature Enable/Disable in Eclipse 3.1.2

If you installed APT as an update to Eclipse 3.1.2 and you have a problem with the compiler, you can disable the feature through the Product Configuration dialog (Menu item Help / Software Updates / Manage Configuration).

Select the JdtAptFeature from your Eclipse installation and click Disable. Your Eclipse will now use the unchanged, original version of the compiler. To re-enable the feature you need to click on the Show Disabled Features on the toolbar of this dialog.