1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
|
2 <html> |
|
3 <head> |
|
4 <!-- |
|
5 |
|
6 Copyright (c) 2004, Oracle and/or its affiliates. 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. Oracle designates this |
|
12 particular file as subject to the "Classpath" exception as provided |
|
13 by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
26 or visit www.oracle.com if you need additional information or have any |
|
27 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> |
|