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.element.*;
33
34
35 /**
36 * Utility methods for operating on program elements.
37 *
38 * <p><b>Compatibility Note:</b> Methods may be added to this interface
39 * in future releases of the platform.
40 *
41 * @author Joseph D. Darcy
42 * @author Scott Seligman
43 * @author Peter von der Ahé
44 * @see javax.annotation.processing.ProcessingEnvironment#getElementUtils
45 * @since 1.6
46 */
47 public interface Elements {
48
49 /**
50 * Returns a package given its fully qualified name.
51 *
117 * leading white space characters are discarded as are any
118 * consecutive "{@code *}" characters appearing after the white
119 * space or starting the line. The processed lines are then
120 * concatenated together (including line terminators) and
121 * returned.
122 *
123 * @param e the element being examined
124 * @return the documentation comment of the element, or {@code null}
125 * if there is none
126 * @jls 3.6 White Space
127 */
128 String getDocComment(Element e);
129
130 /**
131 * Returns {@code true} if the element is deprecated, {@code false} otherwise.
132 *
133 * @param e the element being examined
134 * @return {@code true} if the element is deprecated, {@code false} otherwise
135 */
136 boolean isDeprecated(Element e);
137
138 /**
139 * Returns the <i>binary name</i> of a type element.
140 *
141 * @param type the type element being examined
142 * @return the binary name
143 *
144 * @see TypeElement#getQualifiedName
145 * @jls 13.1 The Form of a Binary
146 */
147 Name getBinaryName(TypeElement type);
148
149
150 /**
151 * Returns the package of an element. The package of a package is
152 * itself.
153 *
154 * @param type the element being examined
155 * @return the package of an element
156 */
|
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 /**
51 * Returns a package given its fully qualified name.
52 *
118 * leading white space characters are discarded as are any
119 * consecutive "{@code *}" characters appearing after the white
120 * space or starting the line. The processed lines are then
121 * concatenated together (including line terminators) and
122 * returned.
123 *
124 * @param e the element being examined
125 * @return the documentation comment of the element, or {@code null}
126 * if there is none
127 * @jls 3.6 White Space
128 */
129 String getDocComment(Element e);
130
131 /**
132 * Returns {@code true} if the element is deprecated, {@code false} otherwise.
133 *
134 * @param e the element being examined
135 * @return {@code true} if the element is deprecated, {@code false} otherwise
136 */
137 boolean isDeprecated(Element e);
138
139 /**
140 * Returns the <em>origin</em> of the given element.
141 *
142 * <p>Note that if this method returns {@link Origin#EXPLICIT
143 * EXPLICIT} and the element was created from a class file, then
144 * the element may not, in fact, correspond to an explicitly
145 * declared construct in source code. This is due to limitations
146 * of the fidelity of the class file format in preserving
147 * information from source code. For example, at least some
148 * versions of the class file format do not preserve whether a
149 * constructor was explicitly declared by the programmer or was
150 * implicitly declared as the <em>default constructor</em>.
151 *
152 * @implSpec The default implementation of this method returns
153 * {@link Origin#EXPLICIT EXPLICIT}.
154 *
155 * @param e the element being examined
156 * @return the origin of the given element
157 * @since 9
158 */
159 default Origin getOrigin(Element e) {
160 return Origin.EXPLICIT;
161 }
162
163 /**
164 * Returns the <em>origin</em> of the given annotation mirror.
165 *
166 * An annotation mirror is {@linkplain Origin#MANDATED mandated}
167 * if it is an implicitly declared <em>container annotation</em>
168 * used to hold repeated annotations of a repeatable annotation
169 * type.
170 *
171 * <p>Note that if this method returns {@link Origin#EXPLICIT
172 * EXPLICIT} and the annotation mirror was created from a class
173 * file, then the element may not, in fact, correspond to an
174 * explicitly declared construct in source code. This is due to
175 * limitations of the fidelity of the class file format in
176 * preserving information from source code. For example, at least
177 * some versions of the class file format do not preserve whether
178 * an annotation was explicitly declared by the programmer or was
179 * implicitly declared as a <em>container annotation</em>.
180 *
181 * @implSpec The default implementation of this method returns
182 * {@link Origin#EXPLICIT EXPLICIT}.
183 *
184 * @param c the construct the annotation mirror modifies
185 * @param a the annotation mirror being examined
186 * @return the origin of the given annotation mirror
187 * @jls 9.6.3 Repeatable Annotation Types
188 * @jls 9.7.5 Multiple Annotations of the Same Type
189 * @since 9
190 */
191 default Origin getOrigin(AnnotatedConstruct c,
192 AnnotationMirror a) {
193 return Origin.EXPLICIT;
194 }
195
196 /**
197 * Returns the <em>origin</em> of the given module directive.
198 *
199 * <p>Note that if this method returns {@link Origin#EXPLICIT
200 * EXPLICIT} and the module directive was created from a class
201 * file, then the module directive may not, in fact, correspond to
202 * an explicitly declared construct in source code. This is due to
203 * limitations of the fidelity of the class file format in
204 * preserving information from source code. For example, at least
205 * some versions of the class file format do not preserve whether
206 * a {@code uses} directive was explicitly declared by the
207 * programmer or was added as a synthetic construct.
208 *
209 * <p>Note that an implementation may not be able to reliably
210 * determine the origin status of the directive if the directive
211 * is created from a class file due to limitations of the fidelity
212 * of the class file format in preserving information from source
213 * code.
214 *
215 * @implSpec The default implementation of this method returns
216 * {@link Origin#EXPLICIT EXPLICIT}.
217 *
218 * @param m the module of the directive
219 * @param directive the module directive being examined
220 * @return the origin of the given directive
221 * @since 9
222 */
223 default Origin getOrigin(ModuleElement m,
224 ModuleElement.Directive directive) {
225 return Origin.EXPLICIT;
226 }
227
228 /**
229 * The <em>origin</em> of an element or other language model
230 * item. The origin of an element or item models how a construct
231 * in a program is declared in the source code, explicitly,
232 * implicitly, etc.
233 *
234 * <p>Note that it is possible additional kinds of origin values
235 * will be added in future versions of the platform.
236 *
237 * @jls 13.1 The Form of a Binary
238 * @since 9
239 */
240 public enum Origin {
241 /**
242 * Describes a construct explicitly declared in source code.
243 */
244 EXPLICIT,
245
246 /**
247 * A mandated construct is one that is not explicitly declared
248 * in the source code, but whose presence is mandated by the
249 * specification. Such a construct is said to be implicitly
250 * declared.
251 *
252 * One example of a mandated element is a <em>default
253 * constructor</em> in a class that contains no explicit
254 * constructor declarations.
255 *
256 * Another example of a mandated construct is an implicitly
257 * declared <em>container annotation</em> used to hold
258 * multiple annotations of a repeatable annotation type.
259 *
260 * @jls 8.8.9 Default Constructor
261 * @jls 9.6.3 Repeatable Annotation Types
262 * @jls 9.7.5 Multiple Annotations of the Same Type
263 */
264 MANDATED,
265
266 /**
267 * A synthetic construct is one that is neither implicitly nor
268 * explicitly declared in the source code. Such a construct is
269 * typically a translation artifact created by a compiler.
270 */
271 SYNTHETIC;
272
273 /**
274 * Returns {@code true} for values corresponding to constructs
275 * that are implicitly or explicitly declared, {@code false}
276 * otherwise.
277 * @return {@code true} for {@link EXPLICIT} and {@link
278 * MANDATED}, {@code false} otherwise.
279 */
280 public boolean isDeclared() {
281 return this != SYNTHETIC;
282 }
283 }
284
285 /**
286 * Returns {@code true} if the executable element is a bridge
287 * method, {@code false} otherwise.
288 *
289 * @implSpec The default implementation of this method returns {@code false}.
290 *
291 * @param e the executable being examined
292 * @return {@code true} if the executable element is a bridge
293 * method, {@code false} otherwise
294 * @since 9
295 */
296 default boolean isBridge(ExecutableElement e) {
297 return false;
298 }
299
300 /**
301 * Returns the <i>binary name</i> of a type element.
302 *
303 * @param type the type element being examined
304 * @return the binary name
305 *
306 * @see TypeElement#getQualifiedName
307 * @jls 13.1 The Form of a Binary
308 */
309 Name getBinaryName(TypeElement type);
310
311
312 /**
313 * Returns the package of an element. The package of a package is
314 * itself.
315 *
316 * @param type the element being examined
317 * @return the package of an element
318 */
|