Пакет javax.lang.model

Типы и иерархии пакетов, составляющих модель языка Java — рефлексивный API, моделирующий объявления и типы языка программирования Java. Элементы этого пакета и его подпакетов предназначены для задач и API моделирования и обработки языков, включая, помимо прочего, инфраструктуру обработки аннотаций.

В основе этой языковой модели лежит архитектура с использованием зеркал; см.

Гилад Браха и Дэвид Унгар. Зеркала: принципы проектирования средств метауровня для объектно-ориентированных языков программирования. В трудах конференции ACM по объектно-ориентированному программированию, системам, языкам и приложениям, октябрь 2004 г.

В частности, модель различает объявленные языковые конструкции, такие как элемент, представляющий java.util.Set, и семейство типов, которые могут быть связаны с элементом, например сырой тип java.util.Set, java.util.Set<String> и java.util.Set<T>.

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

Элементы и типы

Определения и использования

В общих чертах пакет element моделирует объявления, то есть определения элементов, а пакет type моделирует использования типов. В общем случае разные использования могут иметь индивидуальную информацию, отличную от информации, связанной с определением. В некотором смысле информация из определения является общей для всех использований.

Например, рассмотрим использования java.lang.String в приведённом ниже методе обработки строк identityOrEmpty:

Тип возвращаемого значения метода — это String с аннотацией типа @DefinitelyNotNull, а тип параметра — это String с аннотацией типа @MightBeNull. В рефлексивном API, поскольку набор аннотаций различается для двух использований String в качестве типа, тип возвращаемого значения и тип аргумента необходимо было бы представить разными объектами, чтобы различать эти два случая. Само определение java.lang.String не имеет ни одной из рассматриваемых аннотаций типа.

Другой пример — объявление обобщённого интерфейса (JLS 9.1.2) java.util.Set, у которого есть один параметр типа. Это объявление задаёт общую основу для множества параметризованных типов (JLS 4.5), производных от этого объявления, таких как java.util.Set<String>, java.util.Set<E>, java.util.Set<?>, а также для сырого типа (JLS 4.8) java.util.Set.

Отображение между элементами и типами

Хотя это разные понятия, между элементами и типами, то есть между определениями и использованиями, существуют частичные отображения в обоих направлениях. Например, грубо говоря, информацию, которая была бы инвариантной для всех использований типа, можно получить из элемента, определяющего этот тип. Рассмотрим, например, зеркало типа DeclaredType, моделирующее использование java.lang.String. Вызов DeclaredType.asElement() вернёт TypeElement для java.lang.String. Из TypeElement можно получить общую информацию, например имя и модификаторы.

Всем элементам можно сопоставить некоторый тип. Элементам классов и интерфейсов сопоставляется прототипический тип. И наоборот, в общем случае многим типам может соответствовать один и тот же элемент типа. Например, зеркало типа для сырого типа java.util.Set, прототипический тип java.util.Set<E> и тип java.util.Set<String> будут все сопоставлены с элементом типа для java.util.Set. Некоторым видам типов можно сопоставить элементы, но у других видов типов нет соответствующего элемента. Например, зеркало исполняемого типа не имеет соответствующего элемента, тогда как объявленный тип сопоставляется с элементом типа, как описано выше.