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 an element logically has a origin other
143 * than {@link Origin#EXPLICIT EXPLICIT}, an implementation may
144 * not be able to reliably determine this status if the element is
145 * created from a class file due to limitations of the fidelity of
146 * the class file format in preserving information from source
147 * code.
148 *
149 * @implSpec The default implementation of this method returns
150 * {@link Origin#EXPLICIT EXPLICIT}.
151 *
152 * @param e the element being examined
153 * @return the origin of the given element
154 * @since 9
155 */
156 default Origin getOrigin(Element e) {
157 return Origin.EXPLICIT;
158 }
159
160 /**
161 * Returns the <em>origin</em> of the given annotation mirror.
162 *
163 * An annotation mirror is {@linkplain Origin#MANDATED mandated}
164 * if it is an implicitly declared <em>container annotation</em>
165 * used to hold repeated annotations of a repeatable annotation
166 * type.
167 *
168 * <p>Note that if an annotation mirror logically has a origin
169 * other than {@link Origin#EXPLICIT EXPLICIT}, an implementation
170 * may not be able to reliably determine this status if the
171 * annotation mirror is created from a class file due to
172 * limitations of the fidelity of the class file format in
173 * preserving information from source code.
174 *
175 * @implSpec The default implementation of this method returns
176 * {@link Origin#EXPLICIT EXPLICIT}.
177 *
178 * @param c the construct the annotation mirror modifies
179 * @param a the annotation mirror being examined
180 * @return the origin of the given annotation mirror
181 * @jls 9.6.3 Repeatable Annotation Types
182 * @jls 9.7.5 Multiple Annotations of the Same Type
183 * @since 9
184 */
185 default Origin getOrigin(AnnotatedConstruct c,
186 AnnotationMirror a) {
187 return Origin.EXPLICIT;
188 }
189
190 /**
191 * Returns the <em>origin</em> of the given module directive.
192 *
193 * <p>Note that an implementation may not be able to reliably
194 * determine the origin status of the directive if the directive
195 * is created from a class file due to limitations of the fidelity
196 * of the class file format in preserving information from source
197 * code.
198 *
199 * @implSpec The default implementation of this method returns
200 * {@link Origin#EXPLICIT EXPLICIT}.
201 *
202 * @param m the module of the directive
203 * @param directive the module directive being examined
204 * @return the origin of the given directive
205 * @since 9
206 */
207 default Origin getOrigin(ModuleElement m,
208 ModuleElement.Directive directive) {
209 return Origin.EXPLICIT;
210 }
211
212 /**
213 * The <em>origin</em> of an element or other language model
214 * item. The origin of an element or item models how a construct
215 * in a program is declared in the source code, explicitly,
216 * implicitly, etc.
217 *
218 * <p>Note that it is possible additional kinds of origin values
219 * will be added in future versions of the platform.
220 *
221 * @jls 13.1 The Form of a Binary
222 * @since 9
223 */
224 public enum Origin {
225 /**
226 * Describes a construct explicitly declared in source code.
227 */
228 EXPLICIT,
229
230 /**
231 * A mandated construct is one that is not explicitly declared
232 * in the source code, but whose presence is mandated by the
233 * specification. Such a construct is said to be implicitly
234 * declared.
235 *
236 * One example of a mandated element is a <em>default
237 * constructor</em> in a class that contains no explicit
238 * constructor declarations.
239 *
240 * Another example of a mandated construct is an implicitly
241 * declared <em>container annotation</em> used to hold
242 * multiple annotations of a repeatable annotation type.
243 *
244 * @jls 8.8.9 Default Constructor
245 * @jls 9.6.3 Repeatable Annotation Types
246 * @jls 9.7.5 Multiple Annotations of the Same Type
247 */
248 MANDATED,
249
250 /**
251 * A synthetic construct is one that is neither implicitly nor
252 * explicitly declared in the source code. Such a construct is
253 * typically a translation artifact created by a compiler.
254 */
255 SYNTHETIC;
256
257 /**
258 * Returns {@code true} for values corresponding to constructs
259 * that are implicitly or explicitly declared, {@code false}
260 * otherwise.
261 * @return {@code true} for {@link EXPLICIT} and {@link
262 * MANDATED}, {@code false} otherwise.
263 */
264 public boolean isDeclared() {
265 return this != SYNTHETIC;
266 }
267 }
268
269 /**
270 * Returns {@code true} if the executable element is a bridge
271 * method, {@code false} otherwise.
272 *
273 * @implSpec The default implementation of this method returns {@code false}.
274 *
275 * @param e the executable being examined
276 * @return {@code true} if the executable element is a bridge
277 * method, {@code false} otherwise
278 * @since 9
279 */
280 default boolean isBridge(ExecutableElement e) {
281 return false;
282 }
283
284 /**
285 * Returns the <i>binary name</i> of a type element.
286 *
287 * @param type the type element being examined
288 * @return the binary name
289 *
290 * @see TypeElement#getQualifiedName
291 * @jls 13.1 The Form of a Binary
292 */
293 Name getBinaryName(TypeElement type);
294
295
296 /**
297 * Returns the package of an element. The package of a package is
298 * itself.
299 *
300 * @param type the element being examined
301 * @return the package of an element
302 */
|