Пакет javax.lang.model.element

Интерфейсы, используемые для моделирования элементов языка программирования Java. Термин «элемент» в этом пакете используется для обозначения программных элементов, объявленных сущностей, составляющих программу. Элементы включают классы, интерфейсы, методы, конструкторы и поля. Интерфейсы в этом пакете не моделируют структуру программы внутри тела метода; например, нет представления о цикле for или блоке try-finally. Однако интерфейсы могут моделировать некоторые структуры, встречающиеся только внутри тел методов, такие как локальные переменные и анонимные классы.

При использовании в контексте обработки аннотаций необходимо возвращать точную модель представляемого элемента. Поскольку это языковая модель, исходный код предоставляет эталонное (ссылочное) представление рассматриваемой конструкции, а не представление в исполняемом выходе, например, в файле класса. Исполняемый вывод может служить основой для создания моделируемого элемента. Однако процесс перевода исходного кода в исполняемый вывод может не позволять восстанавливать некоторые аспекты представления исходного кода. Например, аннотации с source retention нельзя восстановить из файлов классов, а файлы классов могут не содержать информацию о позиции исходного кода. Имена параметров могут быть не восстановимы из файлов классов. Модификаторы модификаторов на элементе, созданном из файла класса, в некоторых случаях могут отличаться от элемента для того же объявления, созданного из исходного файла, включая:

• strictfp для класса или интерфейса
• final для параметра
• protected, private, и static для классов и интерфейсов

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

Во время обработки аннотаций необходимо работать с неполными или ошибочными программами; однако гарантий о характере полученной модели меньше. Если исходный код не является синтаксически корректным или содержит другую невосстанавливаемую ошибку, которая не может быть устранена путем генерации новых классов или интерфейсов, модель может быть или не быть предоставлена в качестве проблемы качества реализации. Если программа синтаксически верна, но ошибочна каким-то другим образом, любая возвращенная модель должна иметь не меньше информации, чем если бы все тела методов в программе были заменены на "throw new RuntimeException();". Если программа ссылается на отсутствующий класс или интерфейс Xyz, возвращенная модель должна содержать не меньше информации, чем если бы объявление класса или интерфейса Xyz предполагалось "class Xyz {}", "interface Xyz {}", "enum Xyz {}", "@interface Xyz {}", или "record Xyz {}". Если программа ссылается на отсутствующий класс или интерфейс Xyz<K1, ... ,Kn>, возвращенная модель должна содержать не меньше информации, чем если бы объявление Xyz предполагалось "class Xyz<T1, ... ,Tn> {}" или "interface Xyz<T1, ... ,Tn> {}"

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

Если не указано иное, методы в этом пакете будут выбрасывать NullPointerException при получении аргумента null.