モジュール 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
関連項目: