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

Интерфейсы, используемые для моделирования элементов языка программирования Java. Термин "элемент" в этом пакете используется для обозначения программных элементов, объявленных сущностей, составляющих программу. К элементам относятся классы, интерфейсы, методы, конструкторы и поля. Интерфейсы в этом пакете не моделируют структуру программы внутри тела метода; например, нет представления о цикле for или блоке try-finally. Конкретно, нет модели абстрактного синтаксического дерева (AST) структуры программы Java. Однако, интерфейсы могут моделировать некоторые структуры, встречающиеся только внутри тел методов, такие как локальные переменные, анонимные классы и параметры исключений. Следовательно, эти интерфейсы могут быть использованы API AST для моделирования объявлений, найденных в телах методов единиц компиляции Java (JLS 7.3).

При использовании в контексте обработки аннотаций должна возвращаться точная модель представляемого элемента. Поскольку это модель языка, исходный код предоставляет опорное (эталонное) представление рассматриваемого конструкта, а не представление в исполняемом выводе, таком как файл класса. Исполняемый вывод может служить основой для создания моделирующего элемента. Однако процесс преобразования исходного кода в исполняемый вывод может не позволить восстановить некоторые аспекты представления исходного кода. Например, аннотации с 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 аргумент.