KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > lang > model > element > package-info


1 /*
2  * @(#)package-info.java 1.6 06/08/28
3  *
4  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 /**
9  * Interfaces used to model elements of the Java programming language.
10  *
11  * <p>When used in the context of annotation processing, an accurate
12  * model of the element being represented must be returned. As this
13  * is a language model, the source code provides the fiducial
14  * (reference) representation of the construct in question rather than
15  * a representation in an executable output like a class file.
16  * Executable output may serve as the basis for creating a modeling
17  * element. However, the process of translating source code to
18  * executable output may not permit recovering some aspects of the
19  * source code representation. For example, annotations with
20  * {@linkplain java.lang.annotation.RetentionPolicy#SOURCE source}
21  * {@linkplain java.lang.annotation.Retention retention} cannot be
22  * recovered from class files and class files might not be able to
23  * provide source position information. The {@linkplain
24  * javax.lang.model.element.Modifier modifiers} on an element may
25  * differ in some cases including
26  *
27  * <ul>
28  * <li> {@code strictfp} on a class or interface
29  * <li> {@code final} on a parameter
30  * <li> {@code protected}, {@code private}, and {@code static} on classes and interfaces
31  * </ul>
32  *
33  * Additionally, synthetic constructs in a class file, such as
34  * accessor methods used in implementing nested classes and bridge
35  * methods used in implementing covariant returns, are translation
36  * artifacts outside of this model.
37  *
38  * <p>During annotation processing, operating on incomplete or
39  * erroneous programs is necessary; however, there are fewer
40  * guarantees about the nature of the resulting model. If the source
41  * code is not syntactically well-formed, a model may or may not be
42  * provided as a quality of implementation issue. If a program is
43  * syntactically valid but erroneous in some other fashion, the
44  * returned model must have no less information than if all the method
45  * bodies in the program were replaced by {@code "throw new
46  * RuntimeException();"}. If a program refers to a missing type XYZ,
47  * the returned model must contain no less information than if the
48  * declaration of type XYZ were assumed to be {@code "class XYZ {}"},
49  * {@code "interface XYZ {}"}, {@code "enum XYZ {}"}, or {@code
50  * "@interface XYZ {}"}. If a program refers to a missing type {@code
51  * XYZ<K1, ... ,Kn>}, the returned model must contain no less
52  * information than if the declaration of XYZ were assumed to be
53  * {@code "class XYZ<T1, ... ,Tn> {}"} or {@code "interface XYZ<T1,
54  * ... ,Tn> {}"}
55  *
56  * <p> Unless otherwise specified in a particular implementation, the
57  * collections returned by methods in this package should be expected
58  * to be unmodifiable by the caller and unsafe for concurrent access.
59  *
60  * <p> Unless otherwise specified, methods in this package will throw
61  * a {@code NullPointerException} if given a {@code null} argument.
62  *
63  * @author Joseph D. Darcy
64  * @author Scott Seligman
65  * @author Peter von der Ah&eacute;
66  * @version 1.6 06/08/28
67  * @since 1.6
68  */
69 package javax.lang.model.element;
70
Popular Tags