Interfaces used to model elements of the Java programming language.
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. The modifiers on an element may
differ in some cases including
-
strictfp
on a class or interface
-
final
on a parameter
-
protected
, private
, and static
on classes and interfaces
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 outside of this model.
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, 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, the
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.