/* * Copyright (c) 2005, 2023, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ /** * Types and hierarchies of packages comprising a {@index "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 {@linkplain javax.annotation.processing * 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 {@linkplain javax.lang.model.element * element} representing {@code java.util.Set}, and the family of * {@linkplain javax.lang.model.type types} that may be associated * with an element, like the raw type {@code java.util.Set}, {@code * java.util.Set}, and {@code java.util.Set}. * *

Unless otherwise specified, methods in this package will throw * a {@code NullPointerException} if given a {@code null} argument. * *

Elements and Types

* *

Definitions and Uses

* * In broad terms the {@link javax.lang.model.element element} package * models the declarations, that is the definitions, of elements while * the {@link javax.lang.model.type 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 {@code * java.lang.String} in the string processing method {@code * identityOrEmpty} below: * * {@snippet lang=java : * // 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 {@code String} annotated with * a {@code @DefinitelyNotNull} type annotation while the type of * the parameter is a {@code String} annotated with a {@code * @MightBeNull} type annotation. In a reflective API, since the set * of annotations is different for the two uses of {@code * 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 {@code java.lang.String} itself * is annotated with neither of the type annotations in question. * *

Another example, consider the declaration of the generic * interface (JLS {@jls 9.1.2}) {@code java.util.Set} which has one * type parameter. This declaration captures commonality between the * many parameterized types (JLS {@jls 4.5}) derived from that * declaration such as {@code java.util.Set}, {@code * java.util.Set}, {@code java.util.Set}, and also the raw type * (JLS {@jls 4.8}) {@code 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 {@link * javax.lang.model.type.DeclaredType DeclaredType} type mirror * modeling a use of {@code java.lang.String}. Calling {@link * javax.lang.model.type.DeclaredType#asElement()} would return the * {@link javax.lang.model.element.TypeElement} for {@code * java.lang.String}. From the {@code TypeElement}, common information * such as {@linkplain * javax.lang.model.element.TypeElement#getSimpleName() name} and * {@linkplain javax.lang.model.element.TypeElement#getModifiers() * modifiers} can be retrieved. * *

All elements can be {@linkplain * javax.lang.model.element.Element#asType() mapped to} some type. * The elements for classes and interfaces get {@linkplain * javax.lang.model.element.TypeElement#asType() mapped to} a * {@linkplain javax.lang.model.element.TypeElement#asType() prototypical type}. * Conversely, in general, many types can map to the same * {@linkplain javax.lang.model.element.TypeElement type element}. For * example, the type mirror for the raw type {@code java.util.Set}, * the prototypical type {@code java.util.Set}, and the type {@code * java.util.Set} would all {@linkplain * javax.lang.model.type.DeclaredType#asElement() map to} the type * element for {@code java.util.Set}. Several kinds of types can be * mapped to elements, but other kinds of types do not have * an {@linkplain javax.lang.model.util.Types#asElement(TypeMirror) * element mapping}. For example, the type mirror of an {@linkplain * javax.lang.model.type.ExecutableType executable type} does * not have an element mapping while a {@linkplain * javax.lang.model.type.DeclaredType declared type} would map to a * {@linkplain javax.lang.model.element.TypeElement type element}, as * discussed above. * * @since 1.6 * * @see * JSR 269: Pluggable Annotation Processing API */ package javax.lang.model;