/*
* Copyright (c) 2005, 2017, 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.
*/
Interfaces used to model elements of the Java programming language. The term "element" in this package is used to refer to program elements, the declared entities that make up a program. Elements include classes, interfaces, methods, constructors, and fields. The interfaces in this package do not model the structure of a program inside a method body; for example there is no representation of a for loop or try-finally block. However, the interfaces can model some structures only appearing inside method bodies, such as local variables and anonymous classes. When used in the context of annotation processing, an accurate model of the element being represented must be returned. As this is a language model, the source code provides the fiducial (reference) representation of the construct in question rather than a representation in an executable output like a class file. Executable output may serve as the basis for creating a modeling element. However, the process of translating source code to executable output may not permit recovering some aspects of the source code representation. For example, annotations with source retention cannot be recovered from class files and class files might not be able to provide source position information. Names of parameters may not be recoverable from class files. The modifiers on an element created from a class file may differ in some cases from an element for the same declaration created from a source file including:
-
strictfp on a class or interface -
final on a parameter -
protected, private, and static on classes and interfaces
Some elements which are mandated may not be marked as such when created from class files. Additionally, synthetic constructs in a class file, such as accessor methods used in implementing nested classes and
bridge methods used in implementing covariant returns, are translation artifacts strictly outside of this model. However, when operating on class files, it is helpful be able to operate on such elements, screening them out when appropriate. During annotation processing, operating on incomplete or erroneous programs is necessary; however, there are fewer guarantees about the nature of the resulting model. If the source code is not syntactically well-formed or has some other irrecoverable error that could not be removed by the generation of new types, a model may or may not be provided as a quality of implementation issue. If a program is syntactically valid but erroneous in some other fashion, any returned model must have no less information than if all the method bodies in the program were replaced by "throw
new RuntimeException();". If a program refers to a missing type Xyz, the returned model must contain no less information than if the declaration of type Xyz were assumed to be "class Xyz {}", "interface Xyz {}", "enum Xyz {}", or
"@interface Xyz {}". If a program refers to a missing type
Xyz<K1, ... ,Kn>, the returned model must contain no less information than if the declaration of Xyz were assumed to be "class Xyz<T1, ... ,Tn> {}" or "interface Xyz<T1,
... ,Tn> {}"
Unless otherwise specified in a particular implementation, the
collections returned by methods in this package should be expected
to be unmodifiable by the caller and unsafe for concurrent access.
Unless otherwise specified, methods in this package will throw a NullPointerException if given a null argument.
Author: Joseph D. Darcy, Scott Seligman, Peter von der Ahé Since: 1.6
/**
* Interfaces used to model elements of the Java programming language.
*
* The term "element" in this package is used to refer to program
* elements, the declared entities that make up a program. Elements
* include classes, interfaces, methods, constructors, and fields.
* The interfaces in this package do not model the structure of a
* program inside a method body; for example there is no
* representation of a {@code for} loop or {@code try}-{@code finally}
* block. However, the interfaces can model some structures only
* appearing inside method bodies, such as local variables and
* anonymous classes.
*
* <p>When used in the context of annotation processing, an accurate
* model of the element being represented must be returned. As this
* is a language model, the source code provides the fiducial
* (reference) representation of the construct in question rather than
* a representation in an executable output like a class file.
* Executable output may serve as the basis for creating a modeling
* element. However, the process of translating source code to
* executable output may not permit recovering some aspects of the
* source code representation. For example, annotations with
* {@linkplain java.lang.annotation.RetentionPolicy#SOURCE source}
* {@linkplain java.lang.annotation.Retention retention} cannot be
* recovered from class files and class files might not be able to
* provide source position information.
*
* Names of parameters may not be recoverable from class files.
*
* The {@linkplain javax.lang.model.element.Modifier modifiers} on an
* element created from a class file may differ in some cases from an
* element for the same declaration created from a source file
* including:
*
* <ul>
* <li> {@code strictfp} on a class or interface
* <li> {@code final} on a parameter
* <li> {@code protected}, {@code private}, and {@code static} on classes and interfaces
* </ul>
*
* Some elements which are {@linkplain
* javax.lang.model.util.Elements.Origin#MANDATED mandated} may not be
* marked as such when created from class files.
*
* Additionally, {@linkplain
* javax.lang.model.util.Elements.Origin#SYNTHETIC synthetic}
* constructs in a class file, such as accessor methods used in
* implementing nested classes and {@linkplain
* javax.lang.model.util.Elements.Origin#isBridge(ExecutableElement)
* bridge methods} used in implementing covariant returns, are
* translation artifacts strictly outside of this model. However, when
* operating on class files, it is helpful be able to operate on such
* elements, screening them out when appropriate.
*
* <p>During annotation processing, operating on incomplete or
* erroneous programs is necessary; however, there are fewer
* guarantees about the nature of the resulting model. If the source
* code is not syntactically well-formed or has some other
* irrecoverable error that could not be removed by the generation of
* new types, a model may or may not be provided as a quality of
* implementation issue.
* If a program is syntactically valid but erroneous in some other
* fashion, any returned model must have no less information than if
* all the method bodies in the program were replaced by {@code "throw
* new RuntimeException();"}. If a program refers to a missing type Xyz,
* the returned model must contain no less information than if the
* declaration of type Xyz were assumed to be {@code "class Xyz {}"},
* {@code "interface Xyz {}"}, {@code "enum Xyz {}"}, or {@code
* "@interface Xyz {}"}. If a program refers to a missing type {@code
* Xyz<K1, ... ,Kn>}, the returned model must contain no less
* information than if the declaration of Xyz were assumed to be
* {@code "class Xyz<T1, ... ,Tn> {}"} or {@code "interface Xyz<T1,
* ... ,Tn> {}"}
*
* <p> Unless otherwise specified in a particular implementation, the
* collections returned by methods in this package should be expected
* to be unmodifiable by the caller and unsafe for concurrent access.
*
* <p> Unless otherwise specified, methods in this package will throw
* a {@code NullPointerException} if given a {@code null} argument.
*
* @author Joseph D. Darcy
* @author Scott Seligman
* @author Peter von der Ahé
* @since 1.6
*/
package javax.lang.model.element;