| author | ohair |
| Wed, 26 May 2010 20:22:54 -0700 | |
| changeset 5568 | 8450cc6bc21c |
| parent 5520 | 86e4b9a9da40 |
| permissions | -rw-r--r-- |
| 10 | 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
2 |
<html> |
|
3 |
<head> |
|
4 |
<!-- |
|
5 |
||
| 5520 | 6 |
Copyright (c) 2004, Oracle and/or its affiliates. All rights reserved. |
| 10 | 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 |
|
| 5520 | 11 |
published by the Free Software Foundation. Oracle designates this |
| 10 | 12 |
particular file as subject to the "Classpath" exception as provided |
| 5520 | 13 |
by Oracle in the LICENSE file that accompanied this code. |
| 10 | 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 |
||
|
5568
8450cc6bc21c
6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents:
5520
diff
changeset
|
25 |
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
8450cc6bc21c
6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents:
5520
diff
changeset
|
26 |
or visit www.oracle.com if you need additional information or have any |
|
8450cc6bc21c
6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents:
5520
diff
changeset
|
27 |
questions. |
| 10 | 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> |