第9章 インタフェース

インタフェース宣言には、インタフェース修飾子を含めることができます。

インタフェース宣言の注釈修飾子に関する規則は、§9.7.4および§9.7.5で指定されています。

アクセス修飾子public (§6.6)は、ローカル・インタフェース(§14.3)ではなく、トップ・レベル・インタフェース(§7.6)およびメンバー・インタフェース(§8.5、§9.5)にのみ関連します。

アクセス修飾子protectedおよびprivateは、メンバー・インタフェースにのみ関係します。

修飾子staticは、メンバー・インタフェースおよびローカル・インタフェースにのみ関係します。

同じキーワードがインタフェース宣言の修飾子として複数回出現する場合、またはインタフェース宣言にアクセス修飾子public、protectedおよびprivateが複数存在する場合は、コンパイル時にエラーが発生します。

インタフェース宣言に複数の修飾子sealedおよびnon-sealedがある場合、コンパイル時にエラーが発生します。

2つ以上の(個別)インタフェース修飾子がインタフェース宣言に表示される場合、InterfaceModifierの本番で前述したものと一致する順序で表示されることは、必須ではありませんが慣例です。

インタフェース宣言で1つ以上の型変数が宣言されている場合、インタフェースは汎用です(§4.4)。

これらの型変数は、インタフェースの型パラメータと呼ばれます。 タイプ・パラメータ・セクションは、インタフェース名の後に山カッコで区切られます。

ここでは、便宜上、§8.1.2および §4.4からの次のプロダクションを示します。

型パラメータ宣言の注釈修飾子に関する規則は、§9.7.4および§9.7.5に記載されています。

インタフェースの型パラメータ・セクションで、型変数Tは型変数Sに直接依存します(SがTの境界である場合)。一方、TはSに依存します(TがSまたはTに直接依存している場合)。この定義は、Sに依存する型変数Uに直接依存します(この定義を再帰的に使用します)。 インタフェース型パラメータ・セクションの型変数がそれ自体に依存している場合は、コンパイル時エラーです。

インタフェースの型パラメータのスコープとシャドウは、§6.3および §6.4.1で指定されています。

静的コンテキストまたはネストされたクラスまたはインタフェースからのインタフェースの型パラメータへの参照は、§6.5.5.1で指定されているように制限されます。

汎用インタフェース宣言は、パラメータ化された型のセット(§4.5)を定義し、型引数による型パラメータ・セクションの可能なパラメータ化ごとに1つずつ定義します。 これらのパラメータ化された型はすべて、実行時に同じインタフェースを共有します。

extends句が指定されている場合、宣言されるインタフェースは、指定された各インタフェース・タイプを拡張するため、これらの各インタフェース・タイプのメンバー・クラス、メンバー・インタフェース、インスタンス・メソッドおよびstaticフィールドを継承します。

指定されたインタフェース・タイプは、宣言されるインタフェースのダイレクト・スーパーインタフェース・タイプです。

宣言されたインタフェースをimplementsするクラスも、このインタフェースextendsのすべてのインタフェースを実装するとみなされます。

ここでは、便宜上、§8.1.5の次の本番環境を示します。

インタフェース宣言のextends句の各InterfaceTypeは、アクセス可能なインタフェース(§6.6)に名前を付ける必要があります。そうしないと、コンパイル時にエラーが発生します。

いずれかのInterfaceTypeがsealed (§9.1.1.4)のインタフェースに名前を付け、宣言されているインタフェースが指定されたインタフェース(§9.1.4)の直接サブインタフェースとして許可されていない場合、コンパイル時にエラーが発生します。

InterfaceTypeに型引数がある場合、整形式のパラメータ化された型(§4.5)を示す必要があり、どの型引数もワイルドカード型引数にできないか、コンパイル時にエラーが発生します。

1つ目のインタフェースは、2つ目のインタフェースの直接スーパーインタフェース・タイプの1つによって名前が付けられている場合、別のインタフェースの直接スーパーインタフェースです。

スーパーインタフェース関係は、直接スーパーインタフェース関係の推移的クローズです。 次のいずれかが当てはまる場合、インタフェースIはインタフェースKのスーパーインタフェースです。

インタフェースは、その直接スーパーインタフェースの直接サブインタフェースであり、各スーパーインタフェースのサブインタフェースであると言われています。

すべてのクラスはObjectクラスの拡張ですが、すべてのインタフェースが拡張である単一のインタフェースはありません。

インタフェースIは、クラスまたはインタフェースAにAがIのextends句で、スーパーインタフェースとして、またはスーパーインタフェース名の完全修飾形式の修飾子として記述されている場合、直接依存します。

次のいずれかに該当する場合、インタフェースIはクラスまたはインタフェースAに依存します。

インタフェースがそれ自体に依存している場合は、コンパイル時エラーです。

循環宣言されたインタフェースが実行時に検出され、インタフェースがロードされると、ClassCircularityErrorがスローされます(§12.2.1)。

標準インタフェース宣言のオプションのpermits句は、宣言されるインタフェースの直接サブクラスおよび直接サブインタフェース(§9.1.1.4)として意図されるすべてのクラスおよびインタフェースを指定します。

インタフェース宣言にpermits句があり、sealed修飾子がない場合、コンパイル時にエラーが発生します。

すべてのTypeNameは、アクセス可能なクラスまたはインタフェースに名前を付ける必要があります(§6.6)。そうしないと、コンパイル時にエラーが発生します。

permits句で同じクラスまたはインタフェースが複数回指定されている場合、コンパイル時にエラーが発生します。 これは、クラスまたはインタフェースに異なる方法で名前が付けられている場合でも当てはまります。

package p;

sealed interface I permits C, D, p.C {}  // error

non-sealed class C implements I {}
non-sealed class D implements I {}

sealedインタフェースIが名前付きモジュール(§7.3)に関連付けられている場合は、Iの宣言のpermits句で指定されたすべてのクラスまたはインタフェースをIと同じモジュールに関連付ける必要があります。そうしないと、コンパイル時にエラーが発生します。

sealedインタフェースIが名前のないモジュール(§7.7.5)に関連付けられている場合、Iの宣言のpermits句で指定されているすべてのクラスまたはインタフェースは、Iと同じパッケージに属している必要があります。そうしないと、コンパイル時にエラーが発生します。

sealedインタフェースとそのダイレクト・サブクラスおよびダイレクト・サブインタフェースは、それぞれpermits、implementsおよびextends句で、循環方式で相互を参照する必要があります。 したがって、モジュラ・コードベースでは、異なるモジュールのクラスとインタフェースが循環方式で相互に参照できないため、同じモジュール内に配置する必要があります。 シール済インタフェース階層は常に1つのメンテナンス・ドメイン内で宣言する必要があり、同じ開発者または開発者のグループが階層の維持を担当するため、いずれの場合もコロケーションが望ましいです。 名前付きモジュールは通常、モジュラーコードベースの保守ドメインを表します。

sealedインタフェースIの宣言にpermits句がある場合、Iの許可された直接サブクラスおよびサブインタフェースは、permits句で指定されたクラスおよびインタフェースです。

permits句で指定されるすべての許可される直接サブクラスおよびサブインタフェースは、I (§8.1.5)の直接サブクラスまたはI (§9.1.3)の直接サブインタフェースである必要があります。そうでない場合、コンパイル時にエラーが発生します。

sealedインタフェースIの宣言にpermits句がない場合、Iで許可される直接サブクラスおよびサブインタフェースは、正規名(§6.7)を持ち、直接スーパーインタフェースにIが含まれるI (§7.3)と同じコンパイル・ユニットで宣言されるクラスおよびインタフェースです。

つまり、許可される直接サブクラスおよびサブインタフェースは、直接スーパーインタフェースとして Iを指定する同じコンパイルユニット内のクラスおよびインタフェースと見なされます。 正規名の要件は、ローカル・クラス、ローカル・インタフェースまたは匿名クラスが考慮されないことを意味します。

sealedインタフェースIの宣言にpermits句がなく、Iに許可されている直接サブクラスまたはサブインタフェースがない場合、コンパイル時にエラーが発生します。

インタフェース本体には、インタフェースのメンバー、つまりフィールド(§9.3)、メソッド(§9.4)、クラスおよびインタフェース(§9.5)の宣言を含めることができます。

インタフェースIで宣言または継承されたメンバーmの宣言のスコープは、§6.3で指定されます。

インタフェースのフィールド宣言内のすべての宣言子には変数イニシャライザが必要です。そうしないと、コンパイル時にエラーが発生します。

イニシャライザは定数式である必要はありません(§15.29)。

インタフェース・フィールドのイニシャライザが同じインタフェースのイニシャライザ(§3.5)の右側に宣言が出現する同じフィールドの単純名または別のフィールドを使用する場合、コンパイル時にエラーが発生します。

インタフェース・フィールドのイニシャライザは、§15.8.3、§15.11.2および§15.12.3で指定されているキーワードthisまたはキーワードsuperを使用して、現在のオブジェクトを参照することはできません。

実行時に、イニシャライザが評価され、インタフェースの初期化時にフィールド割当てが1回のみ実行されます(§12.4.2)。

定数変数であるインタフェース・フィールド(§4.12.4)は、他のインタフェース・フィールドより前に初期化されることに注意してください。 これは、クラス内の定数変数であるstaticフィールドにも適用されます(§8.3.2)。 このようなフィールドは、逸脱したプログラムであっても、デフォルトの初期値(§4.12.5)を持つことは決してありません。

interface Test {
    float f = j;
    int   j = 1;
    int   k = k + 1;
}

インタフェースIは、その直接スーパーインタフェース・タイプから継承し、すべてのabstractおよびデフォルト・メソッドmに対して、次のすべてに該当します。

メソッドは、シグネチャごとにオーバーライドされます。 たとえば、インタフェースが同じ名前を持つ2つのpublicメソッド(§9.4.2)を宣言し、サブインタフェースがそのいずれかをオーバーライドする場合、サブインタフェースはもう一方のメソッドを継承します。

前述の3つ目の句により、サブインタフェースが、そのスーパーインタフェースの別のサブインタフェースによってすでにオーバーライドされたメソッドを再度継承することが防止されます。 たとえば、次のプログラムでは、

interface Top {
    default String name() { return "unnamed"; }
}
interface Left extends Top {
    default String name() { return getClass().getName(); }
}
interface Right extends Top {}

interface Bottom extends Left, Right {}

RightはTopからname()を継承しますが、BottomはRightではなくLeftからname()を継承します。 これは、Leftのname()がTopのname()の宣言をオーバーライドするためです。

インタフェースは、そのスーパーインタフェースからprivateまたはstaticメソッドを継承しません。

インタフェースIがprivateまたはstaticメソッドmを宣言し、mのシグネチャがスーパーインタフェース型Iのpublicインスタンス・メソッドm'のサブシグネチャで、m'がIのコードからアクセス可能である場合、コンパイル時にエラーが発生します。

基本的に、インタフェースのstaticメソッドは、スーパーインタフェース型のインスタンス・メソッドを非表示にできません。 これは、クラス内のstaticメソッドがスーパークラス型またはスーパーインタフェース型のインスタンス・メソッドを非表示にできない§8.4.8.2のルールと似ています。 §8.4.8.2のルールは「staticメソッドを宣言または継承する」クラスを語るのに対し、前述のルールは「staticメソッドを宣言する」インタフェースのみを語ることに注意してください。これは、インタフェースがstaticメソッドを継承できないためです。 また、§8.4.8.2のルールでは、スーパークラス/スーパーインタフェースでインスタンス・メソッドとstaticメソッドの両方を非表示にできますが、前述のルールでは、スーパーインタフェース・タイプのpublicインスタンス・メソッドのみが考慮されます。

同じ行で、インタフェース内のprivateメソッドは、スーパーインタフェース型のインスタンス・メソッド(publicまたはprivate)をオーバーライドできません。 これは、§8.4.8.1および§8.4.8.3のルールに似ています。このルールでは、クラス内のprivateメソッドがスーパークラス型またはスーパーインタフェース型のインスタンス・メソッドをオーバーライドできません。これは、§8.4.8.1ではオーバーライドされたメソッドが非privateである必要があり、§8.4.8.3ではオーバーライドされたメソッドが、オーバーライドされたメソッドと少なくとも同じ数のアクセスを提供する必要があるためです。 要約すると、インタフェース内のpublicメソッドのみをオーバーライドでき、サブインタフェースまたは実装クラスのpublicメソッドによってのみオーバーライドできます。

インタフェースの2つのメソッド(同じインタフェースで宣言されたメソッド、またはインタフェースによって継承されたメソッド、または宣言されたメソッドと継承されたメソッドのどちらか)が同じ名前を持つが、オーバーライド等価ではない異なるシグネチャ(§8.4.2)がある場合、メソッド名はオーバーロードされたと見なされます。

この事実は難しくなく、それ自体ではコンパイル時にエラーが発生することはありません。 戻り型間、または2つのメソッドのthrows句間で、同じ名前を持つが、オーバーライド等価ではない異なるシグネチャの間には、必要な関係はありません。

interface PointInterface {
    void move(int dx, int dy);
}
interface RealPointInterface extends PointInterface {
    void move(float dx, float dy);
    void move(double dx, double dy);
}

デフォルト・メソッドにはブロック本文があります。 このコード・ブロックは、クラスがインタフェースを実装するが、メソッドの独自の実装を提供しない場合に、メソッドの実装を提供します。

privateまたはstaticインタフェース・メソッドには、メソッドの実装を提供するブロック本体もあります。

インタフェース・メソッド宣言がabstract (明示的または暗黙的)であり、その本体のブロックがある場合、コンパイル時にエラーが発生します。

インタフェース・メソッド宣言がdefault、privateまたはstaticで、本体にセミコロンがある場合、コンパイル時にエラーが発生します。

メソッド本体内のreturn文のルールは、§14.17で指定します。

メソッドが戻り型(§8.4.5)を持つように宣言されている場合、メソッドの本文が正常に完了できるとコンパイル時エラーが発生します(§14.1)。

アノテーション・インタフェース宣言の本体には、それぞれがアノテーション・インタフェースの要素を定義するメソッド宣言を含めることができます。 アノテーション・インタフェースには、アノテーション・インタフェース宣言で明示的に宣言されたメソッドによって定義された要素以外の要素はありません。

ここでは、便宜上、§4.3の次の本番環境を示します。

前述の文法により、注釈インタフェース宣言のメソッド宣言に仮パラメータ、型パラメータまたはthrows句を含めることはできず、private、defaultまたはstaticにすることもできません。 したがって、注釈インタフェースは、通常のインタフェースと同じ種類のメソッドを持つことはできません。 Java SE 26では、注釈インタフェースが暗黙的なスーパーインタフェースjava.lang.annotation.Annotationからデフォルト・メソッドを継承することは可能ですが、このようなデフォルト・メソッドは存在しません。

規則によって、注釈インタフェース要素の宣言に存在する必要がある修飾子は、注釈のみです。

注釈インタフェースの本体で宣言されたメソッドの戻り型は、次のいずれかである必要があります。そうしないと、コンパイル時にエラーが発生します。

@interface Verboten {
    String[][] value();
}

配列を返すメソッドの宣言では、配列型を示す大カッコのペアを空の仮パラメータ・リストの後に配置できます。 この構文は、Javaプログラミング言語の初期バージョンとの互換性のためにサポートされています。 この構文は新しいコードでは使用しないことを強くお薦めします。

注釈インタフェースで宣言されたメソッドに、クラスObjectまたはインタフェースjava.lang.annotation.Annotationで宣言されたpublicまたはprotectedメソッドのシグネチャとオーバーライド等価(§8.4.2)のシグネチャがある場合、コンパイル時にエラーが発生します。

注釈インタフェースTの宣言にT型の要素が直接的または間接的に含まれている場合は、コンパイル時にエラーが発生します。

@interface SelfRef { SelfRef value(); }

@interface Ping { Pong value(); }
@interface Pong { Ping value(); }

要素のない注釈インタフェースは、マーカー注釈インタフェースと呼ばれます。

1つの要素を持つ注釈インタフェースは、単一要素注釈インタフェースと呼ばれます。

慣例上、単一要素注釈インタフェースの唯一の要素の名前はvalueです。 この規則の言語サポートは、単一要素注釈(§9.7.3)によって提供されます。

/**
 * Describes the "request-for-enhancement" (RFE)
 * that led to the presence of the annotated API element.
 */
@interface RequestForEnhancement {
    int    id();        // Unique ID number associated with RFE
    String synopsis();  // Synopsis of RFE
    String engineer();  // Name of engineer who implemented RFE
    String date();      // Date RFE was implemented
}

/**
 * An annotation with this type indicates that the
 * specification of the annotated API element is
 * preliminary and subject to change.
 */
@interface Preliminary {}

/**
 * Associates a copyright notice with the annotated API element.
 */
@interface Copyright {
    String value();
}

/**
 * Associates a list of endorsers with the annotated class.
 */
@interface Endorsers {
    String[] value();
}

interface Formatter {}

// Designates a formatter to pretty-print the annotated class
@interface PrettyPrinter {
    Class<? extends Formatter> value();
}

/**
 * Indicates the author of the annotated program element.
 */
@interface Author {
    Name value();
}
/**
 * A person's name.  This annotation interface is not
 * designed to be used directly to annotate program elements,
 * but to define elements of other annotation interfaces.
 */
@interface Name {
    String first();
    String last();
}

@interface Quality {
    enum Level { BAD, INDIFFERENT, GOOD }
    Level value();
}

注釈インタフェース要素には、キーワードdefaultおよび要素を定義するメソッド宣言に値をアタッチすることによって指定されるデフォルト値を指定できます。

ここでは、便宜上、§9.7.1からの次のプロダクションを示します。

デフォルト値を持つように指定されている注釈インタフェース要素は、デフォルト・メソッド(§9.4)ではないことに注意してください。 注釈インタフェースの宣言では、デフォルト・メソッドを宣言できません(§9.6.1)。

要素の型が、指定されたデフォルト値と同等でない場合(§9.7)、コンパイル時にエラーが発生します。

デフォルト値は注釈にコンパイルされず、注釈の読取り時に動的に適用されます。 したがって、デフォルト値を変更すると、変更が(これらの注釈にデフォルト要素の明示的な値がないと仮定)に行われる前にコンパイルされたクラスであっても注釈に影響します。

@interface RequestForEnhancement {
    int    id();       // No default - must be specified in
                       // each annotation
    String synopsis(); // No default - must be specified in
                       // each annotation
    String engineer()  default "[unassigned]";
    String date()      default "[unimplemented]";
}

注釈インタフェースAが反復可能になるのは、その宣言が@Repeatable注釈(§9.6.4.8)で注釈付けされている(メタ)場合で、value要素がAの注釈インタフェースを含むことを示す場合です。

次のすべてに当てはまる場合、注釈インタフェースACはAの注釈インタフェースを含むです。

注釈インタフェースAが、value要素がAの包含注釈インタフェースではない型を示す@Repeatable注釈で(メタ)注釈付けされている場合、コンパイル時にエラーが発生します。

import java.lang.annotation.Repeatable;

@Repeatable(FooContainer.class)
@interface Foo {}

@interface FooContainer { Object[] value(); }

@Repeatableアノテーションを繰り返すことはできないため、繰返し可能なアノテーション・インタフェースで指定できるアノテーション・インタフェースは1つのみです。

複数の包含アノテーション・インタフェースを指定できるようにすると、繰返し可能なアノテーション・インタフェースの複数のアノテーションがコンテナ・アノテーション(§9.7.5)で論理的に置換される場合に、コンパイル時に望ましくない選択が生じます。

注釈インタフェースは、最大1つの注釈インタフェースの包含注釈インタフェースにできます。

これは、注釈インタフェースAの宣言でACの包含注釈インタフェースが指定されている場合、ACのvalue()メソッドにはA (特にA[])を含む戻り型があるという要件によって暗示されます。

注釈インタフェースは、それ自体を含む注釈インタフェースとして指定できません。

これは、包含アノテーション・インタフェースのvalue()メソッドの要件によって示されます。 具体的には、注釈インタフェースAがそれ自身を(@Repeatableを介して)包含注釈インタフェースとして指定した場合、Aのvalue()メソッドの戻り型はA[]である必要がありますが、注釈インタフェースがその要素(§9.6.1)でそれ自体を参照できないため、コンパイル時にエラーが発生します。 より一般的には、2つの注釈インタフェースは、循環注釈インタフェース宣言が不正であるため、包含注釈インタフェースとして指定できません。

注釈インタフェースACは、一部の注釈インタフェースAの包含注釈インタフェースであり、独自の包含注釈インタフェースSCを持つ場合もあります。 つまり、包含アノテーション・インタフェース自体が繰返し可能なアノテーション・インタフェースである場合があります。

import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Target;

@Target(ElementType.TYPE)
@Repeatable(FooContainer.class)
@interface Foo {}

@Target(ElementType.ANNOTATION_TYPE)
@interface FooContainer {
    Foo[] value();
}

@Foo @Foo
@interface Anno {}

@Foo @Foo
interface Intf {}

import java.lang.annotation.Repeatable;

// Foo: Repeatable annotation interface
@Repeatable(FooContainer.class)
@interface Foo { int value(); }

// FooContainer: Containing annotation interface of Foo
// Also a repeatable annotation interface itself
@Repeatable(FooContainerContainer.class)
@interface FooContainer { Foo[] value(); }

// FooContainerContainer: Containing annotation interface
// of FooContainer
@interface FooContainerContainer { FooContainer[] value(); }

@FooContainer({@Foo(1)}) @FooContainer({@Foo(2)})
class Test {}

Java SE Platform APIには、いくつかの注釈インタフェースが事前定義されています。 事前定義された注釈インタフェースの中には、Javaプログラミング言語で特別なセマンティクスを持つものがあり、この項で説明するように、Javaコンパイラの部分で特別な動作を必要とします。 この項では、Java SE Platform APIドキュメント(§1.4)を参照する事前定義済注釈インタフェースの完全な仕様は提供していません。

public boolean equals(Foo that) { ... }

public boolean equals(Object that) { ... }

class Foo     { @Override public int hashCode() {..} }
interface Bar { @Override int hashCode(); }

interface Quux { @Override Object clone(); }

class Beep { @Override protected Object clone() {..} }

record Roo(int x) {
    @Override
    public int x() {
        return Math.abs(x);
    }
}

public static <T> boolean
  addAll(Collection<? super T> c, T... elements)

通常の注釈は、注釈インタフェースの名前と、オプションでカンマ区切りの要素と値のペアのリストを指定します。 各ペアには、注釈インタフェースの要素(§9.6.1)に関連付けられた要素値が含まれます。

アットマーク(@)はそれ自体に対するトークンであることに注意してください(§3.11)。 TypeNameとの間に空白を入れることは可能ですが、スタイルの問題としてはお薦めしません。

TypeNameでは、注釈に対応する注釈インタフェースを指定します。 この注釈は、そのインタフェースに「of」と表示されます。

TypeNameは、アクセス可能な注釈インタフェースに名前を付ける必要があります(§6.6)。そうしないと、コンパイル時にエラーが発生します。

要素と値のペアの識別子は、注釈インタフェースのいずれかの要素(つまり、メソッド)の単純な名前である必要があります。そうしないと、コンパイル時にエラーが発生します。

このメソッドの戻り型は、要素と値のペアの要素型を定義します。

要素型が配列型である場合、要素と値のペアの要素値を指定するのに中カッコを使用する必要はありません。 エレメント値がElementValueArrayInitializerでない場合は、唯一のエレメントがエレメント値である配列値がエレメントに関連付けられます。 エレメント値がElementValueArrayInitializerの場合、ElementValueArrayInitializerで表される配列値はそのエレメントに関連付けられます。

要素型が要素値とともに補正されない場合は、コンパイル時にエラーが発生します。 要素型Tは、次のいずれかが当てはまる場合にのみ、要素値vと相乗的になります。

Tが配列型または注釈インタフェースでない場合、要素値はConditionalExpression (§15.25)である必要があります。 「式」のようなより一般的な生成ではなく、「ConditionalExpression」を使用することは、代入式を要素値として防止するための構文上のトリックです。 代入式は定数式ではないため、プリミティブ要素またはString型要素の代数要素値にはできません。

通常の注釈には、対応する注釈インタフェースのすべての要素について要素と値のペアを含める必要があります。ただし、デフォルト値を持つ要素を除きます。そうしないと、コンパイル時にエラーが発生します。

標準注釈には、デフォルト値が指定された要素の要素と値のペアを含めることができます(必須ではありません)。

アノテーション内の要素と値のペアは、アノテーション・インタフェース宣言内の対応する要素と同じ順序で提示されることは、必須ではありませんが慣例です。

注釈インタフェース宣言の注釈は、メタ注釈と呼ばれます。

インタフェースAの注釈は、インタフェースA自体の宣言にメタ注釈として表示される場合があります。 より一般的には、「注釈付け」関係の推移閉包の循環性が許可されます。

たとえば、注釈インタフェースSの宣言にインタフェースTのメタ注釈を付け、T自身の宣言にインタフェースSのメタ注釈を付けて注釈を付けることは有効です。 事前定義された注釈インタフェース(§9.6.4)には、このような循環がいくつか含まれています。

@RequestForEnhancement(
    id       = 2868724,
    synopsis = "Provide time-travel functionality",
    engineer = "Mr. Peabody",
    date     = "4/1/2004"
)
public static void travelThroughTime(Date destination) { ... }

@RequestForEnhancement(
    id       = 4561414,
    synopsis = "Balance the federal budget"
)
public static void balanceFederalBudget() {
    throw new UnsupportedOperationException("Not implemented");
}

マーカー注釈は、マーカー注釈インタフェース(§9.6.1)で使用するために設計された短縮形です。

これは次の標準注釈の簡略表現です。

@TypeName()

すべての要素にデフォルト値(§9.6.2)があるかぎり、要素を含む注釈インタフェースにマーカー注釈を使用することは有効です。

@Preliminary public class TimeTravel { ... }

単一要素注釈は、単一要素注釈インタフェース(§9.6.1)で使用するために設計された短縮形です。

これは次の標準注釈の簡略表現です。

@TypeName(value = ElementValue)

1つの要素がvalueという名前で、他のすべての要素にデフォルト値(§9.6.2)が指定されているかぎり、複数の要素を持つ注釈インタフェースに単一要素注釈を使用することは有効です。

@Copyright("2002 Yoyodyne Propulsion Systems, Inc.")
public class OscillationOverthruster { ... }

@Endorsers({"Children", "Unscrupulous dentists"})
public class Lollipop { ... }

@Endorsers("Epicurus")
public class Pleasure { ... }

class GorgeousFormatter implements Formatter { ... }

@PrettyPrinter(GorgeousFormatter.class)
public class Petunia { ... }

// Illegal; String is not a subtype of Formatter
@PrettyPrinter(String.class)
public class Begonia { ... }

@Author(@Name(first = "Joe", last = "Hacker"))
public class BitTwiddle { ... }

@Quality(Quality.Level.GOOD)
public class Karma { ... }

宣言注釈は、宣言に適用され、その宣言によって表される宣言コンテキスト(§9.6.4.1)に注釈インタフェースが適用される注釈、またはクラス、インタフェースまたは型パラメータ宣言に適用され、その注釈インタフェースが型コンテキスト(§4.11)に適用可能な注釈です。

型注釈は、型(または型の任意の部分)に適用され、その注釈インタフェースが型コンテキストに適用可能な注釈です。

@Foo int f;

@C int @A [] @B [] f;

@C int f;
@C int[] f;
@C int[][] f;

これは、特に必要ではなく、他のすべての修飾子の前に宣言の注釈を記述するためであり、適用する型の直前に注釈を入力することです。

注釈は、プログラム内で宣言または型、あるいはその両方に柔軟に適用される構文上のロケーションに表示できます。 これは、宣言されたエンティティの型の直前に修飾子がある6つの宣言コンテキストのいずれかで発生する可能性があります。

Javaプログラミング言語の文法では、これらの場所にある注釈を宣言の修飾子(§8.3)として明確に扱いますが、これは単なる構文の問題です。 注釈が宣言または宣言されたエンティティの型に適用されるかどうか、つまり、注釈が宣言注釈か型注釈かは、注釈のインタフェースの適用性によって異なります。

前述の2番目と3番目のケースでは、注釈に最も近い型は次のように決定されます。

インタフェースAの注釈が構文的に次の修飾子である場合、コンパイル時にエラーが発生します。

これらの11個の句のうち6個は、この項で前述した6つの構文の場所を特徴付けるため、「...または型コンテキスト内」に言及しています。注釈は宣言または型に妥当に適用できます。 さらに、クラスおよびインタフェース宣言と型パラメータ宣言の2つの11個の句のうち、クラス、インタフェースまたは型パラメータの宣言にインタフェースがメタ注釈付き(したがって、型コンテキストに適用可能)の注釈を適用できると便利な場合があるため、「...」または型コンテキストに言及します。

次の両方に当てはまる場合、型注釈はadmissibleです。

2番目の句の背後にある直観は、Outer.thisがOuterで囲まれたネストされたクラスで正当な場合、実行時に一部のオブジェクトのタイプを表すため、Outerに注釈を付けることができることです。 一方、Outer.thisが正当でない場合- 出現するクラスには実行時にOuterの囲みインスタンスがないため- Outerは、完全修飾型名のパッケージ名のコンポーネントと同様に、論理的に単なる名前であるため、注釈付けされない可能性があります。

@Target(ElementType.TYPE_USE)
@interface Foo {}

class A {
    static class B {}
}

@Foo A.B x;  // Illegal

@Target(ElementType.TYPE_USE)
@interface Foo {}

class Test {
    static class C {
        class D {}
    }

    @Foo C.D x;  // Legal
}

インタフェースAの注釈が型コンテキスト内の型の最も外側のレベルに適用され、Aが型コンテキストまたは同じ構文の場所を占める宣言コンテキスト(存在する場合)に適用されない場合は、コンパイル時にエラーが発生します。

インタフェース Aの注釈が、型コンテキスト内の型の一部(つまり、もっとも外側のレベルではない)に適用され、型コンテキストで Aが適用されない場合は、コンパイル時にエラーが発生します。

インタフェースAの注釈が型コンテキスト内の型(または型の任意の部分)に適用され、型コンテキストでAが適用可能であるが、注釈が許可されていない場合、コンパイル時にエラーが発生します。

たとえば、注釈インタフェースTAが、@Target(ElementType.TYPE_USE)のみでメタ注釈付けされているとします。 @TA java.lang.Objectおよびjava.@TA lang.Objectという用語は、@TAがもっとも近い単純名がパッケージ名として分類されるため、無効です。 一方、java.lang.@TA Objectは有効です。

使用できない用語に"どこでも"が含まれています。 パッケージ名の注釈付け禁止は、class ... extends @TA java.lang.Object {...}などの型コンテキストのみである場所、および宣言コンテキストと型コンテキストの両方である場所(@TA java.lang.Object f;など)に広く適用されます。 (パッケージ、クラス、インタフェースおよび型パラメータ宣言では単純名のみが導入されるため、パッケージ名に注釈を付けることができる唯一の宣言コンテキストである場所はありません。)

TAがさらに@Target(ElementType.FIELD)でメタ注釈付けされている場合、@TA java.lang.Objectという用語は、フィールド宣言@TA java.lang.Object f;などの宣言コンテキストと型コンテキストの両方の場所で有効です。 ここでは、@TAはfの宣言(java.lang.Object型ではなく)に適用されるとみなされます。これは、TAがフィールド宣言コンテキストに適用可能であるためです。

Aが繰返し可能(§9.6.3)であり、AとAの包含アノテーション・インタフェースの両方が宣言コンテキストまたは型コンテキスト(§9.6.4.1)に適用可能でないかぎり、同じインタフェースAの複数のアノテーションが宣言コンテキストまたは型コンテキスト(§9.6.3)に存在する場合、コンパイル時にエラーが発生します。

同じインターフェイスの複数の注釈が連続して表示されるのは慣例ですが、必須ではありません。

宣言コンテキストまたは型コンテキストに繰返し可能な注釈インタフェースAの複数の注釈がある場合、そのコンテキストにインタフェースAの明示的に宣言された注釈と、Aの包含注釈インタフェースの暗黙的に宣言された注釈が1つないかのようになります。

暗黙的に宣言された注釈はコンテナ注釈と呼ばれ、コンテキストに出現したインタフェースAの複数の注釈はベース注釈と呼ばれます。 コンテナ注釈の(配列型)value要素の要素はすべて、コンテキストに表示された左から右の順番のベース注釈です。

宣言コンテキストまたは型コンテキストで、繰返し可能な注釈インタフェースAの複数の注釈と、Aの包含する注釈インタフェースの注釈がある場合、コンパイル時にエラーが発生します。

つまり、コンテナと同じインタフェースのアノテーションも表示されるアノテーションを繰り返すことはできません。 これにより、次のような洗練されないコードは禁止されています。

@Foo(0) @Foo(1) @FooContainer({@Foo(2)})
class A {}

このコードが正当な場合、複数のレベルの包含が必要になります。最初に、インタフェースFooの基本注釈がインタフェースFooContainerの暗黙的に宣言されたコンテナ注釈によって含まれるため、その注釈とインタフェースFooContainerの明示的に宣言された注釈は、さらに別の暗黙的に宣言された注釈に含まれます。 Javaプログラミング言語の設計者は、この複雑さは望ましくないと判断しています。 インタフェースFooの基本アノテーションを、明示的な@FooContainerアノテーションで@Foo(2)と並んで発生したかのように処理するもう1つの方法は、リフレクティブ・プログラムが@FooContainerアノテーションを解釈する方法を変更する可能性があるため、望ましくありません。

宣言コンテキストまたは型コンテキストで、繰返し可能な注釈インタフェースAの注釈が1つあり、Aの包含注釈インタフェースの注釈が複数ある場合は、コンパイル時にエラーが発生します。

このルールは、次のコードを許可するために設計されています。

@Foo(1) @FooContainer({@Foo(2)})
class A {}

繰返し可能な注釈インタフェースFooのベース注釈が1つのみの場合、FooContainerがFooの包含注釈インタフェースであっても、コンテナ注釈は暗黙的に宣言されません。 ただし、次のように、インタフェースFooContainerの注釈を繰り返します。

@Foo(1) @FooContainer({@Foo(2)}) @FooContainer({@Foo(3)})
class A {}

FooContainerがそれ自身の包含アノテーション・インタフェースで繰返し可能である場合でも、禁止されています。 基礎となる反復可能なインタフェースのアノテーションが存在する場合は、それ自体がコンテナであるアノテーションを繰り返すのは難しくなります。