Musings on JDK development

Annotation Processor SourceVersion

In annotation processing there are three distinct roles,
title="JavaOne 2005: Annotation Processing for the Java™ Programming Language">the author of the annotation types, the author of the annotation processor, and the client of the annotations. The third role includes the responsibility to configure the compiler correctly, such as
title="Build Advice: Set Source, Target, and Encoding">setting the source, target, and encoding options and
title="Annotation Processing Build Advice: Set source and class file destinations">setting the source and class file destination for annotation processing.
The author of the annotation processor shares a related responsibility: property returning the source version supported by the processor.

Most processors can be written against a particular source version and always return that source version, such as by including a @SupportedSourceVersion annotation on the processor class.
In principle, the annotation processing infrastructure could tailor the view of newer-than-supported language constructs to be more compatible with existing processors. Conversely, processors have the flexibility to implement
title="http://blogs.sun.com/darcy/entry/jdk_6_build_101_jsr">their own policies when encountering objects representing newer-than-supported structures.
In brief, by extending version-specific abstract visitor classes, such as
AbstractElementVisitor6 and
AbstractTypeVisitor6, the visitUnknown method will be called on entities newer than the version in question.

Just as regression tests inside the JDK itself should by default follow a dual policy of accepting the default source and target settings rather than setting them explicitly like other programs, annotation processors used for testing with the JDK should generally support the latest source version and not be constrained to a particular version. This allows any issues or unexpected interactions of new features to be found more quickly and keeps the regression tests exercising the most recent code paths in the compiler.

This dual policy is now consistently implemented in the langtools regression tests as of build 85 of JDK 7 (title="Annotation processing regression tests should typically return SourceVersion.latest">6926699).

Join the discussion

Comments ( 2 )
  • Neal Gafter Friday, March 12, 2010

    Presumably, this advice isn't intended to negate the requirement to have regression tests that explicitly test the behavior of newer or older annotation processors versus older or newer source versions.

  • Joe Darcy Friday, March 12, 2010


    Correct; most annotation processors should "generally support the latest source version" because they are not targeting version-specific functionality . Tests that are targeting version-specific functionality should explicitly use older-newer source versions as appropriate.

Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.