1 /*
2 * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
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.element;
27
28 import java.util.List;
29
30 /**
31 * Represents a module program element. Provides access to
32 * information about the module, its directives, and its members.
33 *
34 * @see javax.lang.model.util.Elements#getModuleOf
35 * @since 9
36 * @jls 7.7 Module Declarations
37 * @spec JPMS
38 */
39 public interface ModuleElement extends Element, QualifiedNameable {
40
41 /**
42 * Returns the fully qualified name of this module. For an
43 * {@linkplain #isUnnamed() unnamed module}, an empty name is returned.
44 *
45 * @apiNote If the module name consists of one identifier, then
46 * this method returns that identifier, which is deemed to be
47 * module's fully qualified name despite not being in qualified
48 * form. If the module name consists of more than one identifier,
49 * then this method returns the entire name.
50 *
51 * @return the fully qualified name of this module, or an
52 * empty name if this is an unnamed module
53 *
54 * @jls 6.2 Names and Identifiers
55 */
56 @Override
57 Name getQualifiedName();
58
59 /**
60 * Returns the simple name of this module. For an {@linkplain
61 * #isUnnamed() unnamed module}, an empty name is returned.
62 *
63 * @apiNote If the module name consists of one identifier, then
64 * this method returns that identifier. If the module name
65 * consists of more than one identifier, then this method returns
66 * the rightmost such identifier, which is deemed to be the
67 * module's simple name.
68 *
69 * @return the simple name of this module or an empty name if
70 * this is an unnamed module
71 *
72 * @jls 6.2 Names and Identifiers
73 */
74 @Override
75 Name getSimpleName();
76
77 /**
78 * Returns the packages within this module.
79 * @return the packages within this module
80 */
81 @Override
82 List<? extends Element> getEnclosedElements();
83
84 /**
85 * Returns {@code true} if this is an open module and {@code
86 * false} otherwise.
87 *
88 * @return {@code true} if this is an open module and {@code
89 * false} otherwise
90 */
91 boolean isOpen();
92
93 /**
94 * Returns {@code true} if this is an unnamed module and {@code
95 * false} otherwise.
96 *
97 * @return {@code true} if this is an unnamed module and {@code
98 * false} otherwise
99 *
100 * @jls 7.7.5 Unnamed Modules
101 */
102 boolean isUnnamed();
103
104 /**
105 * Returns {@code null} since a module is not enclosed by another
106 * element.
107 *
108 * @return {@code null}
109 */
110 @Override
111 Element getEnclosingElement();
112
113 /**
114 * Returns the directives contained in the declaration of this module.
115 * @return the directives in the declaration of this module
116 */
117 List<? extends Directive> getDirectives();
118
119 /**
120 * The {@code kind} of a directive.
121 *
122 * <p>Note that it is possible additional directive kinds will be added
123 * to accommodate new, currently unknown, language structures added to
124 * future versions of the Java™ programming language.
125 *
126 * @since 9
127 * @spec JPMS
128 */
129 enum DirectiveKind {
130 /** A "requires (static|transitive)* module-name" directive. */
131 REQUIRES,
132 /** An "exports package-name [to module-name-list]" directive. */
133 EXPORTS,
134 /** An "opens package-name [to module-name-list]" directive. */
135 OPENS,
136 /** A "uses service-name" directive. */
137 USES,
138 /** A "provides service-name with implementation-name" directive. */
139 PROVIDES
140 };
141
142 /**
143 * Represents a directive within the declaration of this
144 * module. The directives of a module declaration configure the
145 * module in the Java Platform Module System.
146 *
147 * @since 9
148 * @spec JPMS
149 */
150 interface Directive {
151 /**
152 * Returns the {@code kind} of this directive.
153 *
154 * @return the kind of this directive
155 */
156 DirectiveKind getKind();
157
158 /**
159 * Applies a visitor to this directive.
160 *
161 * @param <R> the return type of the visitor's methods
162 * @param <P> the type of the additional parameter to the visitor's methods
163 * @param v the visitor operating on this directive
164 * @param p additional parameter to the visitor
165 * @return a visitor-specified result
166 */
167 <R, P> R accept(DirectiveVisitor<R, P> v, P p);
168 }
169
170 /**
171 * A visitor of module directives, in the style of the visitor design
172 * pattern. Classes implementing this interface are used to operate
173 * on a directive when the kind of directive is unknown at compile time.
174 * When a visitor is passed to a directive's {@link Directive#accept
175 * accept} method, the <code>visit<i>Xyz</i></code> method applicable
176 * to that directive is invoked.
177 *
178 * <p> Classes implementing this interface may or may not throw a
179 * {@code NullPointerException} if the additional parameter {@code p}
180 * is {@code null}; see documentation of the implementing class for
181 * details.
182 *
183 * <p> <b>WARNING:</b> It is possible that methods will be added to
184 * this interface to accommodate new, currently unknown, language
185 * structures added to future versions of the Java™ programming
186 * language. Methods to accommodate new language constructs will
187 * be added in a source <em>compatible</em> way using
188 * <em>default methods</em>.
189 *
190 * @param <R> the return type of this visitor's methods. Use {@link
191 * Void} for visitors that do not need to return results.
192 * @param <P> the type of the additional parameter to this visitor's
193 * methods. Use {@code Void} for visitors that do not need an
194 * additional parameter.
195 *
196 * @since 9
197 * @spec JPMS
198 */
199 interface DirectiveVisitor<R, P> {
200 /**
201 * Visits any directive as if by passing itself to that
202 * directive's {@link Directive#accept accept} method and passing
203 * {@code null} for the additional parameter.
204 *
205 * @param d the directive to visit
206 * @return a visitor-specified result
207 * @implSpec The default implementation is {@code d.accept(v, null)}.
208 */
209 default R visit(Directive d) {
210 return d.accept(this, null);
211 }
212
213 /**
214 * Visits any directive as if by passing itself to that
215 * directive's {@link Directive#accept accept} method.
216 *
217 * @param d the directive to visit
218 * @param p a visitor-specified parameter
219 * @return a visitor-specified result
220 * @implSpec The default implementation is {@code d.accept(v, p)}.
221 */
222 default R visit(Directive d, P p) {
223 return d.accept(this, p);
224 }
225
226 /**
227 * Visits a {@code requires} directive.
228 * @param d the directive to visit
229 * @param p a visitor-specified parameter
230 * @return a visitor-specified result
231 */
232 R visitRequires(RequiresDirective d, P p);
233
234 /**
235 * Visits an {@code exports} directive.
236 * @param d the directive to visit
237 * @param p a visitor-specified parameter
238 * @return a visitor-specified result
239 */
240 R visitExports(ExportsDirective d, P p);
241
242 /**
243 * Visits an {@code opens} directive.
244 * @param d the directive to visit
245 * @param p a visitor-specified parameter
246 * @return a visitor-specified result
247 */
248 R visitOpens(OpensDirective d, P p);
249
250 /**
251 * Visits a {@code uses} directive.
252 * @param d the directive to visit
253 * @param p a visitor-specified parameter
254 * @return a visitor-specified result
255 */
256 R visitUses(UsesDirective d, P p);
257
258 /**
259 * Visits a {@code provides} directive.
260 * @param d the directive to visit
261 * @param p a visitor-specified parameter
262 * @return a visitor-specified result
263 */
264 R visitProvides(ProvidesDirective d, P p);
265
266 /**
267 * Visits an unknown directive.
268 * This can occur if the language evolves and new kinds of directive are added.
269 * @param d the directive to visit
270 * @param p a visitor-specified parameter
271 * @return a visitor-specified result
272 * @throws UnknownDirectiveException a visitor implementation may optionally throw this exception
273 * @implSpec The default implementation throws {@code new UnknownDirectiveException(d, p)}.
274 */
275 default R visitUnknown(Directive d, P p) {
276 throw new UnknownDirectiveException(d, p);
277 }
278 }
279
280 /**
281 * A dependency of a module.
282 * @since 9
283 * @spec JPMS
284 */
285 interface RequiresDirective extends Directive {
286 /**
287 * Returns whether or not this is a static dependency.
288 * @return whether or not this is a static dependency
289 */
290 boolean isStatic();
291
292 /**
293 * Returns whether or not this is a transitive dependency.
294 * @return whether or not this is a transitive dependency
295 */
296 boolean isTransitive();
297
298 /**
299 * Returns the module that is required
300 * @return the module that is required
301 */
302 ModuleElement getDependency();
303 }
304
305 /**
306 * An exported package of a module.
307 * @since 9
308 * @spec JPMS
309 */
310 interface ExportsDirective extends Directive {
311
312 /**
313 * Returns the package being exported.
314 * @return the package being exported
315 */
316 PackageElement getPackage();
317
318 /**
319 * Returns the specific modules to which the package is being exported,
320 * or {@code null}, if the package is exported to all modules which
321 * have readability to this module.
322 * @return the specific modules to which the package is being exported
323 */
324 List<? extends ModuleElement> getTargetModules();
325 }
326
327 /**
328 * An opened package of a module.
329 * @since 9
330 * @spec JPMS
331 */
332 interface OpensDirective extends Directive {
333
334 /**
335 * Returns the package being opened.
336 * @return the package being opened
337 */
338 PackageElement getPackage();
339
340 /**
341 * Returns the specific modules to which the package is being open
342 * or {@code null}, if the package is open all modules which
343 * have readability to this module.
344 * @return the specific modules to which the package is being opened
345 */
346 List<? extends ModuleElement> getTargetModules();
347 }
348
349 /**
350 * An implementation of a service provided by a module.
351 * @since 9
352 * @spec JPMS
353 */
354 interface ProvidesDirective extends Directive {
355 /**
356 * Returns the service being provided.
357 * @return the service being provided
358 */
359 TypeElement getService();
360
361 /**
362 * Returns the implementations of the service being provided.
363 * @return the implementations of the service being provided
364 */
365 List<? extends TypeElement> getImplementations();
366 }
367
368 /**
369 * A reference to a service used by a module.
370 * @since 9
371 * @spec JPMS
372 */
373 interface UsesDirective extends Directive {
374 /**
375 * Returns the service that is used.
376 * @return the service that is used
377 */
378 TypeElement getService();
379 }
380 }