Объявление интерфейса может содержать модификаторы интерфейсов.

Правила модификаторов аннотаций для объявления интерфейса описаны в §9.7.4 и §9.7.5.

Модификатор доступа public (§6.6) относится ко всем видам объявлений интерфейсов.

Модификаторы доступа protected и private относятся только к вложенным интерфейсам, объявления которых непосредственно заключены в объявлении класса (§8.5.1).

Модификатор static относится только к вложенным интерфейсам (§8.5.1, §9.5), а не к интерфейсам верхнего уровня (§7.6).

Ошибка времени компиляции возникает, если одно и то же ключевое слово используется более одного раза в качестве модификатора для объявления интерфейса или если в объявлении интерфейса используется более одного из модификаторов доступа public, protected и private (§6.6).

Если в объявлении интерфейса присутствует два или более (различных) модификатора интерфейса, то принято, хотя и не обязательно, что они располагаются в порядке, согласованном с представленным выше в продукции для МодификатораИнтерфейса.

Интерфейс является параметризованным, если он объявляет одну или несколько переменных типов (§4.4).

Эти переменные типа известны как параметры типа интерфейса. Раздел параметров типа следует за именем интерфейса и ограничен угловыми скобками.

Следующие правила из §8.1.2 и §4.4 приведены здесь для удобства:

Правила модификаторов аннотаций для объявления параметра типа описаны в §9.7.4 и §9.7.5.

В разделе параметров типа интерфейса переменная типа T непосредственно зависит от переменной типа S, если S является ограничением T, тогда как T зависит от S, если либо T непосредственно зависит от S, либо T непосредственно зависит от переменной типа U, которая зависит от S (используя это определение рекурсивно). Ошибка времени компиляции возникает, если переменная типа в разделе параметров типа интерфейса зависит от самой себя.

Область действия и перекрытие параметра типа интерфейса описаны в §6.3.

Ошибка времени компиляции возникает при ссылке на параметр типа параметризованного интерфейса I где-либо в объявлении static члена интерфейса I (§9.3, §9.4, §9.5).

Объявление параметризованного интерфейса определяет набор параметризованных типов (§4.5), по одному для каждой возможной параметризации раздела параметров типа аргументами типа. Все эти параметризованные типы совместно используют один и тот же интерфейс во время выполнения.

Если указан пункт extends, то объявляемый интерфейс расширяет каждый из других перечисленных интерфейсов и, следовательно, наследует типы членов, методы экземпляров и константы каждого из других перечисленных интерфейсов.

Эти другие перечисленные интерфейсы являются прямыми суперинтерфейсами объявляемого интерфейса.

Любой класс, который implements объявленный интерфейс, также считается реализующим все интерфейсы, которые этот интерфейс extends.

Для удобства приводится следующее производство из §8.1.5:

Каждый Тип интерфейса в пункте extends объявления интерфейса должен указывать на доступный тип интерфейса (§6.6), иначе происходит ошибка времени компиляции.

Если у Типа интерфейса есть аргументы типа, он должен обозначать правильно сформированный параметризованный тип (§4.5), и ни один из аргументов типа не может быть аргументом типа с подстановкой, иначе происходит ошибка времени компиляции.

Для объявления интерфейса (возможно, обобщенного) I<F₁,...,F_n> (n ≥ 0), прямыми суперинтерфейсами типа интерфейса I<F₁,...,F_n> являются типы, указанные в пункте extends объявления I, если такой пункт присутствует.

Для обобщенного объявления интерфейса I<F₁,...,F_n> (n > 0), прямыми суперинтерфейсами параметризованного типа интерфейса I<T₁,...,T_n>, где T_i (1 ≤ i ≤ n) – тип, являются все типы J<U₁ θ,...,U_k θ>, где J<U₁,...,U_k> является прямым суперинтерфейсом I<F₁,...,F_n>, а θ – подстановка [F1:=T1,...,Fn:=Tn].

Отношение суперинтерфейса является транзитивным замыканием отношения прямого суперинтерфейса. Интерфейс K является суперинтерфейсом интерфейса I, если выполняется одно из следующих условий:

Интерфейс I считается подинтерфейсом интерфейса K, когда K является суперинтерфейсом I.

В то время как каждый класс является расширением класса Object, не существует единого интерфейса, расширением которого являются все интерфейсы.

Интерфейс I непосредственно зависит от типа T, если T упоминается в пункте extends I либо как суперинтерфейс, либо как квалификатор в полном полном имени суперинтерфейса.

Интерфейс I зависит от ссылочного типа T, если выполняется любое из следующих условий:

Ошибка компиляции, если интерфейс зависит от самого себя.

Если при загрузке интерфейсов обнаруживаются циклически объявленные интерфейсы, то генерируется ClassCircularityError (§12.2.1).

Тело интерфейса может объявлять члены интерфейса, т. е. поля (§9.3), методы (§9.4), классы (§9.5) и интерфейсы (§9.5).

Область действия объявления члена m, объявленного в или унаследованного типом интерфейса I, указана в §6.3.

Если у двух методов интерфейса (независимо от того, объявлены ли они в одном интерфейсе, или оба унаследованы интерфейсом, или один объявлен, а другой унаследован) одинаковое имя, но разные подписи, которые не являются эквивалентными для переопределения (§8.4.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 и имеет точку с запятой для своего тела.

Ошибка компиляции, если тело static метода пытается получить доступ к текущему объекту с помощью ключевого слова this или ключевого слова super.

Правила для return операторов в теле метода указаны в §14.17.

Если метод объявлен с типом возвращаемого значения (§8.4.5), то возникает ошибка компиляции, если тело метода может завершиться нормально (§14.1).

Тело объявления типа аннотации может содержать объявления методов, каждый из которых определяет элемент типа аннотации. Тип аннотации не имеет элементов, кроме тех, которые определены явно объявленными им методами.

В силу производства AnnotationTypeElementDeclaration, в объявлении метода типа аннотации не могут быть формальные параметры, параметры типа или throws. Следующее производство из §4.3 показано здесь для удобства:

Благодаря производству AnnotationTypeElementModifier, объявление метода в объявлении типа аннотации не может быть default или static. Таким образом, тип аннотации не может объявлять такое же разнообразие методов, как обычный тип интерфейса. Обратите внимание, что тип аннотации всё ещё может унаследовать метод по умолчанию от своего неявного суперинтерфейса, java.lang.annotation.Annotation, хотя такого метода по умолчанию не существует в Java SE 11.

По соглашению, единственными AnnotationTypeElementModifierами, которые должны присутствовать на элементе типа аннотации, являются аннотации.

Тип возвращаемого значения метода, объявленного в типе аннотации, должен быть одним из следующих, иначе произойдёт ошибка времени компиляции:

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

Объявление метода, возвращающего массив, разрешает поместить пару скобок, обозначающих тип массива, после пустого списка формальных параметров. Этот синтаксис поддерживается для совместимости со старыми версиями Java. Крайне рекомендуется не использовать этот синтаксис в новом коде.

Если какой-либо метод, объявленный в типе аннотации, имеет сигнатуру, эквивалентную сигнатуре любого public или protected метода, объявленного в классе Object или в интерфейсе java.lang.annotation.Annotation, то это ошибка времени компиляции.

Если объявление типа аннотации T содержит элемент типа T, непосредственно или косвенно, то это ошибка времени компиляции.

@interface SelfRef { SelfRef value(); }

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

Тип аннотации без элементов называется типом аннотации-метки.

Тип аннотации с одним элементом называется типом аннотации с единственным элементом.

По соглашению, имя единственного элемента в типе аннотации с единственным элементом — 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 type is not designed
 * to be used directly to annotate program elements, but to
 * define elements of other annotation types.
 */
@interface Name {
    String first();
    String last();
}

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

Элемент типа аннотации может иметь значение по умолчанию, указанное после списка параметров элемента (пустого) с ключевым словом default и Значением элемента (§9.7.1).

Если тип элемента не совместим (§9.7) со значением по умолчанию, это является ошибкой компиляции.

Значения по умолчанию не компилируются в аннотации, а применяются динамически в момент чтения аннотаций. Таким образом, изменение значения по умолчанию влияет на аннотации даже в классах, которые были скомпилированы до внесения изменения (предполагая, что эти аннотации не содержат явного значения для элемента по умолчанию).

@interface RequestForEnhancementDefault {
    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]";
}

Обычная аннотация указывает имя типа аннотации и, необязательно, список пар имя-значение элемента, разделённых запятыми. Каждая пара содержит значение элемента, связанное с элементом типа аннотации (§9.6.1).

Обратите внимание, что знак «@» (@) является отдельным токеном (§3.11). Разрешается вставлять пробелы между ним и TypeName, но это не рекомендуется в стиле оформления.

TypeName указывает тип аннотации, соответствующий аннотации. Говорят, что аннотация «относится к» этому типу.

TypeName должен называть доступный тип аннотации (§6.6), иначе происходит ошибка во время компиляции.

Идентификатор в паре «имя-значение элемента» должен быть простым именем одного из элементов (то есть методов) типа аннотации; в противном случае происходит ошибка во время компиляции.

Тип возвращаемого значения этого метода определяет тип элемента пары «имя-значение элемента».

Если тип элемента является типом массива, то для указания значения элемента пары «имя-значение элемента» необязательно использовать фигурные скобки. Если значение элемента не является ИнициализаторМассиваЗначенийЭлементов, то сопоставляется значение массива, единственный элемент которого — это значение элемента. Если значение элемента является ИнициализаторМассиваЗначенийЭлементов, то сопоставляется значение массива, представленное ИнициализаторМассиваЗначенийЭлементов.

Возникает ошибка во время компиляции, если тип элемента не совместим со значением элемента. Тип элемента T совместим со значением элемента V тогда и только тогда, когда выполняется одно из следующих условий:

Обратите внимание, что если T не является типом массива или типом аннотации, значение элемента должно быть условным выражением (§15.25). Использование условного выражения вместо более общей конструкции, типа выражения, является синтаксическим приемом, чтобы предотвратить выражения присваивания в качестве значений элементов. Поскольку выражение присваивания не является константным выражением, оно не может быть совместимым значением элемента для примитивного или String-типизированного элемента.

Формально, нельзя говорить о ЗначениеЭлемента как о строгом FP-выражении (§15.4), потому что это может быть аннотация или литерал класса. Тем не менее, можно неформально говорить о ЗначениеЭлемента как о строгом FP-выражении, когда это либо константное выражение, или массив константных выражений, или аннотация, значения элементов которой (рекурсивно) являются константными выражениями; ведь каждое константное выражение является строго FP-выражением.

В обычной аннотации для каждого элемента соответствующего типа аннотации должна быть пара «имя-значение элемента», за исключением элементов с заданными значениями по умолчанию; в противном случае происходит ошибка во время компиляции.

В обычной аннотации могут, но не обязаны, содержаться пары «имя-значение элемента» для элементов с заданными значениями по умолчанию.

В соответствии с обычной практикой (хотя это и не обязательно), пары «имя-значение элемента» в аннотации представляются в том же порядке, что и соответствующие элементы в объявлении типа аннотации.

Аннотация на объявлении типа аннотации называется мета-аннотацией.

Аннотация типа T может появиться как мета-аннотация в объявлении типа T само по себе. Более того, цикличности в транзитивном замыкании отношения «аннотирует» разрешены.

Например, разрешается аннотировать объявление типа аннотации S мета-аннотацией типа T, а объявление T — мета-аннотацией типа S. В предопределённых типах аннотаций содержатся несколько таких циклов.

@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)

Допускается использование аннотаций с одним элементом для типов аннотаций с несколькими элементами, при условии, что один элемент имеет имя 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 { ... }

Ошибка компиляции, если в контексте объявления или контексте типа появляются несколько аннотаций одного типа T, если только T не является повторяемой (§9.6.3) и T и содержащий тип аннотации T применима в контексте объявления или контексте типа (§9.6.4.1).

Принято, но не обязательно, чтобы несколько аннотаций одного типа появлялись непрерывно.

Если контекст объявления или контекст типа имеет несколько аннотаций повторяемого типа аннотации T, то считается, что контекст не имеет явно объявленных аннотаций типа T и имеет одну неявно объявленную аннотацию содержащего типа аннотации T.

Неявно объявленная аннотация называется контейнерной аннотацией, а несколько аннотаций типа T, появившиеся в контексте, называются базовыми аннотациями. Элементы элемента (типа массива) value контейнерной аннотации — это все базовые аннотации в порядке слева направо, в котором они появились в контексте.

Ошибка компиляции, если в контексте объявления или контексте типа есть несколько аннотаций повторяемого типа аннотации T и любые аннотации содержащего типа аннотации T.

Другими словами, невозможно повторять аннотации, где аннотация того же типа, что и их контейнер, также присутствует. Это запрещает запутанный код, например:

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

Если бы этот код был допустимым, потребовались бы несколько уровней вложенности: сначала аннотации типа Foo содержались бы неявно объявленной контейнерной аннотацией типа FooContainer, а затем эта аннотация и явно объявленная аннотация типа FooContainer содержались бы в ещё одной неявно объявленной аннотации. Такая сложность нежелательна по мнению разработчиков языка программирования Java. Другой подход, рассматривающий аннотации типа Foo как если бы они появились наряду с @Foo(2) в явной @FooContainer аннотации, также нежелателен, поскольку это может изменить то, как рефлексивные программы интерпретируют аннотацию @FooContainer.

Ошибка компиляции, если в контексте объявления или контексте типа есть одна аннотация повторяемого типа аннотации T и несколько аннотаций содержащего типа аннотации T.

Это правило разработано для разрешения следующего кода:

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

При наличии только одной аннотации повторяемого типа аннотации Foo, не объявляется никакой контейнерной аннотации, даже если FooContainer — это содержащий тип аннотации для Foo. Однако повторение аннотации типа FooContainer, как в:

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

запрещено, даже если FooContainer является повторяемой с собственным содержащим типом аннотации. Нежелательно повторять аннотации, которые сами являются контейнерами, когда присутствует аннотация базового повторяемого типа.