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 base annotations of a repeatable
166 * annotation 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 if a directive logically has a origin other than
194 * {@link Origin#EXPLICIT EXPLICIT}, an implementation may not be
195 * able to reliably determine this status if the directive is
196 * created from a class file due to limitations of the fidelity of
197 * the class file format in preserving information from source
198 * code.
199 *
200 * @implSpec The default implementation of this method returns
201 * {@link Origin#EXPLICIT EXPLICIT}.
202 *
203 * @param m the module of the directive
204 * @param directive the module directive being examined
205 * @return the origin of the given directive
206 * @since 9
207 */
208 default Origin getOrigin(ModuleElement m,
209 ModuleElement.Directive directive) {
210 return Origin.EXPLICIT;
211 }
212
213 /**
214 * The <em>origin</em> of a construct. The origin of a construct
215 * concerns the consistency between how a construct is declared in
216 * source code (explicitly, implicitly, or not at all) compared to
217 * how the construct is represented in this model.
218 *
219 * <p>Note that it is possible additional kinds of origin values
220 * will be added in future versions of the platform.
221 *
222 * @jls 13.1 The Form of a Binary
223 * @since 9
224 */
225 enum Origin {
226 /**
227 * Describes a construct explicitly declared in source code.
228 */
229 EXPLICIT,
230
231 /**
232 * A mandated construct is one that is not explicitly declared
233 * in the source code, but whose presence is mandated by the
234 * specification. Such a construct is said to be implicitly
235 * declared.
236 *
237 * One example of a mandated element is a <em>default
238 * constructor</em> in a class that contains no explicit
239 * constructor declarations.
240 *
241 * Another example of a mandated construct is an implicitly
242 * declared <em>container annotation</em> used to hold
243 * multiple annotations of a repeatable annotation type.
244 *
245 * @jls 8.8.9 Default Constructor
246 * @jls 9.6.3 Repeatable Annotation Types
247 * @jls 9.7.5 Multiple Annotations of the Same Type
248 */
249 MANDATED,
250
251 /**
252 * A synthetic construct is one that is neither implicitly nor
253 * explicitly declared in the source code. Such a construct is
254 * typically a translation artifact created by a compiler.
255 */
256 SYNTHETIC;
257
258 /**
259 * Returns {@code true} for values corresponding to constructs
260 * that are implicitly or explicitly declared, {@code false}
261 * otherwise.
262 * @return {@code true} for {@link EXPLICIT} and {@link
263 * MANDATED}, {@code false} otherwise.
264 */
265 public boolean isDeclared() {
266 return this != SYNTHETIC;
267 }
268 }
269
270 /**
271 * Returns {@code true} if the executable element is a bridge
272 * method, {@code false} otherwise.
273 *
274 * @implSpec The default implementation of this method returns {@code false}.
275 *
276 * @param e the executable being examined
277 * @return {@code true} if the executable element is a bridge
278 * method, {@code false} otherwise
279 * @since 9
280 */
281 default boolean isBridge(ExecutableElement e) {
282 return false;
283 }
284
285 /**
286 * Returns the <i>binary name</i> of a type element.
287 *
288 * @param type the type element being examined
289 * @return the binary name
290 *
291 * @see TypeElement#getQualifiedName
292 * @jls 13.1 The Form of a Binary
293 */
294 Name getBinaryName(TypeElement type);
295
296
297 /**
298 * Returns the package of an element. The package of a package is
299 * itself.
300 *
301 * @param type the element being examined
302 * @return the package of an element
303 */
|