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

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

Для вызова 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.