Интерфейс AnnotatedConstruct

Все известные подинтерфейсы:: Тип массива, Тип объявленный, Элемент, Тип ошибки, Исполняемый элемент, Исполняемый тип, Пересечение типов, Тип "нет", Тип null, Элемент пакета, Параметризуемый, Примитивный тип, Имя с квалификатором, Тип ссылки, Элемент типа, Зеркало типа, Элемент параметра типа, Переменная типа, Объединение типов, Элемент переменной, Тип дикого символа

public interface AnnotatedConstruct

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

В определениях ниже аннотация A имеет тип аннотации AT. Если AT — это повторяющийся тип аннотации, то тип содержащей аннотации — ATC.

Аннотация A непосредственно присутствует в конструкции C, если выполняется одно из условий:

A явно или неявно объявлена как применяющаяся к представлению кода источника C.
Как правило, если ровно одна аннотация типа AT появляется в исходном коде представления C, то A явно применяется к C. Если присутствует несколько аннотаций типа AT на C, то если AT — это повторяющийся тип аннотации, аннотация типа ATC неявно объявлена на C.
Представление A появляется в исполняемом выводе для C, например, в атрибутах RuntimeVisibleAnnotations или RuntimeVisibleParameterAnnotations файла класса.

Аннотация A присутствует в конструкции C, если выполняется одно из условий:

A непосредственно присутствует в C.
Ни одна аннотация типа AT не присутствует непосредственно в C, и C — это класс, и AT наследуется, и A присутствует в суперклассе C.

Аннотация A косвенно присутствует в конструкции C, если выполняются оба условия:

AT — это повторяющийся тип аннотации с типом содержащей аннотации ATC.
Аннотация типа ATC непосредственно присутствует в C, и A — это аннотация, включенная в результат вызова метода value непосредственно присутствующей аннотации типа ATC.

Аннотация A связана с конструкцией C, если выполняется одно из условий:

A непосредственно или косвенно присутствует в C.
Ни одна аннотация типа AT не присутствует непосредственно или косвенно в C, и C — класс, и AT наследуется, и A связана с суперклассом C.

С момента:: 1.8

Методы

Модификатор и тип	Метод и описание
`<A extends Annotation> A`	`getAnnotation(Class<A> annotationType)` Возвращает аннотацию данной конструкции указанного типа, если такая аннотация присутствует, в противном случае `null`.
`List<? extends AnnotationMirror>`	`getAnnotationMirrors()` Возвращает аннотации, которые непосредственно присутствуют в этой конструкции.
`<A extends Annotation> A[]`	`getAnnotationsByType(Class<A> annotationType)` Возвращает аннотации, которые связаны с данной конструкцией.

Методы

getAnnotationMirrors

List<? extends AnnotationMirror> getAnnotationMirrors()

Возвращает аннотации, которые непосредственно присутствуют в этой конструкции.

Возвращает:: аннотации, непосредственно присутствующие в этой конструкции; пустой список, если таковых нет

getAnnotation

<A extends Annotation> A getAnnotation(Class<A> annotationType)

Возвращает аннотацию данной конструкции указанного типа, если такая аннотация присутствует, в противном случае null.

Возвращаемая данным методом аннотация может содержать элемент, значение которого имеет тип Class. Это значение нельзя вернуть напрямую: необходимая информация для поиска и загрузки класса (например, загрузчик классов) недоступна, а класс может вообще не загружаться. Попытка прочитать объект Class, вызвав соответствующий метод на возвращаемой аннотации, приведёт к MirroredTypeException, из которого можно извлечь соответствующий TypeMirror. Аналогично, попытка прочитать элемент со значением Class[] приведёт к MirroredTypesException.

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

Параметры типа:: A - тип аннотации
Параметры:: annotationType - объект Class соответствующий типу аннотации
Возвращает:: аннотация данной конструкции для указанного типа аннотации, если она присутствует, в противном случае null
См. также:: getAnnotationMirrors(), AnnotatedElement.getAnnotation(java.lang.Class<T>), EnumConstantNotPresentException, AnnotationTypeMismatchException, IncompleteAnnotationException, MirroredTypeException, MirroredTypesException

getAnnotationsByType

<A extends Annotation> A[] getAnnotationsByType(Class<A> annotationType)

Возвращает аннотации, которые связаны с этой конструкцией. Если связанных аннотаций нет, возвращается массив длины 0. Порядок аннотаций, которые непосредственно или косвенно присутствуют в конструкции C, вычисляется так, как будто косвенно присутствующие аннотации на C непосредственно присутствуют на C вместо их контейнерной аннотации, в порядке их появления в элементе значения контейнерной аннотации. Разница между этим методом и getAnnotation(Class) заключается в том, что этот метод определяет, является ли его аргумент повторяющимся типом аннотации, и если да, пытается найти одну или несколько аннотаций этого типа, «просматривая» контейнерную аннотацию.

Возвращаемые данным методом аннотации могут содержать элемент, значение которого имеет тип Class. Это значение нельзя вернуть напрямую: необходимая информация для поиска и загрузки класса (например, загрузчик классов) недоступна, а класс может вообще не загружаться. Попытка прочитать объект Class, вызвав соответствующий метод на возвращаемой аннотации, приведёт к MirroredTypeException, из которого можно извлечь соответствующий TypeMirror. Аналогично, попытка прочитать элемент со значением Class[] приведёт к MirroredTypesException.

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

Параметры типа:: A - тип аннотации
Параметры:: annotationType - объект Class соответствующий типу аннотации
Возвращает:: аннотации данной конструкции для указанного типа аннотации, если она присутствует в этой конструкции, в противном случае пустой массив
См. также:: getAnnotationMirrors(), getAnnotation(Class), AnnotatedElement.getAnnotationsByType(Class), EnumConstantNotPresentException, AnnotationTypeMismatchException, IncompleteAnnotationException, MirroredTypeException, MirroredTypesException

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.