118 lines
5.2 KiB
HTML
Executable File
118 lines
5.2 KiB
HTML
Executable File
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<html>
|
|
<head>
|
|
<!--
|
|
@(#)overview.html 1.1 04/07/19
|
|
|
|
Copyright (c) 2004, Sun Microsystems, Inc.
|
|
All rights reserved.
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are met:
|
|
|
|
* Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
* Redistributions in binary form must reproduce the above copyright
|
|
notice, this list of conditions and the following disclaimer in the
|
|
documentation and/or other materials provided with the distribution.
|
|
* Neither the name of the Sun Microsystems, Inc. nor the names of
|
|
its contributors may be used to endorse or promote products derived from
|
|
this software without specific prior written permission.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
|
|
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
|
|
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
|
|
OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
|
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
-->
|
|
</head>
|
|
|
|
<body bgcolor="white">
|
|
|
|
The Mirror API is used to model the semantic structure of a program.
|
|
It provides representations of the entities
|
|
declared in a program, such as classes, methods, and fields.
|
|
Constructs below the method level, such as
|
|
individual statements and expressions, are not represented.
|
|
|
|
<p> Also included is support for writing
|
|
{@linkplain com.sun.mirror.apt.AnnotationProcessor annotation processors}
|
|
to examine and process the annotations
|
|
of program elements. An annotation processor may, as an example, create
|
|
new source files and XML documents to be used in conjunction with the
|
|
original code.
|
|
|
|
|
|
<h4> Characteristics of the API </h4>
|
|
|
|
A program is represented at the language level, rather than at the
|
|
level of the virtual machine. Nested classes, for example, are
|
|
handled as first-class constructs,
|
|
rather than in the translated form understood by the VM.
|
|
Both source code and compiled code (class files) may be modeled
|
|
in this way.
|
|
|
|
<p> Programs are modeled in their static, or build-time, form.
|
|
This differs from the {@linkplain java.lang.reflect reflection} API,
|
|
which provides run-time information about classes and objects.
|
|
|
|
<p> The API does not provide direct support for generating new code.
|
|
|
|
|
|
<h4> Declarations and Types </h4>
|
|
|
|
The mirror API represents program constructs principally through the
|
|
{@link com.sun.mirror.declaration.Declaration} interface
|
|
and its hierarchy of subinterfaces in the package {@link
|
|
com.sun.mirror.declaration}. A <tt>Declaration</tt> represents a
|
|
program element such as a package, class, or method.
|
|
The interface hierarchy is depicted
|
|
<a href="com/sun/mirror/declaration/package-tree.html"> here</a>.
|
|
|
|
<p> Types are represented by the {@link com.sun.mirror.type.TypeMirror}
|
|
interface and its hierarchy of subinterfaces in the
|
|
package {@link com.sun.mirror.type}. Types include primitive types,
|
|
class and interface types, array types, type variables, and wildcards.
|
|
The interface hierarchy is depicted
|
|
<a href="com/sun/mirror/type/package-tree.html"> here</a>.
|
|
|
|
<p> The API makes a clear distinction between declarations and types.
|
|
This is most significant for generic types, where a single declaration
|
|
can define an infinite family of types. For example, the declaration of
|
|
<tt>java.util.Set</tt> defines the raw type <tt>java.util.Set</tt>,
|
|
the parameterized type {@code java.util.Set
|
|
<String>},
|
|
and much more. Only the declaration can be annotated, for example,
|
|
and only a type can appear in a method signature.
|
|
|
|
<p> A program being modeled may be incomplete, in that
|
|
it may depend on an unknown class or interface type.
|
|
This may be the result of a processing error such as a missing class file,
|
|
or perhaps the missing type is to be created by an annotation processor.
|
|
See {@link com.sun.mirror.type.DeclaredType} for information on
|
|
how such unknown types are handled.
|
|
|
|
|
|
<h4> Utilities and Tool Support </h4>
|
|
|
|
The {@link com.sun.mirror.util} package provides
|
|
utilities to assist in the processing of declarations and types.
|
|
Included is support for using the visitor design pattern when
|
|
operating on declaration and type objects.
|
|
|
|
<p> The {@link com.sun.mirror.apt} package supports the writing
|
|
of annotation processors. It provides the mechanism for them to
|
|
interact with an annotation processing tool.
|
|
|
|
|
|
@since 1.5
|
|
|
|
</body>
|
|
</html>
|