パッケージjavax.lang.model.util

パッケージjavax.lang.model.util
プログラム要素と型の処理を支援するユーティリティです。

特定の実装で特に指定されないかぎり、このパッケージのメソッドが返すコレクションは、呼出し側からは変更不可能であり、並行アクセスに対しては安全ではないと想定するようにしてください。

特に指定されないかぎり、このパッケージのメソッドはnull引数が渡されるとNullPointerExceptionをスローします。

APIのノート:

予想されるビジターの進化

Javaプログラミング言語が進化するにつれて、言語モデルのビジター・インタフェースも、このパッケージの具体的なビジターと同様に進化します。 JDK Nの「言語機能のプレビュー」には、プレビュー言語レベルのビジター・セットにAPI要素が追加されている場合があります。 このような新しい要素は、反射プレビューAPIとしてマークされます。 プレビュー機能をサポートするように仕様が更新された既存のメソッドは、プレビューとしてマークされません。

このノートの残りの部分では、モデルでのAPI変更の例と、言語機能をサポートするために追加できるビジターの2つの例を示します。 例では、言語モデルの要素部分への追加を使用しますが、タイプまたは注釈値のビジターへの更新は類似しています。 次の2つの異なるケースがあります:

  • プレビュー言語構成には、対応する新しいモデリング・インタフェースと、新しいElementKind定数などの新しい種類の定数があります
  • プレビュー言語構成は、新しいモデリング・インタフェース「のない」新しいkindの導入するだけをトリガーを構成
プレビュー言語機能が永続的なプラットフォーム機能に展開されるのではなく、取り下げられると、その機能に関連付けられたAPI要素が削除されることが予想されます。 次の例では、プレビュー機能が永続的な機能になると予想されるAPIの変更の概要を示します。

トップレベルの言語構成に対するビジター・サポートの追加

JDK Nの新しい言語機能、プレビュー機能1について考えてみます。 この機能には、モデル化するための最上位の要素インタフェースがあります: 
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...
 }
このような機能をモデル化するために、新しい要素の種類も導入されます: 
 //  Sample diff of ElementKind.java
 +    /**
 +     * A preview feature 1.
 +     * @since N
 +     */
 +     PREVIEW_FEATURE_1,
新しい構成に対応するために、defaultメソッドがElementVisitorに追加されます: 
//  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);
 +    }
ビジター・インタフェースでdefaultメソッドを指定した場合、プレビュー・ビジター・クラスは、このメソッドをオーバーライドし、ビジターのセマンティクスに適したアクションを実行する必要があります: 
//  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);
 +    }
プレビュー機能1がJDK (N+k)でプレビューを終了すると、言語レベル(N+k)のビジターのセットが追加されます。 機能で動作するメソッドは、プレビュー・ビジターから新しい言語レベルの(N+k)ビジターに移動されます。 各プレビュー・ビジターは、その直接スーパークラスを、対応する新しい(N+k)ビジターに変更します。

新しい種類の既存構成である言語構成に対するビジター・サポートの追加

JDK Nの新しい言語機能、プレビュー機能2について考えてみます。 この機能には、モデル化に必要な新しい最上位要素「のない」新しい要素kindがあります。 具体的には、プレビュー機能2が新しい種類の変数であると仮定します。この変更は、その機能が新しい種類の実行可能ファイルであったり、別の既存のトップレベル構成の新しい種類であったりした場合に似ています。 この場合、APIの変更はより制限されます: 
 //  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;
          };
      }
親切なビジターは新しいさまざまな要素のサポートを必要とします: 
// 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);
 +    }
次に、プレビュー要素の種類のビジターが 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);
 +    }
新しいインタフェースが導入された場合と同様に、プレビュー機能2がJDK (N+k)でプレビューを終了すると、言語レベル(N+k)のビジターのセットが追加されます。 親切なビジターで新機能を操作するメソッドは、プレビュー・ビジターから新しい言語レベルの(N+k)ビジターに移動されます。 各プレビュー・ビジターは、その直接スーパークラスを、対応する新しい(N+k)ビジターに変更します。
導入されたバージョン:
1.6
関連項目: