Интерфейс AnnotatedElement

public interface AnnotatedElement

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

Методы getAnnotationsByType(Class) и getDeclaredAnnotationsByType(Class) поддерживают несколько аннотаций одного типа на элементе. Если аргумент любого из этих методов является повторяющимся типом аннотации (JLS 9.6), то метод «просмотрит» контейнерную аннотацию (JLS 9.7), если она есть, и вернет любые аннотации внутри контейнера. Контейнерные аннотации могут быть сгенерированы во время компиляции для обертывания нескольких аннотаций указанного типа.

В этом интерфейсе используются термины прямо присутствующая, косвенно присутствующая, присутствующая и ассоциированная, чтобы точно описать, какие аннотации возвращаются методами:

• Аннотация A прямо присутствует на элементе E, если у E есть атрибут RuntimeVisibleAnnotations или RuntimeVisibleParameterAnnotations или RuntimeVisibleTypeAnnotations, и атрибут содержит A.
• Аннотация A косвенно присутствует на элементе E, если у E есть атрибут RuntimeVisibleAnnotations или RuntimeVisibleParameterAnnotations или RuntimeVisibleTypeAnnotations, тип A является повторяющимся, и атрибут содержит ровно одну аннотацию, значение которой содержит A, а тип — тип содержащей аннотации типа A.
• Аннотация A присутствует на элементе E, если выполняется одно из следующих условий:
  • A прямо присутствует на E; или
  • Прямо на E нет аннотации типа A, E — класс, тип A — наследуемый, и A присутствует в суперклассе E.
• Аннотация A ассоциирована с элементом E, если выполняется одно из следующих условий:
  • A прямо или косвенно присутствует на E; или
  • Прямо или косвенно на E нет аннотации типа A, E — класс, тип A — наследуемый, и A ассоциирована с суперклассом E.

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

		Вид присутствия
Метод		Прямо присутствующая	Косвенно присутствующая	Присутствующая	Ассоциированная
T	getAnnotation(Class<T>)			X
Annotation[]	getAnnotations()			X
T[]	getAnnotationsByType(Class<T>)				X
T	getDeclaredAnnotation(Class<T>)	X
Annotation[]	getDeclaredAnnotations()	X
T[]	getDeclaredAnnotationsByType(Class<T>)	X	X

Для вызова get[Declared]AnnotationsByType( Class < T >), порядок аннотаций, которые прямо или косвенно присутствуют на элементе E, вычисляется так, как будто косвенно присутствующие аннотации на E прямо присутствуют на E вместо своей контейнерной аннотации, в порядке их появления в элементе значения контейнерной аннотации.

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

• Изменение T на повторяющийся тип совместимо с исходным и двоичным кодом с существующими использованиями T и TC. То есть для совместимости исходного кода код с аннотациями типа T или типа TC по-прежнему будет компилироваться. Для совместимости двоичного кода файлы классов с аннотациями типа T или типа TC (или с другими видами использования типа T или типа TC) будут связаны с изменённой версией T, если они связывались с предыдущей версией. (Тип аннотации TC может неофициально служить действующим типом содержащей аннотации до формального объявления T повторяющимся. В качестве альтернативы, когда T делается повторяющимся, TC может быть введён как новый тип.)
• Если аннотация типа TC присутствует на элементе, и T модифицируется для повторного использования с TC в качестве типа содержащей аннотации, то:
  • Изменение T совместимо с поведением методов get[Declared]Annotation(Class<T>) (вызываемых с аргументом T или TC) и get[Declared]Annotations() из-за того, что результаты методов не изменятся из-за того, что TC стал типом содержащей аннотации для T.
  • Изменение T изменяет результаты методов get[Declared]AnnotationsByType(Class<T>), вызываемых с аргументом T, так как эти методы теперь будут распознавать аннотацию типа TC как контейнерную аннотацию для T и «просматривать» её, чтобы открыть аннотации типа T.
• Если аннотация типа T присутствует на элементе, и T делается повторяющимся, и к элементу добавляются дополнительные аннотации типа T:
  • Добавление аннотаций типа T совместимо с исходным и двоичным кодом.
  • Добавление аннотаций типа T изменяет результаты методов get[Declared]Annotation(Class<T>) и get[Declared]Annotations(), так как эти методы теперь будут видеть только контейнерную аннотацию на элементе, а не аннотацию типа T.
  • Добавление аннотаций типа T изменяет результаты методов get[Declared]AnnotationsByType(Class<T>), так как их результаты теперь покажут дополнительные аннотации типа T, в то время как ранее они показывали только одну аннотацию типа T.

Если аннотация, возвращаемая методом этого интерфейса, содержит (прямо или косвенно) член со значением Class, ссылающийся на класс, недоступный в этой виртуальной машине, попытка чтения класса путём вызова соответствующего метода Class-возвращающего метода на возвращенной аннотации приведёт к TypeNotPresentException.

Аналогично, попытка чтения члена со значением перечисления приведёт к EnumConstantNotPresentException, если константа перечисления в аннотации больше не присутствует в типе перечисления.

Если тип аннотации T (мета-)аннотирован аннотацией @Repeatable, значение элемента которой указывает на тип TC, но TC не объявляет метод value() с возвращаемым типом T[], то выбрасывается исключение типа AnnotationFormatError.

Наконец, попытка чтения члена, чьё определение эволюционировало несовместимо, приведёт к AnnotationTypeMismatchException или IncompleteAnnotationException.

Методы

isAnnotationPresent

default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)

Параметры:

annotationClass - объект Class, соответствующий типу аннотации

Возвращает:

true, если аннотация указанного типа аннотации присутствует на этом элементе, в противном случае false

Исключения:

NullPointerException - если переданный класс аннотации равен null

С:

1.5

getAnnotation

<T extends Annotation> T getAnnotation(Class<T> annotationClass)

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

Параметры типа:

T - тип аннотации, для запроса и возврата, если она присутствует

Параметры:

annotationClass - объект Class, соответствующий типу аннотации

Возвращает:

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

Исключения:

NullPointerException - если переданный класс аннотации равен null

С:

1.5

getAnnotations

Annotation[] getAnnotations()

Возвращает аннотации, которые присутствуют на этом элементе. Если на этом элементе нет аннотаций, возвращаемое значение — массив длины 0. Вызывающий метод может изменять возвращаемый массив; это не повлияет на массивы, возвращаемые другим вызывающим методам.

Возвращает:

аннотации, присутствующие на этом элементе

С:

1.5

getAnnotationsByType

default <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass)

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

Требования к реализации:

В реализации по умолчанию сначала вызывается getDeclaredAnnotationsByType(Class), передавая annotationClass в качестве аргумента. Если возвращаемый массив имеет длину больше нуля, возвращается массив. Если возвращаемый массив имеет длину ноль, и этот AnnotatedElement является классом, а тип аргумента — наследуемым типом аннотации, и суперкласс этого AnnotatedElement не равен null, то возвращаемое значение — результат вызова getAnnotationsByType(Class) на суперклассе с annotationClass в качестве аргумента. В противном случае возвращается массив длины ноль.

Параметры типа:

T - тип аннотации, для запроса и возврата, если она присутствует

Параметры:

annotationClass - объект Class, соответствующий типу аннотации

Возвращает:

все аннотации этого элемента для указанного типа аннотации, если они связаны с этим элементом, в противном случае массив длины ноль

Исключения:

NullPointerException - если переданный класс аннотации равен null

С:

1.8

getDeclaredAnnotation

default <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass)

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

Требования к реализации:

Реализация по умолчанию сначала выполняет проверку на null, а затем проходит по результатам getDeclaredAnnotations(), возвращая первую аннотацию, тип аннотации которой соответствует типу аргумента.

Параметры типа:

T - тип аннотации, для запроса и возврата, если она непосредственно присутствует

Параметры:

annotationClass - объект Class, соответствующий типу аннотации

Возвращает:

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

Исключения:

NullPointerException - если переданный класс аннотации равен null

С:

1.8

getDeclaredAnnotationsByType

default <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass)

Возвращает аннотацию(и) этого элемента для указанного типа, если такие аннотации непосредственно присутствуют или косвенно присутствуют. Этот метод игнорирует унаследованные аннотации. Если на этом элементе нет указанных аннотаций, прямо или косвенно, возвращаемое значение — массив длины 0. Различие между этим методом и getDeclaredAnnotation(Class) заключается в том, что этот метод определяет, является ли его аргумент повторяющимся типом аннотации (JLS 9.6), и в случае положительного ответа пытается найти одну или несколько аннотаций этого типа, «просматривая» контейнерную аннотацию, если она присутствует. Вызывающий метод может изменять возвращаемый массив; это не повлияет на массивы, возвращаемые другим вызывающим методам.

Требования к реализации:

Реализация по умолчанию может вызвать getDeclaredAnnotation(Class) один или несколько раз, чтобы найти непосредственно присутствующую аннотацию и, если тип аннотации повторяется, чтобы найти контейнерную аннотацию. Если аннотации типа annotationClass присутствуют как непосредственно, так и косвенно, тогда getDeclaredAnnotations() будет вызван для определения порядка элементов в возвращаемом массиве.

Альтернативно, реализация по умолчанию может вызвать getDeclaredAnnotations() один раз, и возвращаемый массив будет проанализирован на наличие как непосредственно, так и косвенно присутствующих аннотаций. Результаты вызова getDeclaredAnnotations() предполагаются согласованными с результатами вызова getDeclaredAnnotation(Class).

Параметры типа:

T - тип аннотации, для запроса и возврата, если она непосредственно или косвенно присутствует

Параметры:

annotationClass - объект Class, соответствующий типу аннотации

Возвращает:

все аннотации этого элемента для указанного типа аннотации, если они непосредственно или косвенно присутствуют на этом элементе, в противном случае массив длины ноль

Исключения:

NullPointerException - если переданный класс аннотации равен null

С:

1.8

getDeclaredAnnotations

Annotation[] getDeclaredAnnotations()

Возвращает аннотации, которые непосредственно присутствуют на этом элементе. Этот метод игнорирует унаследованные аннотации. Если на этом элементе нет непосредственно присутствующих аннотаций, возвращаемое значение — массив длины 0. Вызывающий метод может изменять возвращаемый массив; это не повлияет на массивы, возвращаемые другим вызывающим методам.

Возвращает:

аннотации, непосредственно присутствующие на этом элементе

С:

1.5