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.