Types and hierarchies of packages comprising a Java language model, a reflective API that models the declarations and types of the Java programming language. The members of this package and its subpackages are for use in language modeling and language processing tasks and APIs including, but not limited to, the annotation processing framework.

This language model follows a mirror-based design; see

Gilad Bracha and David Ungar. Mirrors: Design Principles for Meta-level Facilities of Object-Oriented Programming Languages. In Proc. of the ACM Conf. on Object-Oriented Programming, Systems, Languages and Applications, October 2004.

In particular, the model makes a distinction between declared language constructs, like the element representing java.util.Set, and the family of types that may be associated with an element, like the raw type java.util.Set, java.util.Set<String>, and java.util.Set<T>.

Unless otherwise specified, methods in this package will throw a NullPointerException if given a null argument.

Elements and Types

Definitions and Uses

In broad terms the element package models the declarations, that is the definitions, of elements while the type package models uses of types. In general, distinct uses can have individualized information separate from the information associated with the definition. In some sense, the information in the definition is shared by all the uses.

For example, consider the uses of java.lang.String in the string processing method identityOrEmpty below:

The return type of the method is a String annotated with a @DefinitelyNotNull type annotation while the type of the parameter is a String annotated with a @MightBeNull type annotation. In a reflective API, since the set of annotations is different for the two uses of String as a type, the return type and argument type would need to be represented by different objects to distinguish between these two cases. The definition of java.lang.String itself is annotated with neither of the type annotations in question.

Another example, consider the declaration of the generic interface (JLS 9.1.2) java.util.Set which has one type parameter. This declaration captures commonality between the many parameterized types (JLS 4.5) derived from that declaration such as java.util.Set<String>, java.util.Set<E>, java.util.Set<?>, and also the raw type (JLS 4.8) java.util.Set.

Mapping between Elements and Types

While distinct concepts, there are bidirectional (partial) mappings between elements and types, between definitions and uses. For example, roughly speaking, information that would be invariant for all uses of a type can be retrieved from the element defining a type. For example, consider a DeclaredType type mirror modeling a use of java.lang.String. Calling DeclaredType.asElement() would return the TypeElement for java.lang.String. From the TypeElement, common information such as name and modifiers can be retrieved.

All elements can be mapped to some type. The elements for classes and interfaces get mapped to a prototypical type. Conversely, in general, many types can map to the same type element. For example, the type mirror for the raw type java.util.Set, the prototypical type java.util.Set<E>, and the type java.util.Set<String> would all map to the type element for java.util.Set. Several kinds of types can be mapped to elements, but other kinds of types do not have an element mapping. For example, the type mirror of an executable type does not have an element mapping while a declared type would map to a type element, as discussed above.