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