javax.lang.model (Java SE 25 & JDK 25)
Description: declaration: module: java.compiler, package: javax.lang.model
Keywords: javax.lang.model package

# Package javax.lang.model

package javax.lang.model
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:

    // Return the argument if it is non-null and the empty string otherwise.
    public static @DefinitelyNotNull String identityOrEmpty(@MightBeNull String argument) {
       ...
    }

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.

Since:
  1.6
See Also:
  - JSR 269: Pluggable Annotation Processing API

- Related Packages
  Package
  Description
  javax.lang.model.element
  Interfaces used to model elements of the Java programming language.
  javax.lang.model.type
  Interfaces used to model Java programming language types.
  javax.lang.model.util
  Utilities to assist in the processing of program elements and types.
- Class
  Description
  AnnotatedConstruct
  Represents a construct that can be annotated.
  SourceVersion
  Source versions of the Java programming language.
  UnknownEntityException
  Superclass of exceptions which indicate that an unknown kind of entity was encountered.