Интерфейс 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 изначально не является повторяемым, а впоследствии становится повторяемым, следует учитывать несколько аспектов совместимости. Контейнерный тип аннотации для T — это TC.

• Изменение типа T, делающее его повторяемым, совместимо на уровне исходного кода и двоичной совместимости с существующими применениями T и TC. То есть с точки зрения совместимости исходного кода исходный код с аннотациями типа T или TC по-прежнему будет компилироваться. С точки зрения двоичной совместимости файлы классов с аннотациями типа T или TC (либо с другими видами применений типов T или TC) будут связываться с изменённой версией T, если они связывались с предыдущей версией. (До формального объявления T повторяемым тип аннотации TC может неформально выступать в роли контейнерного типа. В качестве альтернативы, когда 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.