/* * Copyright (c) 2014, 2016, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.lang.reflect; import java.io.IOException; import java.io.InputStream; import java.lang.module.Configuration; import java.lang.module.ModuleReference; import java.lang.module.ModuleDescriptor; import java.lang.module.ModuleDescriptor.Exports; import java.lang.module.ModuleDescriptor.Provides; import java.lang.module.ModuleDescriptor.Version; import java.lang.module.ResolvedModule; import java.net.URI; import java.net.URL; import java.util.Collections; import java.util.HashMap; import java.util.HashSet; import java.util.Map; import java.util.Objects; import java.util.Optional; import java.util.Set; import java.util.function.Function; import java.util.stream.Stream; import jdk.internal.loader.BuiltinClassLoader; import jdk.internal.loader.BootLoader; import jdk.internal.misc.JavaLangReflectModuleAccess; import jdk.internal.misc.SharedSecrets; import jdk.internal.module.ServicesCatalog; import sun.reflect.CallerSensitive; import sun.reflect.Reflection; import sun.security.util.SecurityConstants; /** * Represents a run-time module, either {@link #isNamed() named} or unnamed. * *
Named modules have a {@link #getName() name} and are constructed by the * Java Virtual Machine when a graph of modules is defined to the Java virtual * machine to create a module {@link Layer Layer}.
* *An unnamed module does not have a name. There is an unnamed module * per {@link ClassLoader ClassLoader} that is obtained by invoking the class * loader's {@link ClassLoader#getUnnamedModule() getUnnamedModule} method. The * {@link Class#getModule() getModule} method of all types defined by a class * loader that are not in a named module return the class loader's unnamed * module.
* *The package names that are parameters or returned by methods defined in * this class are the fully-qualified names of the packages as defined in * section 6.5.3 of The Java™ Language Specification , for * example, {@code "java.lang"}.
* *Unless otherwise specified, passing a {@code null} argument to a method * in this class causes a {@link NullPointerException NullPointerException} to * be thrown.
* * @since 9 * @see java.lang.Class#getModule */ public final class Module { // the layer that contains this module, can be null private final Layer layer; // module name and loader, these fields are read by VM private final String name; private final ClassLoader loader; // the module descriptor private final ModuleDescriptor descriptor; /** * Creates a new named Module. The resulting Module will be defined to the * VM but will not read any other modules, will not have any exports setup * and will not be registered in the service catalog. */ private Module(Layer layer, ClassLoader loader, ModuleDescriptor descriptor, URI uri) { this.layer = layer; this.name = descriptor.name(); this.loader = loader; this.descriptor = descriptor; // define module to VM SetIf there is a security manager then its {@code checkPermission} * method if first called with a {@code RuntimePermission("getClassLoader")} * permission to check that the caller is allowed to get access to the * class loader.
* * @return The class loader for this module * * @throws SecurityException * If denied by the security manager */ public ClassLoader getClassLoader() { SecurityManager sm = System.getSecurityManager(); if (sm != null) { sm.checkPermission(SecurityConstants.GET_CLASSLOADER_PERMISSION); } return loader; } /** * Returns the module descriptor for this module or {@code null} if this * module is an unnamed module. * * @return The module descriptor for this module */ public ModuleDescriptor getDescriptor() { return descriptor; } /** * Returns the layer that contains this module or {@code null} if this * module is not in a layer. * * A module {@code Layer} contains named modules and therefore this * method always returns {@code null} when invoked on an unnamed module. * *Dynamic modules are named * modules that are generated at runtime. A dynamic module may or may * not be in a module Layer.
* * @return The layer that contains this module * * @see Proxy */ public Layer getLayer() { if (isNamed()) { Layer layer = this.layer; if (layer != null) return layer; // special-case java.base as it is created before the boot Layer if (loader == null && name.equals("java.base")) { return SharedSecrets.getJavaLangAccess().getBootLayer(); } } return null; } // -- readability -- // true if this module reads all unnamed modules (a.k.a. loose module) private volatile boolean loose; // the modules that this module permanently reads // (will be final when the modules are defined in reverse topology order) private volatile SetThis method always return {@code true} when invoked on an unnamed * module.
* *This method does not check if the given module reads this module
* * @param pn * The package name * @param other * The other module * * @return {@code true} if this module exports the package to at least the * given module */ public boolean isExported(String pn, Module other) { Objects.requireNonNull(pn); Objects.requireNonNull(other); return implIsExported(pn, other); } /** * Returns {@code true} if this module exports the given package * unconditionally. * *This method always return {@code true} when invoked on an unnamed * module.
* *This method does not check if the given module reads this module
* * @param pn * The package name * * @return {@code true} if this module exports the package unconditionally */ public boolean isExported(String pn) { Objects.requireNonNull(pn); return implIsExported(pn, EVERYONE_MODULE); } /** * Returns {@code true} if this module exports the given package to the * given module. If the other module is {@code EVERYONE_MODULE} then * this method tests if the package is exported unconditionally. */ private boolean implIsExported(String pn, Module other) { // all packages are exported by unnamed modules if (!isNamed()) return true; // exported via module declaration/descriptor if (isExportedPermanently(pn, other)) return true; // exported via addExports if (isExportedReflectively(pn, other)) return true; // not exported or not exported to other return false; } /** * Returns {@code true} if this module permanently exports the given * package to the given module. */ private boolean isExportedPermanently(String pn, Module other) { MapThis method has no effect if the package is already exported to the * given module. If also has no effect if invoked on an unnamed module (as * unnamed modules export all packages).
* * @param pn * The package name * @param other * The module * * @return this module * * @throws IllegalArgumentException * If {@code pn} is {@code null}, or this is a named module and the * package {@code pn} is not a package in this module * @throws IllegalStateException * If this is a named module and the caller is not this module */ @CallerSensitive public Module addExports(String pn, Module other) { if (pn == null) throw new IllegalArgumentException("package is null"); Objects.requireNonNull(other); if (isNamed()) { Module caller = Reflection.getCallerClass().getModule(); if (caller != this) { throw new IllegalStateException(caller + " != " + this); } implAddExports(pn, other, true); } return this; } /** * Updates the exports so that package {@code pn} is exported to module * {@code other} but without notifying the VM. * * @apiNote This method is for VM white-box testing. */ void implAddExportsNoSync(String pn, Module other) { if (other == null) other = EVERYONE_MODULE; implAddExports(pn.replace('/', '.'), other, false); } /** * Updates the exports so that package {@code pn} is exported to module * {@code other}. * * @apiNote This method is for white-box testing. */ void implAddExports(String pn, Module other) { implAddExports(pn, other, true); } /** * Updates the exports so that package {@code pn} is exported to module * {@code other}. * * If {@code syncVM} is {@code true} then the VM is notified. */ private void implAddExports(String pn, Module other, boolean syncVM) { Objects.requireNonNull(other); Objects.requireNonNull(pn); // unnamed modules export all packages if (!isNamed()) return; // nothing to do if already exported to other if (implIsExported(pn, other)) return; // can only export a package in the module if (!containsPackage(pn)) { throw new IllegalArgumentException("package " + pn + " not in contents"); } // update VM first, just in case it fails if (syncVM) { String pkgInternalForm = pn.replace('.', '/'); if (other == EVERYONE_MODULE) { addExportsToAll0(this, pkgInternalForm); } else if (other == ALL_UNNAMED_MODULE) { addExportsToAllUnnamed0(this, pkgInternalForm); } else { addExports0(this, pkgInternalForm, other); } } // add package name to transientExports if absent transientExports .computeIfAbsent(this, other, (_this, _other) -> new HashSet<>()) .add(pn); } // -- services -- // additional service type (2nd key) that some module (1st key) uses private static final WeakPairMapThis method does not cause {@link * Configuration#resolveRequiresAndUses resolveRequiresAndUses} to be * re-run.
* * @param st * The service type * * @return this module * * @throws IllegalStateException * If this is a named module and the caller is not this module * * @see #canUse(Class) * @see ModuleDescriptor#uses() */ @CallerSensitive public Module addUses(Class> st) { Objects.requireNonNull(st); if (isNamed()) { Module caller = Reflection.getCallerClass().getModule(); if (caller != this) { throw new IllegalStateException(caller + " != " + this); } if (!canUse(st)) { transientUses.putIfAbsent(this, st, Boolean.TRUE); } } return this; } /** * Indicates if this module has a service dependence on the given service * type. This method always returns {@code true} when invoked on an unnamed * module. * * @param st * The service type * * @return {@code true} if this module uses service type {@code st} * * @see #addUses(Class) */ public boolean canUse(Class> st) { Objects.requireNonNull(st); if (!isNamed()) return true; if (descriptor.isAutomatic()) return true; // uses was declared if (descriptor.uses().contains(st.getName())) return true; // uses added via addUses return transientUses.constainsKeyPair(this, st); } // -- packages -- // Additional packages that are added to the module at run-time. // The field is volatile as it may be replaced at run-time private volatile SetFor named modules, the returned array contains an element for each * package in the module. It may contain elements corresponding to packages * added to the module, dynamic modules * for example, after it was loaded. * *
For unnamed modules, this method is the equivalent of invoking the * {@link ClassLoader#getDefinedPackages() getDefinedPackages} method of * this module's class loader and returning the array of package names.
* *A package name appears at most once in the returned array.
* * @apiNote This method returns an array rather than a {@code Set} for * consistency with other {@code java.lang.reflect} types. * * @return an array of the package names of the packages in this module */ public String[] getPackages() { if (isNamed()) { SetIf this module is an unnamed module, and the {@code ClassLoader} for * this module is not {@code null}, then this method is equivalent to * invoking the {@link ClassLoader#getResourceAsStream(String) * getResourceAsStream} method on the class loader for this module. * * @param name * The resource name * * @return An input stream for reading the resource or {@code null} * * @throws IOException * If an I/O error occurs * * @see java.lang.module.ModuleReader#open(String) */ public InputStream getResourceAsStream(String name) throws IOException { Objects.requireNonNull(name); URL url = null; if (isNamed()) { String mn = this.name; // special-case built-in class loaders to avoid URL connection if (loader == null) { return BootLoader.findResourceAsStream(mn, name); } else if (loader instanceof BuiltinClassLoader) { return ((BuiltinClassLoader) loader).findResourceAsStream(mn, name); } // use SharedSecrets to invoke protected method url = SharedSecrets.getJavaLangAccess().findResource(loader, mn, name); } else { // unnamed module if (loader == null) { url = BootLoader.findResource(name); } else { return loader.getResourceAsStream(name); } } // fallthrough to URL case if (url != null) { try { return url.openStream(); } catch (SecurityException e) { } } return null; } /** * Returns the string representation of this module. For a named module, * the representation is the string {@code "module"}, followed by a space, * and then the module name. For an unnamed module, the representation is * the string {@code "unnamed module"}, followed by a space, and then an * implementation specific identifier for the unnamed module. * * @return The string representation of this module */ @Override public String toString() { if (isNamed()) { return "module " + name; } else { String id = Integer.toHexString(System.identityHashCode(this)); return "unnamed module @" + id; } } // -- native methods -- // JVM_DefineModule private static native void defineModule0(Module module, String version, String location, String[] pns); // JVM_AddReadsModule private static native void addReads0(Module from, Module to); // JVM_AddModuleExports private static native void addExports0(Module from, String pn, Module to); // JVM_AddModuleExportsToAll private static native void addExportsToAll0(Module from, String pn); // JVM_AddModuleExportsToAllUnnamed private static native void addExportsToAllUnnamed0(Module from, String pn); // JVM_AddModulePackage private static native void addPackage0(Module m, String pn); /** * Register shared secret to provide access to package-private methods */ static { SharedSecrets.setJavaLangReflectModuleAccess( new JavaLangReflectModuleAccess() { @Override public Module defineUnnamedModule(ClassLoader loader) { return new Module(loader); } @Override public Module defineModule(ClassLoader loader, ModuleDescriptor descriptor, URI uri) { return new Module(null, loader, descriptor, uri); } @Override public void addReads(Module m1, Module m2) { m1.implAddReads(m2, true); } @Override public void addExports(Module m, String pn, Module other) { m.implAddExports(pn, Objects.requireNonNull(other), true); } @Override public void addExportsToAll(Module m, String pn) { m.implAddExports(pn, Module.EVERYONE_MODULE, true); } @Override public void addExportsToAllUnnamed(Module m, String pn) { m.implAddExports(pn, Module.ALL_UNNAMED_MODULE, true); } @Override public void addPackage(Module m, String pn) { m.implAddPackage(pn, true); } }); } }