モジュール java.base
パッケージ java.lang.reflect

インタフェースAnnotatedElement

既知のすべてのサブインタフェース:
AnnotatedArrayType, AnnotatedParameterizedType, AnnotatedType, AnnotatedTypeVariable, AnnotatedWildcardType, GenericDeclaration, TypeVariable<D>
既知のすべての実装クラス:
AccessibleObject, Class, Constructor, Executable, Field, Method, Module, Package, Parameter, RecordComponent
public interface AnnotatedElement
このVMで現在実行されているプログラムの注釈付きコンストラクトを表します。 コンストラクトは要素または型のどちらかです。 要素の注釈は宣言に置かれ、型の注釈は型名の特定の使用に置かれます。 「Java言語仕様」セクション9.7.4で定義されているように、要素の注釈は「宣言注釈」で、型の注釈は「タイプ注釈」です。 注釈が付けられる可能性があるエンティティは型であるため、AnnotatedTypeインタフェースおよびそのサブインタフェースのメソッドによって返される注釈は型注釈であることに注意してください。 AnnotatedType階層外のメソッドによって返される注釈は、宣言注釈です。

このインタフェースを使用すると、注釈をリフレクト的に呼び出すことができます。 このインタフェースのメソッドにより返されたすべての注釈は、不変に保たれ、直列化可能です。 このインタフェースのメソッドによって返される配列は、ほかの呼出し元に返された配列に影響を及ぼすことなく、呼出し元で変更できます。

getAnnotationsByType(Class)メソッドおよびgetDeclaredAnnotationsByType(Class)メソッドでは、1つの要素における同じ型の複数の注釈がサポートされます。 いずれかのメソッドの引数が繰返し可能な注釈型(JLS 9.6)の場合、メソッドはコンテナ注釈(JLS 9.7)(存在する場合)を"見回す"し、コンテナ内の注釈を返します。 コンテナ注釈は、引数の型の複数の注釈をラップするために、コンパイル時に生成できます。

メソッドによって返される注釈を正確に記述するために、次のように、直接存在する、間接的に存在する、存在するおよび関連付けられているという用語がこのインタフェース全体で使用されます。

  • 要素Eが RuntimeVisibleAnnotationsまたは RuntimeVisibleParameterAnnotationsまたは RuntimeVisibleTypeAnnotations属性を持ち、その属性に注釈Aが含まれている場合、AはEに直接存在する。
  • 要素EがRuntimeVisibleAnnotationsまたはRuntimeVisibleParameterAnnotationsまたはRuntimeVisibleTypeAnnotations属性を持ち、注釈Aの型が繰返し可能であり、その属性に、Aが含まれる値要素およびAの型の包含する注釈型である型を持つ、厳密に1つの注釈が含まれている場合、AはEに間接的に存在する。
  • 次のいずれかの場合、要素Eの注釈Aはpresentです:
    • AがEに直接存在する。または
    • Aの型の注釈がEに直接存在せず、Eがクラスであり、Aの型が継承可能であり、AがEのスーパークラスに存在する。
  • 次のいずれかの場合、注釈Aは要素Eに関連付けられている。
    • AがEに直接または間接的に存在する。または
    • Aの型の注釈がEに直接または間接的に存在せず、Eがクラスであり、Aの型が継承可能であり、AがEのスーパークラスに関連付けられている。

次の表は、このインタフェースにおけるさまざまなメソッドによって検査される注釈の存在の種類を要約したものです。

さまざまなAnnotatedElementメソッドによって検出される存在の種類の概要
メソッド 存在の種類
戻り型 シグネチャ 直接存在する 間接的に存在する あり 関連付けられている
T getAnnotation(Class<T>) X
Annotation[] getAnnotations() X
T[] getAnnotationsByType(Class<T>) X
T getDeclaredAnnotation(Class<T>) X
Annotation[] getDeclaredAnnotations() X
T[] getDeclaredAnnotationsByType(Class<T>) XX

get[Declared]AnnotationsByType(Class <T>)の呼び出しでは、要素Eに直接または間接的に存在する注釈の順序は、Eに間接的に存在する注釈が、コンテナ注釈の代わりに、コンテナ注釈の値要素に現れる順序でEに直接存在するかのように計算されます。

注釈型Tがもともと繰返し可能ではなく、後で繰返し可能に変更された場合は、いくつかの互換性に関する問題に注意してください。 Tの包含する注釈型はTCです。

  • Tの繰返し可能への変更は、Tの既存の使用およびTCの既存の使用とはソース互換およびバイナリ互換です。 つまり、ソース互換については、型Tまたは型TCの注釈を含むソース・コードは引き続きコンパイルされます。 バイナリ互換については、型Tまたは型TCの注釈を含む(または型Tまたは型TCのその他の種類の使用を含む)クラス・ファイルは、以前のバージョンにリンクされていた場合は変更されたバージョンのTにリンクされます。 (注釈型TCは、Tが正式に繰返し可能に変更されるまでは、代理の包含する注釈型として非公式に機能できます。 または、Tを繰返し可能にするときに、TCを新しい型として導入できます。)
  • 注釈型TCが要素に存在し、Tが繰返し可能に変更され、TCがその包含する注釈型である場合、次のようになります。
    • Tに対する変更は、get[Declared]Annotation(Class<T>)メソッド(TまたはTCの引数を指定して呼び出される)および get[Declared]Annotations()メソッドに関しては動作に互換性があります。これは、TCがTの包含する注釈型になってもメソッドの結果が変化しないためです。
    • Tに対する変更によって、Tの引数を指定して呼び出される get[Declared]AnnotationsByType(Class<T>)メソッドの結果が変化します。これは、これらのメソッドで、型TCの注釈がTのコンテナ注釈として認識されるようになり、型Tの注釈を公開するためにこれが調べられるためです。
  • 型Tの注釈が要素に存在し、Tを繰返し可能にして、型Tの注釈が要素にさらに追加された場合、次のようになります。
    • 型Tの注釈の追加は、ソース互換かつバイナリ互換です。
    • 型Tの注釈の追加によって、get[Declared]Annotation(Class<T>)メソッドおよび get[Declared]Annotations()メソッドの結果が変化します。これは、これらのメソッドで、型Tの1つの注釈が確認されるのではなく、要素におけるコンテナ注釈のみが確認されるようになったためです。
    • 型Tの注釈の追加によって、get[Declared]AnnotationsByType(Class<T>)メソッドの結果が変化します。これは、それらの結果によって型Tの追加の注釈が公開されるためですが、以前は型Tの単一の注釈のみが公開されていました。

このインタフェースのメソッドにより返された注釈が、このVMでアクセスできないクラスを参照しているClassの値を持つメンバーを(直接または間接に)含む場合、関連するクラスを返すメソッドを返された注釈で呼び出してクラスを読み取ろうとすると、TypeNotPresentExceptionがスローされます。

同様に、enum値のメンバーを読み取ろうとすると、注釈内のenum定数がenumクラスに存在しなくなった場合にEnumConstantNotPresentExceptionになります。

注釈型Tが@Repeatable注釈によって(メタ)注釈が付けられており、その注釈の値要素で型TCが指定されているが、TCではT[]の戻り型を持つvalue()メソッドが宣言されていない場合、型AnnotationFormatErrorの例外がスローされます。

最後に、互換性なく開発された定義を持つメンバーを読み取ろうとすると、AnnotationTypeMismatchExceptionまたはIncompleteAnnotationExceptionがスローされます。

導入されたバージョン:
1.5
関連項目:

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    <T extends Annotation>
    T
    getAnnotation(Class<T> annotationClass)
    存在する場合は、この要素の指定された型の注釈を返し、そうでない場合はnullを返します。
    Annotation[]
    getAnnotations()
    この要素に存在する注釈を返します。
    default <T extends Annotation>
    T[]
    getAnnotationsByType(Class<T> annotationClass)
    この要素に関連付けられている注釈を返します。
    default <T extends Annotation>
    T
    getDeclaredAnnotation(Class<T> annotationClass)
    直接存在する場合は、この要素の指定された型の注釈を返し、そうでない場合はnullを返します。
    Annotation[]
    getDeclaredAnnotations()
    この要素に直接存在する注釈を返します。
    default <T extends Annotation>
    T[]
    getDeclaredAnnotationsByType(Class<T> annotationClass)
    直接存在するか間接的に存在する場合は、この要素の指定された型の注釈を返します。
    default boolean
    isAnnotationPresent(Class<? extends Annotation> annotationClass)
    指定された型の注釈がこの要素に存在する場合はtrueを返し、そうでない場合はfalseを返します。

  • メソッドの詳細

    • isAnnotationPresent

      default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
      指定された型の注釈がこの要素に存在する場合はtrueを返し、そうでない場合はfalseを返します。 このメソッドは、主にマーカー注釈への簡易アクセスを目的に設計されています。

      このメソッドによって返されるtrue値は、getAnnotation(annotationClass) != nullと同等です。

      実装要件:
      デフォルトの実装では getAnnotation(annotationClass) != nullが返されます。
      パラメータ:
      annotationClass - 注釈型に対応するClassオブジェクト
      戻り値:
      指定された注釈型の注釈がこの要素に存在する場合はtrue、そうでない場合はfalse
      例外:
      NullPointerException - 指定された注釈クラスがnullの場合
      導入されたバージョン:
      1.5

    • getAnnotation

      <T extends Annotation> T getAnnotation(Class<T> annotationClass)
      存在する場合は、この要素の指定された型の注釈を返し、そうでない場合はnullを返します。
      型パラメータ:
      T - 照会し、存在する場合に返す注釈の型。
      パラメータ:
      annotationClass - 注釈型に対応するClassオブジェクト
      戻り値:
      存在する場合は、この要素の指定された注釈型の注釈。そうでない場合はnull
      例外:
      NullPointerException - 指定された注釈クラスがnullの場合
      導入されたバージョン:
      1.5

    • getAnnotations

      Annotation[] getAnnotations()
      この要素に存在する注釈を返します。 この要素に存在する注釈がない場合、戻り値は長さ0の配列です。 このメソッドの呼出し元は、返された配列を自由に変更することができ、これはほかの呼出し元に返された配列に影響を及ぼしません。
      戻り値:
      この要素に存在する注釈
      導入されたバージョン:
      1.5

    • getAnnotationsByType

      default <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass)
      この要素に関連付けられている注釈を返します。 この要素に関連付けられている注釈がない場合、戻り値は長さ0の配列です。 このメソッドとgetAnnotation(Class)の違いは、引数が「繰返し可能な注釈タイプ」 (JLS 9.6)であるかどうかをこのメソッドが検出し、その場合、"検索"がコンテナ注釈を使用してそのタイプの注釈を検索しようとすることです。 このメソッドの呼出し元は、返された配列を自由に変更することができ、これはほかの呼出し元に返された配列に影響を及ぼしません。
      実装要件:
      デフォルトの実装では最初に、引数として annotationClassを渡してgetDeclaredAnnotationsByType(Class)が呼び出されます。 返された配列の長さが0より大きい場合は、その配列が返されます。 返された配列の長さが0であり、このAnnotatedElementがクラスであり、引数の型が継承可能な注釈型であり、このAnnotatedElementのスーパークラスがnullでない場合、返される結果は、引数として annotationClassを指定してスーパークラスに対してgetAnnotationsByType(Class)を呼び出した結果です。 それ以外の場合、長さゼロの配列が返されます。
      型パラメータ:
      T - 照会し、存在する場合に返す注釈の型。
      パラメータ:
      annotationClass - 注釈型に対応するClassオブジェクト
      戻り値:
      この要素に関連付けられている場合は、この要素の指定された注釈型のすべての注釈。そうでない場合は長さ0の配列
      例外:
      NullPointerException - 指定された注釈クラスがnullの場合
      導入されたバージョン:
      1.8

    • getDeclaredAnnotation

      default <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass)
      直接存在する場合は、この要素の指定された型の注釈を返し、そうでない場合はnullを返します。 このメソッドは継承された注釈を無視します。 (この要素に直接存在する注釈がない場合は、nullを返します。)
      実装要件:
      デフォルトの実装では、最初にnullチェックが実行された後、getDeclaredAnnotations()の結果に対するループが実行されて、注釈型が引数の型に一致する最初の注釈が返されます。
      型パラメータ:
      T - 照会し、直接存在する場合に返す注釈の型。
      パラメータ:
      annotationClass - 注釈型に対応するClassオブジェクト
      戻り値:
      直接存在する場合は、この要素の指定された注釈型の注釈。そうでない場合はnull
      例外:
      NullPointerException - 指定された注釈クラスがnullの場合
      導入されたバージョン:
      1.8

    • getDeclaredAnnotationsByType

      default <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass)
      直接存在するか間接的に存在する場合は、この要素の指定された型の注釈を返します。 このメソッドは継承された注釈を無視します。 この要素に直接または間接的に存在する指定された注釈がない場合、戻り値は長さ0の配列です。 このメソッドとgetDeclaredAnnotation(Class)の違いは、引数が「繰返し可能な注釈タイプ」 (JLS 9.6)であるかどうかをこのメソッドが検出し、ある場合は"検索"がコンテナ注釈(存在する場合)を検出しようとする点です。 このメソッドの呼出し元は、返された配列を自由に変更することができ、これはほかの呼出し元に返された配列に影響を及ぼしません。
      実装要件:
      デフォルトの実装では、getDeclaredAnnotation(Class)を1回以上呼び出して、直接存在する注釈を探したり、その注釈型が繰返し可能である場合は、コンテナ注釈を探したりすることができます。 注釈型annotationClassの注釈が直接かつ間接的に存在することがわかった場合は、getDeclaredAnnotations()が呼び出され、返される配列内での要素の順序が決定されます。

      または、デフォルトの実装で、getDeclaredAnnotations()を1回呼び出し、返された配列を、直接存在する注釈と間接的に存在する注釈の両方について検査することもできます。 getDeclaredAnnotations()の呼び出しの結果は、getDeclaredAnnotation(Class)の呼び出しの結果と一致すると見なされます。

      型パラメータ:
      T - 照会し、直接または間接的に存在する場合に返す注釈の型。
      パラメータ:
      annotationClass - 注釈型に対応するClassオブジェクト
      戻り値:
      この要素に直接または間接的に存在する場合は、この要素の指定された注釈型のすべての注釈。そうでない場合は長さ0の配列
      例外:
      NullPointerException - 指定された注釈クラスがnullの場合
      導入されたバージョン:
      1.8

    • getDeclaredAnnotations

      Annotation[] getDeclaredAnnotations()
      この要素に直接存在する注釈を返します。 このメソッドは継承された注釈を無視します。 この要素に直接存在する注釈がない場合、戻り値は長さ0の配列です。 このメソッドの呼出し元は、返された配列を自由に変更することができ、これはほかの呼出し元に返された配列に影響を及ぼしません。
      戻り値:
      この要素に直接存在する注釈
      導入されたバージョン:
      1.5