JSR 269 Maintenance Review

JSR 269 was bundled as a component of JSR 270, the umbrella JSR for Java SE 6. The APIs defined by JSR 269 need to be updated to model the language changes being made by Project Coin / JSR 334. JSR 334 in turn is a component of JSR 336, the umbrella JSR for Java SE 7, and the maintenance review of JSR 269 is expected to be bundled with JSR 336. In addition to changes to directly support new language features, the JSR 269 API would benefit from a number of corrections and enhancements to improve ease of use.

The JSR 269 language model follows somewhat different evolution rules than most APIs included in Java SE. In particular, while the changes to the API are binary compatible, certain source incompatible changes are made of necessity. In particular, methods can be added to the visitor interfaces to allow operations on newly-added language constructs to be performed. This evolution path was expected during JSR 269's development and for that reason developers were warned to not directly implement the visitor interfaces, but rather to extend one of the visitor utility classes. The utility classes are versioned per release and implement default behavior appropriate for that release.

Change Log

The following are proposed changes for JSR 269:

• Clarified interaction between the Filer and rounds.

• Constructors explicitly added to the kinds of elements that can be returned by RoundEnvironment.getElementsAnnotatedWith.

• New enum constant javax.lang.model.SourceVersion.RELEASE_7.

• In the package description of javax.lang.model.element, requirements on when a model must be provided are loosened to remove the requirement in case of an "irrecoverable error that could not be removed by the generation of new types," a condition which includes but is not limited to syntax errors.

• New exception type javax.lang.model.UnknownEntityException added as a common superclass for existing exception types UnknownAnnotationValueException, UnknownElementException, and UnknownTypeException.

• New enum constant javax.lang.model.element.ElementKind.RESOURCE_VARIABLE.

• New mixin interfaces Parameterizable and QualifiedNameable added to package javax.lang.model.element. ExecutableElement and TypeElement are retrofitted to extend Parameterizable; PackageElementand TypeElement are retrofitted to extend QualifiedNameable.

• Behavior of getEnclosingElement method defined to return the generic element of a type parameter instead of null.

• New interface javax.lang.model.type.UnionType to model union types.

• New enum constant javax.lang.model.type.TypeKind.UNION to mark union types.

• New method visitUnion added to visitor interface javax.lang.model.type.TypeVisitor. Utility visitor implementations updated accordingly.

• In the package javax.lang.model.type, MirroredTypesException retrofitted to be the superclass of MirroredTypeException.

• New utility visitors for release 7 in package javax.lang.model.util:

  • AbstractAnnotationValueVisitor7

  • AbstractElementVisitor7

  • AbstractTypeVisitor7

  • ElementKindVisitor7

  • ElementScanner7

  • SimpleAnnotationValueVisitor7

  • SimpleElementVisitor7

  • SimpleTypeVisitor7

  • TypeKindVisitor7

• The visitors ElementKindVisitor6, ElementScanner6, and SimpleElementVisitor6, are updated to account for new element kind RESOURCE_VARIABLE.

• The visitor AbstractTypeVisitor6 is updated to account for the possibility of visiting a UnionType.

• Definition of documentation comment added to javadoc of javax.lang.model.util.Elements.getDocComment.