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

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

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

• 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.