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