|
10
|
1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
|
2 |
<html>
|
|
|
3 |
<head>
|
|
|
4 |
<!--
|
|
|
5 |
|
|
|
6 |
Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.
|
|
|
7 |
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
|
8 |
|
|
|
9 |
This code is free software; you can redistribute it and/or modify it
|
|
|
10 |
under the terms of the GNU General Public License version 2 only, as
|
|
|
11 |
published by the Free Software Foundation. Sun designates this
|
|
|
12 |
particular file as subject to the "Classpath" exception as provided
|
|
|
13 |
by Sun in the LICENSE file that accompanied this code.
|
|
|
14 |
|
|
|
15 |
This code is distributed in the hope that it will be useful, but WITHOUT
|
|
|
16 |
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
|
17 |
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
|
18 |
version 2 for more details (a copy is included in the LICENSE file that
|
|
|
19 |
accompanied this code).
|
|
|
20 |
|
|
|
21 |
You should have received a copy of the GNU General Public License version
|
|
|
22 |
2 along with this work; if not, write to the Free Software Foundation,
|
|
|
23 |
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
|
24 |
|
|
|
25 |
Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
|
|
|
26 |
CA 95054 USA or visit www.sun.com if you need additional information or
|
|
|
27 |
have any questions.
|
|
|
28 |
-->
|
|
|
29 |
</head>
|
|
|
30 |
|
|
|
31 |
<body bgcolor="white">
|
|
|
32 |
|
|
|
33 |
The Mirror API is used to model the semantic structure of a program.
|
|
|
34 |
It provides representations of the entities
|
|
|
35 |
declared in a program, such as classes, methods, and fields.
|
|
|
36 |
Constructs below the method level, such as
|
|
|
37 |
individual statements and expressions, are not represented.
|
|
|
38 |
|
|
|
39 |
<p> Also included is support for writing
|
|
|
40 |
{@linkplain com.sun.mirror.apt.AnnotationProcessor annotation processors}
|
|
|
41 |
to examine and process the annotations
|
|
|
42 |
of program elements. An annotation processor may, as an example, create
|
|
|
43 |
new source files and XML documents to be used in conjunction with the
|
|
|
44 |
original code.
|
|
|
45 |
|
|
|
46 |
|
|
|
47 |
<h4> Characteristics of the API </h4>
|
|
|
48 |
|
|
|
49 |
A program is represented at the language level, rather than at the
|
|
|
50 |
level of the virtual machine. Nested classes, for example, are
|
|
|
51 |
handled as first-class constructs,
|
|
|
52 |
rather than in the translated form understood by the VM.
|
|
|
53 |
Both source code and compiled code (class files) may be modeled
|
|
|
54 |
in this way.
|
|
|
55 |
|
|
|
56 |
<p> Programs are modeled in their static, or build-time, form.
|
|
|
57 |
This differs from the {@linkplain java.lang.reflect reflection} API,
|
|
|
58 |
which provides run-time information about classes and objects.
|
|
|
59 |
|
|
|
60 |
<p> The API does not provide direct support for generating new code.
|
|
|
61 |
|
|
|
62 |
|
|
|
63 |
<h4> Declarations and Types </h4>
|
|
|
64 |
|
|
|
65 |
The mirror API represents program constructs principally through the
|
|
|
66 |
{@link com.sun.mirror.declaration.Declaration} interface
|
|
|
67 |
and its hierarchy of subinterfaces in the package {@link
|
|
|
68 |
com.sun.mirror.declaration}. A <tt>Declaration</tt> represents a
|
|
|
69 |
program element such as a package, class, or method.
|
|
|
70 |
The interface hierarchy is depicted
|
|
|
71 |
<a href="com/sun/mirror/declaration/package-tree.html"> here</a>.
|
|
|
72 |
|
|
|
73 |
<p> Types are represented by the {@link com.sun.mirror.type.TypeMirror}
|
|
|
74 |
interface and its hierarchy of subinterfaces in the
|
|
|
75 |
package {@link com.sun.mirror.type}. Types include primitive types,
|
|
|
76 |
class and interface types, array types, type variables, and wildcards.
|
|
|
77 |
The interface hierarchy is depicted
|
|
|
78 |
<a href="com/sun/mirror/type/package-tree.html"> here</a>.
|
|
|
79 |
|
|
|
80 |
<p> The API makes a clear distinction between declarations and types.
|
|
|
81 |
This is most significant for generic types, where a single declaration
|
|
|
82 |
can define an infinite family of types. For example, the declaration of
|
|
|
83 |
<tt>java.util.Set</tt> defines the raw type <tt>java.util.Set</tt>,
|
|
|
84 |
the parameterized type {@code java.util.Set<String>},
|
|
|
85 |
and much more. Only the declaration can be annotated, for example,
|
|
|
86 |
and only a type can appear in a method signature.
|
|
|
87 |
|
|
|
88 |
<p> A program being modeled may be incomplete, in that
|
|
|
89 |
it may depend on an unknown class or interface type.
|
|
|
90 |
This may be the result of a processing error such as a missing class file,
|
|
|
91 |
or perhaps the missing type is to be created by an annotation processor.
|
|
|
92 |
See {@link com.sun.mirror.type.DeclaredType} for information on
|
|
|
93 |
how such unknown types are handled.
|
|
|
94 |
|
|
|
95 |
|
|
|
96 |
<h4> Utilities and Tool Support </h4>
|
|
|
97 |
|
|
|
98 |
The {@link com.sun.mirror.util} package provides
|
|
|
99 |
utilities to assist in the processing of declarations and types.
|
|
|
100 |
Included is support for using the visitor design pattern when
|
|
|
101 |
operating on declaration and type objects.
|
|
|
102 |
|
|
|
103 |
<p> The {@link com.sun.mirror.apt} package supports the writing
|
|
|
104 |
of annotation processors. It provides the mechanism for them to
|
|
|
105 |
interact with an annotation processing tool.
|
|
|
106 |
|
|
|
107 |
|
|
|
108 |
@since 1.5
|
|
|
109 |
|
|
|
110 |
</body>
|
|
|
111 |
</html>
|