Интерфейс 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.

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

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

Существуют некоторые проблемы совместимости, которые необходимо учитывать, если тип аннотации 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.