Elements


1   /*
2    * @(#)Elements.java    1.11 06/08/16
3    *
4    * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.lang.model.util;
9   
10  
11  import java.util.List  ;
12  import java.util.Map  ;
13  
14  import javax.lang.model.element.*;
15  import javax.lang.model.type.*;
16  
17  
18  /**
19   * Utility methods for operating on program elements.
20   *
21   * <p><b>Compatibility Note:</b> Methods may be added to this interface
22   * in future releases of the platform.
23   *
24   * @author Joseph D. Darcy
25   * @author Scott Seligman
26   * @author Peter von der Ah&eacute;
27   * @version 1.11 06/08/16
28   * @see javax.annotation.processing.ProcessingEnvironment#getElementUtils
29   * @since 1.6
30   */
31  public interface Elements {
32  
33      /**
34       * Returns a package given its fully qualified name.
35       *
36       * @param name  fully qualified package name, or "" for an unnamed package
37       * @return the named package, or {@code null} if it cannot be found
38       */
39      PackageElement getPackageElement(CharSequence   name);
40  
41      /**
42       * Returns a type element given its canonical name.
43       *
44       * @param name  the canonical name
45       * @return the named type element, or {@code null} if it cannot be found
46       */
47      TypeElement getTypeElement(CharSequence   name);
48  
49      /**
50       * Returns the values of an annotation's elements, including defaults.
51       * 
52       * @see AnnotationMirror#getElementValues()
53       * @param a  annotation to examine
54       * @return the values of the annotation's elements, including defaults
55       */
56      Map  <? extends ExecutableElement, ? extends AnnotationValue>
57          getElementValuesWithDefaults(AnnotationMirror a);
58  
59      /**
60       * Returns the text of the documentation (&quot;Javadoc&quot;)
61       * comment of an element.
62       *
63       * @param e  the element being examined
64       * @return the documentation comment of the element, or {@code null}
65       *      if there is none
66       */
67      String   getDocComment(Element e);
68  
69      /**
70       * Returns {@code true} if the element is deprecated, {@code false} otherwise.
71       *
72       * @param e  the element being examined
73       * @return {@code true} if the element is deprecated, {@code false} otherwise
74       */
75      boolean isDeprecated(Element e);
76  
77      /**
78       * Returns the <i>binary name</i> of a type element.
79       *
80       * @param type  the type element being examined
81       * @return the binary name
82       *
83       * @see TypeElement#getQualifiedName
84       * @jls3 13.1 The Form of a Binary
85       */
86      Name getBinaryName(TypeElement type);
87  
88  
89      /**
90       * Returns the package of an element.  The package of a package is
91       * itself.
92       *
93       * @param type the element being examined
94       * @return the package of an element
95       */
96      PackageElement getPackageOf(Element type);
97  
98      /**
99       * Returns all members of a type element, whether inherited or
100      * declared directly.  For a class the result also includes its
101      * constructors, but not local or anonymous classes.
102      *
103      * <p>Note that elements of certain kinds can be isolated using
104      * methods in {@link ElementFilter}.
105      *
106      * @param type  the type being examined
107      * @return all members of the type
108      * @see Element#getEnclosedElements
109      */
110     List  <? extends Element> getAllMembers(TypeElement type);
111 
112     /**
113      * Returns all annotations of an element, whether
114      * inherited or directly present.
115      *
116      * @param e  the element being examined
117      * @return all annotations of the element
118      * @see Element#getAnnotationMirrors
119      */
120     List  <? extends AnnotationMirror> getAllAnnotationMirrors(Element e);
121 
122     /**
123      * Tests whether one type, method, or field hides another.
124      *
125      * @param hider   the first element
126      * @param hidden  the second element
127      * @return {@code true} if and only if the first element hides
128      *      the second
129      */
130     boolean hides(Element hider, Element hidden);
131 
132     /**
133      * Tests whether one method, as a member of a given type,
134      * overrides another method.
135      * When a non-abstract method overrides an abstract one, the
136      * former is also said to <i>implement</i> the latter.
137      *
138      * <p> In the simplest and most typical usage, the value of the
139      * {@code type} parameter will simply be the class or interface
140      * directly enclosing {@code overrider} (the possibly-overriding
141      * method).  For example, suppose {@code m1} represents the method
142      * {@code String.hashCode} and {@code m2} represents {@code
143      * Object.hashCode}.  We can then ask whether {@code m1} overrides
144      * {@code m2} within the class {@code String} (it does):
145      *
146      * <blockquote>
147      * {@code assert elements.overrides(m1, m2,
148      *          elements.getTypeElement("java.lang.String")); }
149      * </blockquote>
150      * 
151      * A more interesting case can be illustrated by the following example
152      * in which a method in type {@code A} does not override a
153      * like-named method in type {@code B}:
154      *
155      * <blockquote>
156      * {@code class A { public void m() {} } }<br>
157      * {@code interface B { void m(); } }<br>
158      * ...<br>
159      * {@code m1 = ...;  // A.m }<br>
160      * {@code m2 = ...;  // B.m }<br>
161      * {@code assert ! elements.overrides(m1, m2,
162      *          elements.getTypeElement("A")); }
163      * </blockquote>
164      * 
165      * When viewed as a member of a third type {@code C}, however, 
166      * the method in {@code A} does override the one in {@code B}:
167      *
168      * <blockquote>
169      * {@code class C extends A implements B {} }<br>
170      * ...<br>
171      * {@code assert elements.overrides(m1, m2,
172      *          elements.getTypeElement("C")); }
173      * </blockquote>
174      *
175      * @param overrider  the first method, possible overrider
176      * @param overridden  the second method, possibly being overridden
177      * @param type   the type of which the first method is a member
178      * @return {@code true} if and only if the first method overrides
179      *      the second
180      * @jls3 8.4.8 Inheritance, Overriding, and Hiding
181      * @jls3 9.4.1 Inheritance and Overriding
182      */
183     boolean overrides(ExecutableElement overrider, ExecutableElement overridden,
184               TypeElement type);
185 
186     /**
187      * Returns the text of a <i>constant expression</i> representing a
188      * primitive value or a string.
189      * The text returned is in a form suitable for representing the value
190      * in source code.
191      *
192      * @param value  a primitive value or string
193      * @return the text of a constant expression
194      * @throws IllegalArgumentException if the argument is not a primitive
195      *      value or string
196      *
197      * @see VariableElement#getConstantValue()
198      */
199     String   getConstantExpression(Object   value);
200 
201     /**
202      * Prints a representation of the elements to the given writer in
203      * the specified order.  The main purpose of this method is for
204      * diagnostics.  The exact format of the output is <em>not</em>
205      * specified and is subject to change.
206      *
207      * @param w the writer to print the output to
208      * @param elements the elements to print
209      */
210     void printElements(java.io.Writer   w, Element... elements);
211 
212     /**
213      * Return a name with the same sequence of characters as the
214      * argument.
215      *
216      * @param cs the character sequence to return as a name
217      */
218     Name getName(CharSequence   cs);
219 }
220
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags