# Package javax.lang.model.util

package javax.lang.model.util
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.

API Note:

  ## 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 `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.
Since:
  1.6
See Also:
  - JSR 269: Pluggable Annotation Processing API

- Related Packages
  Package
  Description
  javax.lang.model
  Types and hierarchies of packages comprising a Java language model, a reflective API that models the declarations and types of the Java programming language.
  javax.lang.model.element
  Interfaces used to model elements of the Java programming language.
  javax.lang.model.type
  Interfaces used to model Java programming language types.
- Class
  Description
  AbstractAnnotationValueVisitor14<R,P>
  A skeletal visitor for annotation values with default behavior appropriate for source version `RELEASE_14`.
  AbstractAnnotationValueVisitor6<R,P>
  A skeletal visitor for annotation values with default behavior appropriate for the `RELEASE_6` source version.
  AbstractAnnotationValueVisitor7<R,P>
  A skeletal visitor for annotation values with default behavior appropriate for the `RELEASE_7` source version.
  AbstractAnnotationValueVisitor8<R,P>
  A skeletal visitor for annotation values with default behavior appropriate for the `RELEASE_8` source version.
  AbstractAnnotationValueVisitor9<R,P>
  A skeletal visitor for annotation values with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
  AbstractAnnotationValueVisitorPreviewPREVIEW<R,P>
  Preview.
  A skeletal visitor for annotation values with default behavior appropriate for a preview source version.
  AbstractElementVisitor14<R,P>
  A skeletal visitor of program elements with default behavior appropriate for the `RELEASE_14` source version.
  AbstractElementVisitor6<R,P>
  A skeletal visitor of program elements with default behavior appropriate for the `RELEASE_6` source version.
  AbstractElementVisitor7<R,P>
  A skeletal visitor of program elements with default behavior appropriate for the `RELEASE_7` source version.
  AbstractElementVisitor8<R,P>
  A skeletal visitor of program elements with default behavior appropriate for the `RELEASE_8` source version.
  AbstractElementVisitor9<R,P>
  A skeletal visitor of program elements with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
  AbstractElementVisitorPreviewPREVIEW<R,P>
  Preview.
  A skeletal visitor of program elements with default behavior appropriate for a preview source version.
  AbstractTypeVisitor14<R,P>
  A skeletal visitor of types with default behavior appropriate for the `RELEASE_14` source version.
  AbstractTypeVisitor6<R,P>
  A skeletal visitor of types with default behavior appropriate for the `RELEASE_6` source version.
  AbstractTypeVisitor7<R,P>
  A skeletal visitor of types with default behavior appropriate for the `RELEASE_7` source version.
  AbstractTypeVisitor8<R,P>
  A skeletal visitor of types with default behavior appropriate for the `RELEASE_8` source version.
  AbstractTypeVisitor9<R,P>
  A skeletal visitor of types with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
  AbstractTypeVisitorPreviewPREVIEW<R,P>
  Preview.
  A skeletal visitor of types with default behavior appropriate for a preview source version.
  ElementFilter
  Filters for selecting just the elements of interest from a collection of elements.
  ElementKindVisitor14<R,P>
  A visitor of program elements based on their kind with default behavior appropriate for the `RELEASE_14` source version.
  ElementKindVisitor6<R,P>
  A visitor of program elements based on their kind with default behavior appropriate for the `RELEASE_6` source version.
  ElementKindVisitor7<R,P>
  A visitor of program elements based on their kind with default behavior appropriate for the `RELEASE_7` source version.
  ElementKindVisitor8<R,P>
  A visitor of program elements based on their kind with default behavior appropriate for the `RELEASE_8` source version.
  ElementKindVisitor9<R,P>
  A visitor of program elements based on their kind with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
  ElementKindVisitorPreviewPREVIEW<R,P>
  Preview.
  A visitor of program elements based on their kind with default behavior appropriate for a preview source version.
  Elements
  Utility methods for operating on program elements.
  Elements.DocCommentKind
  The kind of documentation comment.
  Elements.Origin
  The origin of an element or other language model item.
  ElementScanner14<R,P>
  A scanning visitor of program elements with default behavior appropriate for the `RELEASE_14` source version.
  ElementScanner6<R,P>
  A scanning visitor of program elements with default behavior appropriate for the `RELEASE_6` source version.
  ElementScanner7<R,P>
  A scanning visitor of program elements with default behavior appropriate for the `RELEASE_7` source version.
  ElementScanner8<R,P>
  A scanning visitor of program elements with default behavior appropriate for the `RELEASE_8` source version.
  ElementScanner9<R,P>
  A scanning visitor of program elements with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
  ElementScannerPreviewPREVIEW<R,P>
  Preview.
  A scanning visitor of program elements with default behavior appropriate for a preview source version.
  SimpleAnnotationValueVisitor14<R,P>
  A simple visitor for annotation values with default behavior appropriate for source version `RELEASE_14`.
  SimpleAnnotationValueVisitor6<R,P>
  A simple visitor for annotation values with default behavior appropriate for the `RELEASE_6` source version.
  SimpleAnnotationValueVisitor7<R,P>
  A simple visitor for annotation values with default behavior appropriate for the `RELEASE_7` source version.
  SimpleAnnotationValueVisitor8<R,P>
  A simple visitor for annotation values with default behavior appropriate for the `RELEASE_8` source version.
  SimpleAnnotationValueVisitor9<R,P>
  A simple visitor for annotation values with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
  SimpleAnnotationValueVisitorPreviewPREVIEW<R,P>
  Preview.
  A simple visitor for annotation values with default behavior appropriate for a preview source version.
  SimpleElementVisitor14<R,P>
  A simple visitor of program elements with default behavior appropriate for the `RELEASE_14` source version.
  SimpleElementVisitor6<R,P>
  A simple visitor of program elements with default behavior appropriate for the `RELEASE_6` source version.
  SimpleElementVisitor7<R,P>
  A simple visitor of program elements with default behavior appropriate for the `RELEASE_7` source version.
  SimpleElementVisitor8<R,P>
  A simple visitor of program elements with default behavior appropriate for the `RELEASE_8` source version.
  SimpleElementVisitor9<R,P>
  A simple visitor of program elements with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
  SimpleElementVisitorPreviewPREVIEW<R,P>
  Preview.
  A simple visitor of program elements with default behavior appropriate for a preview source version.
  SimpleTypeVisitor14<R,P>
  A simple visitor of types with default behavior appropriate for source version `RELEASE_14`.
  SimpleTypeVisitor6<R,P>
  A simple visitor of types with default behavior appropriate for the `RELEASE_6` source version.
  SimpleTypeVisitor7<R,P>
  A simple visitor of types with default behavior appropriate for the `RELEASE_7` source version.
  SimpleTypeVisitor8<R,P>
  A simple visitor of types with default behavior appropriate for the `RELEASE_8` source version.
  SimpleTypeVisitor9<R,P>
  A simple visitor of types with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
  SimpleTypeVisitorPreviewPREVIEW<R,P>
  Preview.
  A simple visitor of types with default behavior appropriate for a preview source version.
  TypeKindVisitor14<R,P>
  A visitor of types based on their kind with default behavior appropriate for source version `RELEASE_14`.
  TypeKindVisitor6<R,P>
  A visitor of types based on their kind with default behavior appropriate for the `RELEASE_6` source version.
  TypeKindVisitor7<R,P>
  A visitor of types based on their kind with default behavior appropriate for the `RELEASE_7` source version.
  TypeKindVisitor8<R,P>
  A visitor of types based on their kind with default behavior appropriate for the `RELEASE_8` source version.
  TypeKindVisitor9<R,P>
  A visitor of types based on their kind with default behavior appropriate for source versions `RELEASE_9` through `RELEASE_14`.
  TypeKindVisitorPreviewPREVIEW<R,P>
  Preview.
  A visitor of types based on their kind with default behavior appropriate for a preview source version.
  Types
  Utility methods for operating on types.