Пакет 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 аргумент.