Пакет javax.lang.model

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

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

Гилад Браха и Дэвид Унгар. Зеркала: Принципы проектирования метауровневых средств объектно-ориентированных языков программирования. В Proc. of the ACM Conf. on Object-Oriented Programming, Systems, Languages and Applications, октябрь 2004.

В частности, модель различает объявленные языковые конструкции, такие как элемент element, представляющий 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. Несколько видов типов могут быть отображены на элементы, но другие виды типов не имеют отображения на элемент. Например, зеркальное отображение типа выполнимого кода не имеет отображения на элемент, в то время как объявленный тип отображается на элемент типа, как описано выше.