jdk8-mips64-public/langtools: src/share/classes/com/sun/mirror/overview.html@4b4e282a3146

     1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

     2 <html>

     3 <head>

     4 <!--

     6 Copyright 2004 Sun Microsystems, Inc.  All Rights Reserved.

     7 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     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.

    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).

    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.

    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>

    31 <body bgcolor="white">

    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.

    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.

    47 <h4> Characteristics of the API </h4>

    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.

    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.

    60 <p> The API does not provide direct support for generating new code.

    63 <h4> Declarations and Types </h4>

    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>.

    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>.

    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.

    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.

    96 <h4> Utilities and Tool Support </h4>

    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.

   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.

   108 @since 1.5

   110 </body>

   111 </html>

Mercurial > jdk8-mips64-public > langtools / file revision