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 null, an empty set of package
89 * elements is returned; otherwise, a single-element set with the
90 * found package element is returned. If the set of modules is
91 * nonempty, the modules are iterated over and any non-null result
92 * of {@link #getPackageElement(ModuleElement, CharSequence)
93 * getPackageElement(module, name)} are accumulated into a
94 * set. The set is then returned.
95 *
96 * @param name the canonical name
97 * @return the package elements, or an empty set if no package with the name can be found
98 * @since 9
99 */
100 default Set<? extends PackageElement> getAllPackageElements(CharSequence name) {
101 Set<? extends ModuleElement> modules = getAllModuleElements();
102 if (modules.isEmpty()) {
103 PackageElement packageElt = getPackageElement(name);
104 return (packageElt != null) ?
105 Collections.singleton(packageElt):
106 Collections.emptySet();
107 } else {
108 Set<PackageElement> result = new LinkedHashSet<>(1); // Usually expect at most 1 result
109 for (ModuleElement module: modules) {
110 PackageElement packageElt = getPackageElement(module, name);
111 if (packageElt != null)
112 result.add(packageElt);
113 }
114 return Collections.unmodifiableSet(result);
115 }
116 }
117
118 /**
119 * Returns a type element given its canonical name if the type element is unique in the environment.
120 * If running with modules, all modules in the modules graph are searched for matching
121 * type elements.
122 *
123 * @param name the canonical name
124 * @return the named type element, or {@code null} if it cannot be uniquely found
125 */
126 TypeElement getTypeElement(CharSequence name);
127
128 /**
129 * Returns a type element given its canonical name, as seen from the given module.
130 *
131 * @implSpec The default implementation of this method returns
132 * {@code null}.
133 *
134 * @param name the canonical name
135 * @param module module relative to which the lookup should happen
136 * @return the named type element, or {@code null} if it cannot be found
137 * @since 9
138 */
139 default TypeElement getTypeElement(ModuleElement module, CharSequence name) {
140 return null;
141 }
142
143 /**
144 * Returns all type elements with the given canonical name.
145 *
146 * There may be more than one type element with the same canonical
147 * name if the type elements are in different modules.
148 *
149 * @implSpec The default implementation of this method calls
150 * {@link #getAllModuleElements() getAllModuleElements} and stores
151 * the result. If the set of modules is empty, {@link
152 * #getTypeElement(CharSequence) getTypeElement(name)} is called
153 * passing through the name argument. If {@code
154 * getTypeElement(name)} is null, an empty set of type elements is
155 * returned; otherwise, a single-element set with the found type
156 * element is returned. If the set of modules is nonempty, the
157 * modules are iterated over and any non-null result of {@link
158 * #getTypeElement(ModuleElement, CharSequence)
159 * getTypeElement(module, name)} are accumulated into a set. The
160 * set is then returned.
161 *
162 * @param name the canonical name
163 * @return the type elements, or an empty set if no type with the name can be found
164 * @since 9
165 */
166 default Set<? extends TypeElement> getAllTypeElements(CharSequence name) {
167 Set<? extends ModuleElement> modules = getAllModuleElements();
168 if (modules.isEmpty()) {
169 TypeElement typeElt = getTypeElement(name);
170 return (typeElt != null) ?
171 Collections.singleton(typeElt):
172 Collections.emptySet();
173 } else {
174 Set<TypeElement> result = new LinkedHashSet<>(1); // Usually expect at most 1 result
175 for (ModuleElement module: modules) {
176 TypeElement typeElt = getTypeElement(module, name);
177 if (typeElt != null)
178 result.add(typeElt);
179 }
180 return Collections.unmodifiableSet(result);
181 }
182 }
183
184 /**
185 * Returns a module element given its fully qualified name.
186 * If the named module cannot be found, null is returned. One situation where a module
187 * cannot be found is if the environment does not include modules, such as
188 * an annotation processing environment configured for
189 * a {@linkplain
190 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
191 * source version} without modules.
192 *
193 * @implSpec The default implementation of this method returns
194 * {@code null}.
195 *
196 * @param name the name
197 * @return the named module element, or {@code null} if it cannot be found
198 * @since 9
199 * @spec JPMS
200 */
201 default ModuleElement getModuleElement(CharSequence name) {
202 return null;
203 }
204
205 /**
206 * Returns all module elements in the current environment.
207 *
208 * If no modules are present, an empty set is returned. One
209 * situation where no modules are present occurs when the
210 * environment does not include modules, such as an annotation
211 * processing environment configured for a {@linkplain
212 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
213 * source version} without modules.
214 *
215 * @implSpec The default implementation of this method returns
216 * an empty set.
217 *
218 * @return the known module elements, or an empty set if there are no modules
219 * @since 9
220 */
221 default Set<? extends ModuleElement> getAllModuleElements() {
222 return Collections.emptySet();
223 }
224
225 /**
226 * Returns the values of an annotation's elements, including defaults.
227 *
228 * @see AnnotationMirror#getElementValues()
229 * @param a annotation to examine
230 * @return the values of the annotation's elements, including defaults
231 */
232 Map<? extends ExecutableElement, ? extends AnnotationValue>
233 getElementValuesWithDefaults(AnnotationMirror a);
234
235 /**
236 * Returns the text of the documentation ("Javadoc")
237 * comment of an element.
238 *
239 * <p> A documentation comment of an element is a comment that
240 * begins with "{@code /**}" , ends with a separate
241 * "<code>*/</code>", and immediately precedes the element,
242 * ignoring white space. Therefore, a documentation comment
|