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

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

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

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