--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/src/share/classes/com/sun/mirror/overview.html Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,111 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<!--
+
+Copyright 2004 Sun Microsystems, Inc. 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. Sun designates this
+particular file as subject to the "Classpath" exception as provided
+by Sun 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>