Глава 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 21.

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

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

@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.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]";
}

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