Пакет 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 {}". Если программа ссылается на отсутствующий тип XYZ<K1, ... ,Kn>, возвращаемая модель должна содержать не меньше информации, чем если бы объявление типа XYZ предполагалось "class XYZ<T1, ... ,Tn> {}" или "interface XYZ<T1, ... ,Tn> {}".

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

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