OpenJDK 1.23 · javax.lang.model.util · APIdia, the JavaDoc alternative

Utilities to assist in the processing of program elements and types.

Unless otherwise specified in a particular implementation, the collections returned by methods in this package should be expected to be unmodifiable by the caller and unsafe for concurrent access.

Unless otherwise specified, methods in this package will throw a NullPointerException if given a null argument.

Expected visitor evolution

As the Java programming language evolves, the visitor interfaces of the language model also evolve as do the concrete visitors in this package. A preview language feature in JDK N may have API elements added in the set of visitors for the preview language level. Such new elements are marked as reflective preview API. Any existing methods whose specification is updated to support the preview feature are not marked as preview.

The remainder of this note will show two examples of the API changes in the model and visitors that can be added to support a language feature. The examples will use additions to the elements portion of the language model, but the updates to visitors for types or annotation values would be analogous. Two distinct cases are:

the preview language construct has a corresponding new modeling interface and a concomitant new kind constant, such as a new javax.lang.model.element.ElementKind constant
the preview language construct only triggers the introduction of a new kind without a new modeling interface

If a preview language feature is withdrawn rather than evolving to a permanent platform feature, the API elements associated with the feature are expected to be removed. The examples below outline the API changes expected when a preview feature becomes a permanent feature.

Adding visitor support for a top-level language construct

Consider a new language feature, preview feature 1, in JDK N. This feature has a top-level element interface to model it:

package javax.lang.model.element;
/**
 * Represents a preview feature 1.
 *
 * @since N
 */
 public interface PreviewFeature1Element extends Element {
 // Methods to retrieve information specific to the preview feature...
 }

A new element kind would also be introduced to model such a feature:

 //  Sample diff of ElementKind.java
 +    /**
 +     * A preview feature 1.
 +     * @since N
 +     */
 +     PREVIEW_FEATURE_1,

A default method is added to ElementVisitor to accommodate the new construct:

//  Sample diff for ElementVisitor.java
 +    /**
 +     * Visits a preview feature 1.
 +     *
 +     * @implSpec The default implementation visits a {@code
 +     * PreviewFeature1Element} by calling {@code visitUnknown(e, p)}.
 +     *
 +     * @param e  the element to visit
 +     * @param p  a visitor-specified parameter
 +     * @return a visitor-specified result
 +     * @since N
 +     */
 +    default R visitPreviewFeature1(PreviewFeature1Element e, P p) {
 +        return visitUnknown(e, p);
 +    }

Given the default method on the visitor interface, the preview visitor classes need to override this method and take an action appropriate for the visitor's semantics:

//  Sample diff for AbstractElementVisitorPreview.java
//  Re-abstract visitPreviewFeature1.
 +    /**
 +     * {@inheritDoc ElementVisitor}
 +     *
 +     * @implSpec Visits a {@code PreviewFeature1Element} in a manner
 +     * defined by a subclass.
 +     *
 +     * @param e {@inheritDoc ElementVisitor}
 +     * @param p {@inheritDoc ElementVisitor}
 +     * @return a visitor-specified result
 +     * @since N
 +     */
 +    @Override
 +    public abstract R visitPreviewFeature1(PreviewFeature1Element e, P p);

//  Sample diff for ElementKindVisitorPreview.java
//  Take the default action for a preview feature 1.
 +
 +    /**
 +     * {@inheritDoc ElementVisitor}
 +     *
 +     * @implSpec This implementation calls {@code defaultAction}.
 +     *
 +     * @param e {@inheritDoc ElementVisitor}
 +     * @param p {@inheritDoc ElementVisitor}
 +     * @return  the result of {@code defaultAction}
 +     * @since N
 +     */
 +    @Override
 +    public R visitPreviewFeature1(PreviewFeature1Element e, P p) {
 +        return defaultAction(e, p);
 +    }

//  Sample diff for ElementScannerPreview.java
//  Scan the enclosed elements of a preview feature 1.
 +
 +    /**
 +     * {@inheritDoc ElementVisitor}
 +     *
 +     * @implSpec This implementation scans the enclosed elements.
 +     *
 +     * @param e {@inheritDoc ElementVisitor}
 +     * @param p {@inheritDoc ElementVisitor}
 +     * @return  {@inheritDoc ElementScanner6}
 +     * @since N
 +     */
 +    @Override
 +    public R visitPreviewFeature1(PreviewFeature1Element e, P p) {
 +        return scan(e.getEnclosedElements(), p);
 +    }

//  Sample diff for SimpleElementVisitorPreview.java
//  Take the default action for a preview feature 1.
 +    /**
 +     * {@inheritDoc ElementVisitor}
 +     *
 +     * @implSpec Visits a {@code PreviewFeature1Element} by calling
 +     * defaultAction.
 +     *
 +     * @param e {@inheritDoc ElementVisitor}
 +     * @param p {@inheritDoc ElementVisitor}
 +     * @return  {@inheritDoc ElementVisitor}
 +     * @since N
 +     */
 +    @Override
 +    public R visitPreviewFeature1(PreviewFeature1Element e, P p) {
 +        return defaultAction(e, p);
 +    }

When preview feature 1 exits preview in JDK (N+k), a set of visitors for language level (N+k) would be added. The methods operating over the feature would be moved from the preview visitors to the new language level (N+k) visitors. Each preview visitor would then have its direct superclass changed to the new corresponding (N+k) visitor.

Adding visitor support for a language construct that is a new kind of an existing construct

Consider a new language feature, preview feature 2, in JDK N. This feature has a new element kind without a new top-level element interface needed to model it. Concretely, assume a preview feature 2 is a new kind of variable; the changes would be analogous if the feature were a new kind of executable instead or new kind of another existing top-level construct. In that case, the API changes are more limited:

 //  Sample diff for ElementKind.java
 +    /**
 +     * A preview feature 2.
 +     * @since N
 +     */
 +     PREVIEW_FEATURE_2,
 ...
 // Update existing methods as needed
      public boolean isVariable() {
          return switch(this) {
          case ENUM_CONSTANT, FIELD, PARAMETER,
               LOCAL_VARIABLE, EXCEPTION_PARAMETER, RESOURCE_VARIABLE,
 -             BINDING_VARIABLE -> true;
 +             BINDING_VARIABLE, PREVIEW_FEATURE_2 -> true;
          default -> false;
          };
      }

The kind visitors need support for the new variety of element:

// Update visitVariable in ElementKindVisitor6:
       ...
       * @implSpec This implementation dispatches to the visit method for
       * the specific {@linkplain ElementKind kind} of variable, {@code
       * ENUM_CONSTANT}, {@code EXCEPTION_PARAMETER}, {@code FIELD},
 -     * {@code LOCAL_VARIABLE}, {@code PARAMETER}, or {@code RESOURCE_VARIABLE}.
 +     * {@code LOCAL_VARIABLE}, {@code PARAMETER}, {@code RESOURCE_VARIABLE},
 +     * or {@code PREVIEW_FEATURE_2}.
       *
       * @param e {@inheritDoc ElementVisitor}
       * @param p {@inheritDoc ElementVisitor}
       * @return  the result of the kind-specific visit method
       */
       @Override
       public R visitVariable(VariableElement e, P p) {
       ...
          case BINDING_VARIABLE:
              return visitVariableAsBindingVariable(e, p);

 +        case PREVIEW_FEATURE_2:
 +            return visitVariableAsPreviewFeature2(e, p);
 +
          default:
              throw new AssertionError("Bad kind " + k + " for VariableElement" + e);
       ...
 +    /**
 +     * Visits a {@code PREVIEW_FEATURE_2} variable element.
 +     *
 +     * @implSpec This implementation calls {@code visitUnknown}.
 +     *
 +     * @param e the element to visit
 +     * @param p a visitor-specified parameter
 +     * @return  the result of {@code visitUnknown}
 +     *
 +     * @since N
 +     */
 +    public R visitVariableAsPreviewFeature2(VariableElement e, P p) {
 +        return visitUnknown(e, p);
 +    }

The preview element kind visitor in turn overrides visitVariableAsPreviewFeature2:

// Sample diff for ElementKindVisitorPreview:
 +    /**
 +     * {@inheritDoc ElementKindVisitor6}
 +     *
 +     * @implSpec This implementation calls {@code defaultAction}.
 +     *
 +     * @param e {@inheritDoc ElementKindVisitor6}
 +     * @param p {@inheritDoc ElementKindVisitor6}
 +     * @return  the result of {@code defaultAction}
 +     *
 +     * @since N
 +     */
 +    @Override
 +    public R visitVariableAsPreviewFeature2(VariableElement e, P p) {
 +        return defaultAction(e, p);
 +    }

As in the case where a new interface is introduced, when preview feature 2 exits preview in JDK (N+k), a set of visitors for language level (N+k) would be added. The methods operating over the new feature in the kind visitors would be moved from the preview visitors to new language level (N+k) visitors. Each preview visitor would then have its direct superclass changed to the new corresponding (N+k) visitor.

Modifier and Type	Interface and Description
public interface	Elements Utility methods for operating on program elements.
public interface	Types Utility methods for operating on types.

Class Summary

Modifier and Type	Class and Description
public abstract class	AbstractAnnotationValueVisitor14< the return type of this visitor's methods R, the type of the additional parameter to this visitor's methods. P> A skeletal visitor for annotation values with default behavior appropriate for source version `RELEASE_14`.
public abstract class	AbstractAnnotationValueVisitor6< the return type of this visitor's methods R, the type of the additional parameter to this visitor's methods. P> A skeletal visitor for annotation values with default behavior appropriate for the `RELEASE_6` source version.
public abstract class	AbstractAnnotationValueVisitor7< the return type of this visitor's methods R, the type of the additional parameter to this visitor's methods. P> A skeletal visitor for annotation values with default behavior appropriate for the `RELEASE_7` source version.
public abstract class	AbstractAnnotationValueVisitor8< the return type of this visitor's methods R, the type of the additional parameter to this visitor's methods. P> A skeletal visitor for annotation values with default behavior appropriate for the `RELEASE_8` source version.
public abstract class	AbstractAnnotationValueVisitor9< the return type of this visitor's methods R, the type of the additional parameter to this visitor's methods. P> A skeletal visitor for annotation values with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
public abstract class	AbstractAnnotationValueVisitorPreview< the return type of this visitor's methods R, the type of the additional parameter to this visitor's methods. P> Preview Language Model preview API. A skeletal visitor for annotation values with default behavior appropriate for a preview source version.
public abstract class	AbstractElementVisitor14< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A skeletal visitor of program elements with default behavior appropriate for the `RELEASE_14` source version.
public abstract class	AbstractElementVisitor6< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A skeletal visitor of program elements with default behavior appropriate for the `RELEASE_6` source version.
public abstract class	AbstractElementVisitor7< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A skeletal visitor of program elements with default behavior appropriate for the `RELEASE_7` source version.
public abstract class	AbstractElementVisitor8< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A skeletal visitor of program elements with default behavior appropriate for the `RELEASE_8` source version.
public abstract class	AbstractElementVisitor9< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A skeletal visitor of program elements with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
public abstract class	AbstractElementVisitorPreview< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> Preview Language Model preview API. A skeletal visitor of program elements with default behavior appropriate for a preview source version.
public abstract class	AbstractTypeVisitor14< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A skeletal visitor of types with default behavior appropriate for the `RELEASE_14` source version.
public abstract class	AbstractTypeVisitor6< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A skeletal visitor of types with default behavior appropriate for the `RELEASE_6` source version.
public abstract class	AbstractTypeVisitor7< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A skeletal visitor of types with default behavior appropriate for the `RELEASE_7` source version.
public abstract class	AbstractTypeVisitor8< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A skeletal visitor of types with default behavior appropriate for the `RELEASE_8` source version.
public abstract class	AbstractTypeVisitor9< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A skeletal visitor of types with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
public abstract class	AbstractTypeVisitorPreview< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> Preview Language Model preview API. A skeletal visitor of types with default behavior appropriate for a preview source version.
public class	ElementFilter Filters for selecting just the elements of interest from a collection of elements.
public class	ElementKindVisitor14< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A visitor of program elements based on their kind with default behavior appropriate for the `RELEASE_14` source version.
public class	ElementKindVisitor6< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A visitor of program elements based on their kind with default behavior appropriate for the `RELEASE_6` source version.
public class	ElementKindVisitor7< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A visitor of program elements based on their kind with default behavior appropriate for the `RELEASE_7` source version.
public class	ElementKindVisitor8< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A visitor of program elements based on their kind with default behavior appropriate for the `RELEASE_8` source version.
public class	ElementKindVisitor9< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A visitor of program elements based on their kind with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
public class	ElementKindVisitorPreview< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> Preview Language Model preview API. A visitor of program elements based on their kind with default behavior appropriate for a preview source version.
public class	ElementScanner14< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A scanning visitor of program elements with default behavior appropriate for the `RELEASE_14` source version.
public class	ElementScanner6< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A scanning visitor of program elements with default behavior appropriate for the `RELEASE_6` source version.
public class	ElementScanner7< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A scanning visitor of program elements with default behavior appropriate for the `RELEASE_7` source version.
public class	ElementScanner8< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A scanning visitor of program elements with default behavior appropriate for the `RELEASE_8` source version.
public class	ElementScanner9< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A scanning visitor of program elements with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
public class	ElementScannerPreview< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> Preview Language Model preview API. A scanning visitor of program elements with default behavior appropriate for a preview source version.
public class	SimpleAnnotationValueVisitor14< the return type of this visitor's methods R, the type of the additional parameter to this visitor's methods. P> A simple visitor for annotation values with default behavior appropriate for source version `RELEASE_14`.
public class	SimpleAnnotationValueVisitor6< the return type of this visitor's methods R, the type of the additional parameter to this visitor's methods. P> A simple visitor for annotation values with default behavior appropriate for the `RELEASE_6` source version.
public class	SimpleAnnotationValueVisitor7< the return type of this visitor's methods R, the type of the additional parameter to this visitor's methods. P> A simple visitor for annotation values with default behavior appropriate for the `RELEASE_7` source version.
public class	SimpleAnnotationValueVisitor8< the return type of this visitor's methods R, the type of the additional parameter to this visitor's methods. P> A simple visitor for annotation values with default behavior appropriate for the `RELEASE_8` source version.
public class	SimpleAnnotationValueVisitor9< the return type of this visitor's methods R, the type of the additional parameter to this visitor's methods. P> A simple visitor for annotation values with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
public class	SimpleAnnotationValueVisitorPreview< the return type of this visitor's methods R, the type of the additional parameter to this visitor's methods. P> Preview Language Model preview API. A simple visitor for annotation values with default behavior appropriate for a preview source version.
public class	SimpleElementVisitor14< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A simple visitor of program elements with default behavior appropriate for the `RELEASE_14` source version.
public class	SimpleElementVisitor6< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A simple visitor of program elements with default behavior appropriate for the `RELEASE_6` source version.
public class	SimpleElementVisitor7< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A simple visitor of program elements with default behavior appropriate for the `RELEASE_7` source version.
public class	SimpleElementVisitor8< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A simple visitor of program elements with default behavior appropriate for the `RELEASE_8` source version.
public class	SimpleElementVisitor9< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A simple visitor of program elements with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
public class	SimpleElementVisitorPreview< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> Preview Language Model preview API. A simple visitor of program elements with default behavior appropriate for a preview source version.
public class	SimpleTypeVisitor14< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A simple visitor of types with default behavior appropriate for source version `RELEASE_14`.
public class	SimpleTypeVisitor6< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A simple visitor of types with default behavior appropriate for the `RELEASE_6` source version.
public class	SimpleTypeVisitor7< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A simple visitor of types with default behavior appropriate for the `RELEASE_7` source version.
public class	SimpleTypeVisitor8< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A simple visitor of types with default behavior appropriate for the `RELEASE_8` source version.
public class	SimpleTypeVisitor9< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A simple visitor of types with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
public class	SimpleTypeVisitorPreview< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> Preview Language Model preview API. A simple visitor of types with default behavior appropriate for a preview source version.
public class	TypeKindVisitor14< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A visitor of types based on their kind with default behavior appropriate for source version `RELEASE_14`.
public class	TypeKindVisitor6< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A visitor of types based on their kind with default behavior appropriate for the `RELEASE_6` source version.
public class	TypeKindVisitor7< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A visitor of types based on their kind with default behavior appropriate for the `RELEASE_7` source version.
public class	TypeKindVisitor8< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A visitor of types based on their kind with default behavior appropriate for the `RELEASE_8` source version.
public class	TypeKindVisitor9< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> A visitor of types based on their kind with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
public class	TypeKindVisitorPreview< the return type of this visitor's methods. Use `Void` for visitors that do not need to return results. R, the type of the additional parameter to this visitor's methods. Use `Void` for visitors that do not need an additional parameter. P> Preview Language Model preview API. A visitor of types based on their kind with default behavior appropriate for a preview source version.

Package javax.lang.model.util

Expected visitor evolution

Adding visitor support for a top-level language construct

Adding visitor support for a language construct that is a new kind of an existing construct

Interface Summary

Class Summary