Интерфейс AnnotatedElement

public interface AnnotatedElement

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

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

Методы 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.

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

Обзор типов присутствия, определяемых различными методами AnnotatedElement

Метод		Тип присутствия
Тип возвращаемого значения	Подпись	Прямо присутствующая	Косвенно присутствующая	Присутствующая	Связанная
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.