Глава 9. Интерфейсы

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

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

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

Модификаторы доступа protected и private относятся только к вложенным интерфейсам.

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

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

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

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

Интерфейс является обобщенным, если объявление интерфейса объявляет одну или несколько переменных типа (§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 и §6.4.1.

Ссылки на параметр типа интерфейса из статического контекста или вложенного класса или интерфейса ограничены, как указано в §6.5.5.1.

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

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

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

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

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

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

Ошибка компиляции возникает, если любой Тип интерфейса называет интерфейс, который sealed (§9.1.1.4), и объявляемый интерфейс не является разрешенным непосредственным подинтерфейсом названного интерфейса (§9.1.4).

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

Один интерфейс является непосредственным суперинтерфейсом другого интерфейса, если первый интерфейс указан в одном из непосредственных типов суперинтерфейса второго интерфейса.

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

Интерфейс называется непосредственным подинтерфейсом своего непосредственного суперинтерфейса и подинтерфейсом каждого из своих суперинтерфейсов.

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

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

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

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

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

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

Если в объявлении интерфейса есть фраза permits, но отсутствует модификатор sealed, то это ошибка компиляции.

Каждый ИмяТипа должен указывать на доступный класс или интерфейс (§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), то каждый класс или интерфейс, указанный во фразе permits объявления I, должен быть ассоциирован с тем же модулем, что и I, иначе произойдёт ошибка компиляции.

Если интерфейс sealed I ассоциирован с безымянным модулем (§7.7.5), то каждый класс или интерфейс, указанный во фразе permits объявления I, должен принадлежать к тому же пакету, что и I, иначе произойдёт ошибка компиляции.

Интерфейс sealed и его прямые подклассы и прямые подинтерфейсы должны ссылаться друг на друга циклическим способом, соответственно, во фразах permits, implements и extends. Поэтому в модульной кодовой базе они должны быть размещены в одном модуле, так как классы и интерфейсы в разных модулях не могут ссылаться друг на друга циклическим образом. Совместное размещение желательно в любом случае, потому что иерархия интерфейса sealed всегда должна быть объявлена в одном домене поддержки, за которым отвечает один и тот же разработчик или группа разработчиков. Именованный модуль обычно представляет собой домен поддержки в модульной кодовой базе.

Если объявление интерфейса sealed I содержит фразу permits, то разрешённые прямые подклассы и подинтерфейсы интерфейса I представляют собой классы и интерфейсы, указанные во фразе permits.

Каждый разрешённый прямой подкласс и подинтерфейс, указанный во фразе permits, должен быть прямым подклассом интерфейса I (§8.1.5) или прямым подинтерфейсом I (§9.1.3), иначе произойдёт ошибка компиляции.

Если объявление интерфейса sealed I не содержит фразу permits, то разрешённые прямые подклассы и подинтерфейсы интерфейса I — это те классы и интерфейсы, которые объявлены в той же единице компиляции, что и I (§7.3), имеют каноническое имя (§6.7) и для которых прямые суперинтерфейсы включают интерфейс I.

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

Если объявление интерфейса sealed I не содержит фразу permits и у I нет разрешённых прямых подклассов или подинтерфейсов, то это ошибка компиляции.

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

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

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

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

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

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

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

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

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

Если любой метод, объявленный в интерфейсе аннотации, имеет подпись, эквивалентную с точки зрения переопределения (§8.4.2), методу 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 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.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]";
}

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

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

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

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

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

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

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

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

Обратите внимание, что если T не является типом массива или интерфейсом аннотации, значение элемента должно быть УсловноеВыражение (§15.25). Использование УсловноеВыражение вместо более общей конструкции, например, Выражение, — это синтаксический трюк, призванный предотвратить использование выражений присваивания в качестве значений элементов. Поскольку выражение присваивания не является константным выражением, оно не может быть совместимым значением элемента для элемента примитивного типа или 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)

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

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

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

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

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

Если в контексте объявления или контексте типа есть несколько аннотаций повторяющегося интерфейса аннотаций A, и есть какие-либо аннотации содержащего интерфейса аннотации A, это ошибка времени компиляции.

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

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

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

Если в контексте объявления или контексте типа есть одна аннотация повторяющегося интерфейса аннотаций A и несколько аннотаций содержащего интерфейса аннотации A, это ошибка времени компиляции.

Это правило разработано для того, чтобы позволить следующий код:

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

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

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

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