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>naturalness</em> of the given element.
141 *
142 * @implSpec The default implementation of this method returns
143 * {@link Naturalness#NATURAL NATURAL}.
144 *
145 * @param e the element being examined
146 * @return the naturalness of the given element
147 * @since 9
148 */
149 default Naturalness getNaturalness(Element e) {
150 return Naturalness.NATURAL;
151 }
152
153 /**
154 * Returns the <em>naturalness</em> of the given annotation mirror.
155 *
156 * One example of a mandated construct is the
157 * implicitly declared <em>container annotation</em> used to hold
158 * repeated base annotations of a repeatable annotation type.
159 *
160 * @implSpec The default implementation of this method returns
161 * {@link Naturalness#NATURAL NATURAL}.
162 *
163 * @param c the construct the annotation mirror modifies
164 * @param a the annotation mirror being examined
165 * @return the naturalness of the given annotation mirror
166 * @jls 9.6.3. Repeatable Annotation Types
167 * @jls 9.7.5 Multiple Annotations of the Same Type
168 * @since 9
169 */
170 default Naturalness getNaturalness(AnnotatedConstruct c, AnnotationMirror a) {
171 return Naturalness.NATURAL;
172 }
173
174 /**
175 * Returns the <em>naturalness</em> of the given module directive.
176 *
177 * @implSpec The default implementation of this method returns
178 * {@link Naturalness#NATURAL NATURAL}.
179 *
180 * @param m the module of the directive
181 * @param directive the module directive being examined
182 * @return the naturalness of the given directive
183 * @since 9
184 */
185 default Naturalness getNaturalness(ModuleElement m, ModuleElement.Directive directive) {
186 return Naturalness.NATURAL;
187 }
188
189 /**
190 * The <em>naturalness</em> of a construct. The naturalness of a
191 * construct concerns the consistency between how a construct is
192 * declared in source code (explicitly, implicitly, or not at all)
193 * compared to how the construct is represented in this model.
194 *
195 * Note that it is possible additional kinds of naturalness will
196 * be added in future versions of the platform.
197 *
198 * @jls 13.1. The Form of a Binary
199 * @since 9
200 */
201 enum Naturalness {
202 /**
203 * A natural construct is explicitly declared in source code.
204 */
205 NATURAL,
206
207 /**
208 * A mandated construct is not explicitly declared in the
209 * source code, but its presence is mandated by the
210 * specification to be implicitly declared.
211 *
212 * One example of a mandated construct is a <em>default
213 * constructor</em> in a class that contains no constructor
214 * declarations.
215 *
216 * Another example is the implicitly declared <em>container
217 * annotation</em> used to hold repeated base annotations of
218 * a repeatable annotation type.
219 *
220 * @jls 8.8.9 Default Constructor
221 * @jls 9.6.3. Repeatable Annotation Types
222 * @jls 9.7.5 Multiple Annotations of the Same Type
223 */
224 MANDATED,
225
226 /**
227 * A synthetic construct is one that is neither implicitly nor
228 * explicitly declared in source code. Synthetic constructs are
229 * commonly translation artifacts created by compiler.
230 */
231 SYNTHETIC;
232 }
233
234 /**
235 * Returns {@code true} if the executable element is a bridge
236 * method, {@code false} otherwise.
237 *
238 * @implSpec The default implementation of this method returns {@code false}.
239 *
240 * @param e the executable being examined
241 * @return {@code true} if the executable element is a bridge
242 * method, {@code false} otherwise
243 * @since 9
244 */
245 default boolean isBridge(ExecutableElement e) {
246 return false;
247 }
248
249 /**
250 * Returns the <i>binary name</i> of a type element.
251 *
252 * @param type the type element being examined
253 * @return the binary name
254 *
255 * @see TypeElement#getQualifiedName
256 * @jls 13.1 The Form of a Binary
257 */
258 Name getBinaryName(TypeElement type);
259
260
261 /**
262 * Returns the package of an element. The package of a package is
263 * itself.
264 *
265 * @param type the element being examined
266 * @return the package of an element
267 */
|