ModuleElement.java revision 4220:51b4cd2af28e
1224726Sdougb/* 252400Sbillf * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved. 352400Sbillf * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 452400Sbillf * 552400Sbillf * This code is free software; you can redistribute it and/or modify it 652400Sbillf * under the terms of the GNU General Public License version 2 only, as 752400Sbillf * published by the Free Software Foundation. Oracle designates this 852400Sbillf * particular file as subject to the "Classpath" exception as provided 952400Sbillf * by Oracle in the LICENSE file that accompanied this code. 1052400Sbillf * 1152400Sbillf * This code is distributed in the hope that it will be useful, but WITHOUT 1252400Sbillf * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1352400Sbillf * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1452400Sbillf * version 2 for more details (a copy is included in the LICENSE file that 1552400Sbillf * accompanied this code). 1652400Sbillf * 1752400Sbillf * You should have received a copy of the GNU General Public License version 1852400Sbillf * 2 along with this work; if not, write to the Free Software Foundation, 1952400Sbillf * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2052400Sbillf * 2152400Sbillf * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2252400Sbillf * or visit www.oracle.com if you need additional information or have any 2352400Sbillf * questions. 2452400Sbillf */ 2552531Sbillf 2652400Sbillfpackage javax.lang.model.element; 27288381Sbdrewery 2852400Sbillfimport java.util.List; 2979537Sru 3052400Sbillf/** 3152400Sbillf * Represents a module program element. Provides access to 3275670Sru * information about the module, its directives, and its members. 3352400Sbillf * 3452400Sbillf * @see javax.lang.model.util.Elements#getModuleOf 35205145Sdougb * @since 9 36205145Sdougb * @jls 7.7 Module Declarations 37227013Sdougb * @spec JPMS 3852400Sbillf */ 3952400Sbillfpublic interface ModuleElement extends Element, QualifiedNameable { 4052400Sbillf 4152400Sbillf /** 4252400Sbillf * Returns the fully qualified name of this module. For an 43189994Sdougb * {@linkplain #isUnnamed() unnamed module}, an empty name is returned. 44189994Sdougb * 4552400Sbillf * @apiNote If the module name consists of one identifier, then 4699968Scharnier * this method returns that identifier, which is deemed to be 4752400Sbillf * module's fully qualified name despite not being in qualified 4899968Scharnier * form. If the module name consists of more than one identifier, 4952400Sbillf * then this method returns the entire name. 5068716Sru * 5168716Sru * @return the fully qualified name of this module, or an 5252400Sbillf * empty name if this is an unnamed module 5352400Sbillf * 5452400Sbillf * @jls 6.2 Names and Identifiers 5552400Sbillf */ 5652400Sbillf @Override 5752400Sbillf Name getQualifiedName(); 5852400Sbillf 59186679Sdougb /** 6052400Sbillf * Returns the simple name of this module. For an {@linkplain 6152400Sbillf * #isUnnamed() unnamed module}, an empty name is returned. 6252400Sbillf * 6357673Ssheldonh * @apiNote If the module name consists of one identifier, then 6457673Ssheldonh * this method returns that identifier. If the module name 6552400Sbillf * consists of more than one identifier, then this method returns 66201293Sdougb * the rightmost such identifier, which is deemed to be the 6767949Sdougb * module's simple name. 6867949Sdougb * 69201293Sdougb * @return the simple name of this module or an empty name if 7067949Sdougb * this is an unnamed module 7152400Sbillf * 7257673Ssheldonh * @jls 6.2 Names and Identifiers 7357673Ssheldonh */ 7452400Sbillf @Override 7552400Sbillf Name getSimpleName(); 7657673Ssheldonh 7757673Ssheldonh /** 7852400Sbillf * Returns the packages within this module. 7952400Sbillf * @return the packages within this module 8052400Sbillf */ 8152400Sbillf @Override 8252400Sbillf List<? extends Element> getEnclosedElements(); 8352400Sbillf 8452400Sbillf /** 8552400Sbillf * Returns {@code true} if this is an open module and {@code 8652400Sbillf * false} otherwise. 87190320Sdougb * 88189994Sdougb * @return {@code true} if this is an open module and {@code 8957673Ssheldonh * false} otherwise 9057673Ssheldonh */ // TODO: add @jls to unnamed module section 91189994Sdougb boolean isOpen(); 9257673Ssheldonh 9357673Ssheldonh /** 94189994Sdougb * Returns {@code true} if this is an unnamed module and {@code 95189994Sdougb * false} otherwise. 96201293Sdougb * 97189994Sdougb * @return {@code true} if this is an unnamed module and {@code 98189994Sdougb * false} otherwise 99201293Sdougb */ // TODO: add @jls to unnamed module section 100189994Sdougb boolean isUnnamed(); 101189994Sdougb 102189994Sdougb /** 103189994Sdougb * Returns {@code null} since a module is not enclosed by another 10452400Sbillf * element. 105114503Sdougb * 106114503Sdougb * @return {@code null} 107114503Sdougb */ 108114503Sdougb @Override 109114503Sdougb Element getEnclosingElement(); 110114503Sdougb 11199968Scharnier /** 11252400Sbillf * Returns the directives contained in the declaration of this module. 11399968Scharnier * @return the directives in the declaration of this module 114131500Sru */ 115131500Sru List<? extends Directive> getDirectives(); 11652400Sbillf 11757673Ssheldonh /** 11857673Ssheldonh * The {@code kind} of a directive. 11952400Sbillf * 12052400Sbillf * <p>Note that it is possible additional directive kinds will be added 12152400Sbillf * to accommodate new, currently unknown, language structures added to 12257673Ssheldonh * future versions of the Java™ programming language. 12357673Ssheldonh * 12452400Sbillf * @since 9 12557673Ssheldonh * @spec JPMS 12657673Ssheldonh */ 12752400Sbillf enum DirectiveKind { 12852400Sbillf /** A "requires (static|transitive)* module-name" directive. */ 12952400Sbillf REQUIRES, 130189994Sdougb /** An "exports package-name [to module-name-list]" directive. */ 131201293Sdougb EXPORTS, 132189994Sdougb /** An "opens package-name [to module-name-list]" directive. */ 13352400Sbillf OPENS, 13452400Sbillf /** A "uses service-name" directive. */ 13552400Sbillf USES, 136189994Sdougb /** A "provides service-name with implementation-name" directive. */ 13752400Sbillf PROVIDES 13852400Sbillf }; 13952400Sbillf 14052400Sbillf /** 14152400Sbillf * Represents a directive within the declaration of this 14252400Sbillf * module. The directives of a module declaration configure the 14399968Scharnier * module in the Java Platform Module System. 14467949Sdougb * 14599968Scharnier * @since 9 146141851Sru * @spec JPMS 14767949Sdougb */ 14867949Sdougb interface Directive { 14967949Sdougb /** 15067949Sdougb * Returns the {@code kind} of this directive. 15167949Sdougb * 15267949Sdougb * @return the kind of this directive 15367949Sdougb */ 15467949Sdougb DirectiveKind getKind(); 15567949Sdougb 15667949Sdougb /** 15767949Sdougb * Applies a visitor to this directive. 15867949Sdougb * 15967949Sdougb * @param <R> the return type of the visitor's methods 16067949Sdougb * @param <P> the type of the additional parameter to the visitor's methods 16167949Sdougb * @param v the visitor operating on this directive 16267949Sdougb * @param p additional parameter to the visitor 16373651Sdougb * @return a visitor-specified result 16473651Sdougb */ 16573651Sdougb <R, P> R accept(DirectiveVisitor<R, P> v, P p); 16673651Sdougb } 16773651Sdougb 16873651Sdougb /** 16967949Sdougb * A visitor of module directives, in the style of the visitor design 170201765Sdougb * pattern. Classes implementing this interface are used to operate 171201765Sdougb * on a directive when the kind of directive is unknown at compile time. 172201765Sdougb * When a visitor is passed to a directive's {@link Directive#accept 173205145Sdougb * accept} method, the <code>visit<i>Xyz</i></code> method applicable 174201765Sdougb * to that directive is invoked. 175201765Sdougb * 176201765Sdougb * <p> Classes implementing this interface may or may not throw a 177201765Sdougb * {@code NullPointerException} if the additional parameter {@code p} 17852400Sbillf * is {@code null}; see documentation of the implementing class for 17952400Sbillf * details. 18052400Sbillf * 181189994Sdougb * <p> <b>WARNING:</b> It is possible that methods will be added to 18290563Sdougb * this interface to accommodate new, currently unknown, language 183189994Sdougb * structures added to future versions of the Java™ programming 18452400Sbillf * language. Methods to accommodate new language constructs will 18552400Sbillf * be added in a source <em>compatible</em> way using 18652400Sbillf * <em>default methods</em>. 18752400Sbillf * 18852400Sbillf * @param <R> the return type of this visitor's methods. Use {@link 18952400Sbillf * Void} for visitors that do not need to return results. 19057673Ssheldonh * @param <P> the type of the additional parameter to this visitor's 19157673Ssheldonh * methods. Use {@code Void} for visitors that do not need an 19252400Sbillf * additional parameter. 19352400Sbillf * 19457673Ssheldonh * @since 9 19557673Ssheldonh * @spec JPMS 19652400Sbillf */ 19768965Sru interface DirectiveVisitor<R, P> { 19852400Sbillf /** 19952400Sbillf * Visits any directive as if by passing itself to that 20052400Sbillf * directive's {@link Directive#accept accept} method and passing 20152400Sbillf * {@code null} for the additional parameter. 20257673Ssheldonh * The invocation {@code v.visit(d)} is equivalent to 20357673Ssheldonh * {@code d.accept(v, null)}. 20452400Sbillf * @param d the directive to visit 20557673Ssheldonh * @return a visitor-specified result 20657673Ssheldonh * @implSpec This implementation is {@code visit(d, null)} 20752400Sbillf */ 20852400Sbillf default R visit(Directive d) { 20957673Ssheldonh return d.accept(this, null); 21057673Ssheldonh } 211205145Sdougb 212205145Sdougb /** 213205145Sdougb * Visits any directive as if by passing itself to that 214205145Sdougb * directive's {@link Directive#accept accept} method. 215205145Sdougb * The invocation {@code v.visit(d, p)} is equivalent to 216189994Sdougb * {@code d.accept(v, p)}. 217201293Sdougb * @param d the directive to visit 218189994Sdougb * @param p a visitor-specified parameter 219201293Sdougb * @return a visitor-specified result 220189994Sdougb */ 22152400Sbillf default R visit(Directive d, P p) { 22252400Sbillf return d.accept(this, p); 22367949Sdougb } 22467949Sdougb 22567949Sdougb /** 22694188Sdougb * Visits a {@code requires} directive. 22794188Sdougb * @param d the directive to visit 22896046Sdougb * @param p a visitor-specified parameter 22994188Sdougb * @return a visitor-specified result 23094188Sdougb */ 23194188Sdougb R visitRequires(RequiresDirective d, P p); 232189994Sdougb 233190320Sdougb /** 234189994Sdougb * Visits an {@code exports} directive. 23594188Sdougb * @param d the directive to visit 23694188Sdougb * @param p a visitor-specified parameter 23794188Sdougb * @return a visitor-specified result 23894188Sdougb */ 23994188Sdougb R visitExports(ExportsDirective d, P p); 240114503Sdougb 241114503Sdougb /** 242114503Sdougb * Visits an {@code opens} directive. 243114503Sdougb * @param d the directive to visit 244114503Sdougb * @param p a visitor-specified parameter 245114503Sdougb * @return a visitor-specified result 246189994Sdougb */ 247189994Sdougb R visitOpens(OpensDirective d, P p); 248224726Sdougb 249224726Sdougb /** 250227013Sdougb * Visits a {@code uses} directive. 251227013Sdougb * @param d the directive to visit 252227013Sdougb * @param p a visitor-specified parameter 253227013Sdougb * @return a visitor-specified result 254227013Sdougb */ 25552400Sbillf R visitUses(UsesDirective d, P p); 25652400Sbillf 25752400Sbillf /** 25852400Sbillf * Visits a {@code provides} directive. 25952400Sbillf * @param d the directive to visit 260288381Sbdrewery * @param p a visitor-specified parameter 261186704Sdougb * @return a visitor-specified result 262288381Sbdrewery */ 263288381Sbdrewery R visitProvides(ProvidesDirective d, P p); 264288381Sbdrewery 265186704Sdougb /** 266288381Sbdrewery * Visits an unknown directive. 26752400Sbillf * This can occur if the language evolves and new kinds of directive are added. 26852400Sbillf * @param d the directive to visit 26952400Sbillf * @param p a visitor-specified parameter 27052400Sbillf * @return a visitor-specified result 27152400Sbillf * @throws UnknownDirectiveException a visitor implementation may optionally throw this exception 27252400Sbillf * @implSpec This implementation throws {@code new UnknownDirectiveException(d, p)}. 27352400Sbillf */ 27457673Ssheldonh default R visitUnknown(Directive d, P p) { 275189994Sdougb throw new UnknownDirectiveException(d, p); 276201293Sdougb } 277189994Sdougb } 27852400Sbillf 27952400Sbillf /** 28057673Ssheldonh * A dependency of a module. 28157673Ssheldonh * @since 9 28252400Sbillf * @spec JPMS 28352400Sbillf */ 28452400Sbillf interface RequiresDirective extends Directive { 28557673Ssheldonh /** 28657673Ssheldonh * Returns whether or not this is a static dependency. 287186679Sdougb * @return whether or not this is a static dependency 288155309Srwatson */ 289155309Srwatson boolean isStatic(); 290155309Srwatson 29167949Sdougb /** 29267949Sdougb * Returns whether or not this is a transitive dependency. 29352400Sbillf * @return whether or not this is a transitive dependency 29452400Sbillf */ 29552400Sbillf boolean isTransitive(); 29652400Sbillf 29799968Scharnier /** 29852400Sbillf * Returns the module that is required 29957673Ssheldonh * @return the module that is required 30057673Ssheldonh */ 30152400Sbillf ModuleElement getDependency(); 30252400Sbillf } 30352400Sbillf 30452400Sbillf /** 30552400Sbillf * An exported package of a module. 30652400Sbillf * @since 9 30752400Sbillf * @spec JPMS 30852400Sbillf */ 30952400Sbillf interface ExportsDirective extends Directive { 31052400Sbillf 31167949Sdougb /** 31267949Sdougb * Returns the package being exported. 31367949Sdougb * @return the package being exported 31467949Sdougb */ 31567949Sdougb PackageElement getPackage(); 31667949Sdougb 31767949Sdougb /** 31867949Sdougb * Returns the specific modules to which the package is being exported, 31967949Sdougb * or null, if the package is exported to all modules which 32052400Sbillf * have readability to this module. 32179300Sru * @return the specific modules to which the package is being exported 32277334Sdougb */ 32370403Sru List<? extends ModuleElement> getTargetModules(); 32479300Sru } 32577334Sdougb 32699968Scharnier /** 32752400Sbillf * An opened package of a module. 328131500Sru * @since 9 329131500Sru * @spec JPMS 330131500Sru */ 33157673Ssheldonh interface OpensDirective extends Directive { 33257673Ssheldonh 33377334Sdougb /** 33477334Sdougb * Returns the package being opened. 33577334Sdougb * @return the package being opened 33657673Ssheldonh */ 33752400Sbillf PackageElement getPackage(); 33852400Sbillf 33952400Sbillf /** 34052400Sbillf * Returns the specific modules to which the package is being open 34152400Sbillf * or null, if the package is open all modules which 342201292Sdougb * have readability to this module. 343186679Sdougb * @return the specific modules to which the package is being opened 344186679Sdougb */ 345201292Sdougb List<? extends ModuleElement> getTargetModules(); 346186679Sdougb } 347186679Sdougb 348201292Sdougb /** 34952400Sbillf * An implementation of a service provided by a module. 35052400Sbillf * @since 9 351201292Sdougb * @spec JPMS 352186679Sdougb */ 353186679Sdougb interface ProvidesDirective extends Directive { 354201292Sdougb /** 35552400Sbillf * Returns the service being provided. 35652400Sbillf * @return the service being provided 357201292Sdougb */ 35852400Sbillf TypeElement getService(); 35952400Sbillf 360201292Sdougb /** 361189994Sdougb * Returns the implementations of the service being provided. 362189994Sdougb * @return the implementations of the service being provided 363201292Sdougb */ 36452400Sbillf List<? extends TypeElement> getImplementations(); 36552400Sbillf } 366201292Sdougb 36767949Sdougb /** 36867949Sdougb * A reference to a service used by a module. 369201292Sdougb * @since 9 370224726Sdougb * @spec JPMS 371179725Sdougb */ 372179725Sdougb interface UsesDirective extends Directive { 373227013Sdougb /** 374227013Sdougb * Returns the service that is used. 375227013Sdougb * @return the service that is used 376201292Sdougb */ 377201292Sdougb TypeElement getService(); 37896046Sdougb } 379201292Sdougb} 380201292Sdougb