Интерфейс 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; или
  • Никакая аннотация типа A не присутствует непосредственно на E, и E — класс, и тип A — наследуемый, и A присутствует в суперклассе E.
• Аннотация A ассоциирована с элементом E, если выполняется одно из условий:
  • A непосредственно или косвенно присутствует на E; или
  • Никакая аннотация типа A не присутствует непосредственно или косвенно на E, и 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.