Package javax.lang.model
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 theelement 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:
 
// Return the argument if it is non-null and the empty string otherwise.
public static @DefinitelyNotNull String identityOrEmpty(@MightBeNull String argument) {
   ...
}
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 aDeclaredType 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.
- Since:
- 1.6
- See Also:
- 
ClassDescriptionRepresents a construct that can be annotated.Source versions of the Java programming language.Superclass of exceptions which indicate that an unknown kind of entity was encountered.