8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.lang.model.util;
27
28
29 import java.util.List;
30 import java.util.Map;
31
32 import javax.lang.model.AnnotatedConstruct;
33 import javax.lang.model.element.*;
34
35
36 /**
37 * Utility methods for operating on program elements.
38 *
39 * <p><b>Compatibility Note:</b> Methods may be added to this interface
40 * in future releases of the platform.
41 *
42 * @author Joseph D. Darcy
43 * @author Scott Seligman
44 * @author Peter von der Ahé
45 * @see javax.annotation.processing.ProcessingEnvironment#getElementUtils
46 * @since 1.6
47 */
48 public interface Elements {
49
50 /**
55 * @return the specified package, or {@code null} if it cannot be uniquely found
56 */
57 PackageElement getPackageElement(CharSequence name);
58
59 /**
60 * Returns a package given its fully qualified name, as seen from the given module.
61 *
62 * @implSpec The default implementation of this method returns
63 * {@code null}.
64 *
65 * @param name fully qualified package name, or an empty string for an unnamed package
66 * @param module module relative to which the lookup should happen
67 * @return the specified package, or {@code null} if it cannot be found
68 * @since 9
69 */
70 default PackageElement getPackageElement(ModuleElement module, CharSequence name) {
71 return null;
72 }
73
74 /**
75 * Returns a type element given its canonical name if the type element is unique in the environment.
76 * If running with modules, all modules in the modules graph are searched for matching
77 * type elements.
78 *
79 * @param name the canonical name
80 * @return the named type element, or {@code null} if it cannot be uniquely found
81 */
82 TypeElement getTypeElement(CharSequence name);
83
84 /**
85 * Returns a type element given its canonical name, as seen from the given module.
86 *
87 * @implSpec The default implementation of this method returns
88 * {@code null}.
89 *
90 * @param name the canonical name
91 * @param module module relative to which the lookup should happen
92 * @return the named type element, or {@code null} if it cannot be found
93 * @since 9
94 */
95 default TypeElement getTypeElement(ModuleElement module, CharSequence name) {
96 return null;
97 }
98
99 /**
100 * Returns a module element given its fully qualified name.
101 * If the named module cannot be found, null is returned. One situation where a module
102 * cannot be found is if the environment does not include modules, such as
103 * an annotation processing environment configured for
104 * a {@linkplain
105 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
106 * source version} without modules.
107 *
108 * @implSpec The default implementation of this method returns
109 * {@code null}.
110 *
111 * @param name the name
112 * @return the named module element, or {@code null} if it cannot be found
113 * @since 9
114 * @spec JPMS
115 */
116 default ModuleElement getModuleElement(CharSequence name) {
117 return null;
118 }
119
120 /**
121 * Returns the values of an annotation's elements, including defaults.
122 *
123 * @see AnnotationMirror#getElementValues()
124 * @param a annotation to examine
125 * @return the values of the annotation's elements, including defaults
126 */
127 Map<? extends ExecutableElement, ? extends AnnotationValue>
128 getElementValuesWithDefaults(AnnotationMirror a);
129
130 /**
131 * Returns the text of the documentation ("Javadoc")
132 * comment of an element.
133 *
134 * <p> A documentation comment of an element is a comment that
135 * begins with "{@code /**}" , ends with a separate
136 * "<code>*/</code>", and immediately precedes the element,
137 * ignoring white space. Therefore, a documentation comment
|
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.lang.model.util;
27
28 import java.util.ArrayList;
29 import java.util.Collections;
30 import java.util.List;
31 import java.util.Map;
32 import java.util.Set;
33 import java.util.LinkedHashSet;
34
35 import javax.lang.model.AnnotatedConstruct;
36 import javax.lang.model.element.*;
37
38
39 /**
40 * Utility methods for operating on program elements.
41 *
42 * <p><b>Compatibility Note:</b> Methods may be added to this interface
43 * in future releases of the platform.
44 *
45 * @author Joseph D. Darcy
46 * @author Scott Seligman
47 * @author Peter von der Ahé
48 * @see javax.annotation.processing.ProcessingEnvironment#getElementUtils
49 * @since 1.6
50 */
51 public interface Elements {
52
53 /**
58 * @return the specified package, or {@code null} if it cannot be uniquely found
59 */
60 PackageElement getPackageElement(CharSequence name);
61
62 /**
63 * Returns a package given its fully qualified name, as seen from the given module.
64 *
65 * @implSpec The default implementation of this method returns
66 * {@code null}.
67 *
68 * @param name fully qualified package name, or an empty string for an unnamed package
69 * @param module module relative to which the lookup should happen
70 * @return the specified package, or {@code null} if it cannot be found
71 * @since 9
72 */
73 default PackageElement getPackageElement(ModuleElement module, CharSequence name) {
74 return null;
75 }
76
77 /**
78 * Returns all package elements with the given canonical name.
79 *
80 * There may be more than one package element with the same canonical
81 * name if the package elements are in different modules.
82 *
83 * @implSpec The default implementation of this method calls
84 * {@link #getAllModuleElements() getAllModuleElements} and stores
85 * the result. If the set of modules is empty, {@link
86 * #getPackageElement(CharSequence) getPackageElement(name)} is
87 * called passing through the name argument. If {@code
88 * getPackageElement(name)} is {@code null}, an empty set of
89 * package elements is returned; otherwise, a single-element set
90 * with the found package element is returned. If the set of
91 * modules is nonempty, the modules are iterated over and any
92 * non-{@code null} result of {@link
93 * #getPackageElement(ModuleElement, CharSequence)
94 * getPackageElement(module, name)} are accumulated into a
95 * set. The set is then returned.
96 *
97 * @param name the canonical name
98 * @return the package elements, or an empty set if no package with the name can be found
99 * @since 9
100 */
101 default Set<? extends PackageElement> getAllPackageElements(CharSequence name) {
102 Set<? extends ModuleElement> modules = getAllModuleElements();
103 if (modules.isEmpty()) {
104 PackageElement packageElt = getPackageElement(name);
105 return (packageElt != null) ?
106 Collections.singleton(packageElt):
107 Collections.emptySet();
108 } else {
109 Set<PackageElement> result = new LinkedHashSet<>(1); // Usually expect at most 1 result
110 for (ModuleElement module: modules) {
111 PackageElement packageElt = getPackageElement(module, name);
112 if (packageElt != null)
113 result.add(packageElt);
114 }
115 return Collections.unmodifiableSet(result);
116 }
117 }
118
119 /**
120 * Returns a type element given its canonical name if the type element is unique in the environment.
121 * If running with modules, all modules in the modules graph are searched for matching
122 * type elements.
123 *
124 * @param name the canonical name
125 * @return the named type element, or {@code null} if it cannot be uniquely found
126 */
127 TypeElement getTypeElement(CharSequence name);
128
129 /**
130 * Returns a type element given its canonical name, as seen from the given module.
131 *
132 * @implSpec The default implementation of this method returns
133 * {@code null}.
134 *
135 * @param name the canonical name
136 * @param module module relative to which the lookup should happen
137 * @return the named type element, or {@code null} if it cannot be found
138 * @since 9
139 */
140 default TypeElement getTypeElement(ModuleElement module, CharSequence name) {
141 return null;
142 }
143
144 /**
145 * Returns all type elements with the given canonical name.
146 *
147 * There may be more than one type element with the same canonical
148 * name if the type elements are in different modules.
149 *
150 * @implSpec The default implementation of this method calls
151 * {@link #getAllModuleElements() getAllModuleElements} and stores
152 * the result. If the set of modules is empty, {@link
153 * #getTypeElement(CharSequence) getTypeElement(name)} is called
154 * passing through the name argument. If {@code
155 * getTypeElement(name)} is {@code null}, an empty set of type
156 * elements is returned; otherwise, a single-element set with the
157 * found type element is returned. If the set of modules is
158 * nonempty, the modules are iterated over and any non-{@code
159 * null} result of {@link #getTypeElement(ModuleElement,
160 * CharSequence) getTypeElement(module, name)} are accumulated
161 * into a set. The set is then returned.
162 *
163 * @param name the canonical name
164 * @return the type elements, or an empty set if no type with the name can be found
165 * @since 9
166 */
167 default Set<? extends TypeElement> getAllTypeElements(CharSequence name) {
168 Set<? extends ModuleElement> modules = getAllModuleElements();
169 if (modules.isEmpty()) {
170 TypeElement typeElt = getTypeElement(name);
171 return (typeElt != null) ?
172 Collections.singleton(typeElt):
173 Collections.emptySet();
174 } else {
175 Set<TypeElement> result = new LinkedHashSet<>(1); // Usually expect at most 1 result
176 for (ModuleElement module: modules) {
177 TypeElement typeElt = getTypeElement(module, name);
178 if (typeElt != null)
179 result.add(typeElt);
180 }
181 return Collections.unmodifiableSet(result);
182 }
183 }
184
185 /**
186 * Returns a module element given its fully qualified name.
187 *
188 * If the named module cannot be found, {@code null} is
189 * returned. One situation where a module cannot be found is if
190 * the environment does not include modules, such as an annotation
191 * processing environment configured for a {@linkplain
192 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
193 * source version} without modules.
194 *
195 * @implSpec The default implementation of this method returns
196 * {@code null}.
197 *
198 * @param name the name
199 * @return the named module element, or {@code null} if it cannot be found
200 * @since 9
201 * @spec JPMS
202 */
203 default ModuleElement getModuleElement(CharSequence name) {
204 return null;
205 }
206
207 /**
208 * Returns all module elements in the current environment.
209 *
210 * If no modules are present, an empty set is returned. One
211 * situation where no modules are present occurs when the
212 * environment does not include modules, such as an annotation
213 * processing environment configured for a {@linkplain
214 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
215 * source version} without modules.
216 *
217 * @implSpec The default implementation of this method returns
218 * an empty set.
219 *
220 * @return the known module elements, or an empty set if there are no modules
221 * @since 9
222 */
223 default Set<? extends ModuleElement> getAllModuleElements() {
224 return Collections.emptySet();
225 }
226
227 /**
228 * Returns the values of an annotation's elements, including defaults.
229 *
230 * @see AnnotationMirror#getElementValues()
231 * @param a annotation to examine
232 * @return the values of the annotation's elements, including defaults
233 */
234 Map<? extends ExecutableElement, ? extends AnnotationValue>
235 getElementValuesWithDefaults(AnnotationMirror a);
236
237 /**
238 * Returns the text of the documentation ("Javadoc")
239 * comment of an element.
240 *
241 * <p> A documentation comment of an element is a comment that
242 * begins with "{@code /**}" , ends with a separate
243 * "<code>*/</code>", and immediately precedes the element,
244 * ignoring white space. Therefore, a documentation comment
|