mirror of
https://github.com/openjdk/jdk.git
synced 2026-06-06 10:42:45 +00:00
112 lines
4.4 KiB
HTML
112 lines
4.4 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<html>
|
|
<head>
|
|
<!--
|
|
|
|
Copyright (c) 2004, 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
|
|
CA 95054 USA or visit www.sun.com if you need additional information or
|
|
have any questions.
|
|
-->
|
|
</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>
|