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

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

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

@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 является повторяемым интерфейсом с собственным интерфейсом содержащей аннотации. Повторение аннотаций, которые сами являются контейнерами, при наличии аннотации базового повторяемого интерфейса — нежелательно.