A layer is created from a graph of modules in a {@link Configuration} * and a function that maps each module to a {@link ClassLoader}. * Creating a layer informs the Java virtual machine about the classes that * may be loaded from the modules so that the Java virtual machine knows which * module that each class is a member of.
* *Creating a layer creates a {@link Module} object for each {@link * ResolvedModule} in the configuration. For each resolved module that is * {@link ResolvedModule#reads() read}, the {@code Module} {@link * Module#canRead reads} the corresponding run-time {@code Module}, which may * be in the same layer or a {@link #parents() parent} layer.
* *The {@link #defineModulesWithOneLoader defineModulesWithOneLoader} and * {@link #defineModulesWithManyLoaders defineModulesWithManyLoaders} methods * provide convenient ways to create a module layer where all modules are * mapped to a single class loader or where each module is mapped to its own * class loader. The {@link #defineModules defineModules} method is for more * advanced cases where modules are mapped to custom class loaders by means of * a function specified to the method. Each of these methods has an instance * and static variant. The instance methods create a layer with the receiver * as the parent layer. The static methods are for more advanced cases where * there can be more than one parent layer or where a {@link * ModuleLayer.Controller Controller} is needed to control modules in the layer *
* *A Java virtual machine has at least one non-empty layer, the {@link * #boot() boot} layer, that is created when the Java virtual machine is * started. The boot layer contains module {@code java.base} and is the only * layer in the Java virtual machine with a module named "{@code java.base}". * The modules in the boot layer are mapped to the bootstrap class loader and * other class loaders that are * built-in into the Java virtual machine. The boot layer will often be * the {@link #parents() parent} when creating additional layers.
* *Each {@code Module} in a layer is created so that it {@link * Module#isExported(String) exports} and {@link Module#isOpen(String) opens} * the packages described by its {@link ModuleDescriptor}. Qualified exports * (where a package is exported to a set of target modules rather than all * modules) are reified when creating the layer as follows:
*Qualified opens are handled in same way as qualified exports.
* *As when creating a {@code Configuration}, * {@link ModuleDescriptor#isAutomatic() automatic} modules receive special * treatment when creating a layer. An automatic module is created in the * Java virtual machine as a {@code Module} that reads every unnamed {@code * Module} in the Java virtual machine.
* *Unless otherwise specified, passing a {@code null} argument to a method * in this class causes a {@link NullPointerException NullPointerException} to * be thrown.
* *This example creates a configuration by resolving a module named * "{@code myapp}" with the configuration for the boot layer as the parent. It * then creates a new layer with the modules in this configuration. All modules * are defined to the same class loader.
* *{@code
* ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);
*
* ModuleLayer parent = ModuleLayer.boot();
*
* Configuration cf = parent.configuration().resolve(finder, ModuleFinder.of(), Set.of("myapp"));
*
* ClassLoader scl = ClassLoader.getSystemClassLoader();
*
* ModuleLayer layer = parent.defineModulesWithOneLoader(cf, scl);
*
* Class c = layer.findLoader("myapp").loadClass("app.Main");
* }
*
* @since 9
* @spec JPMS
* @see Module#getLayer()
*/
public final class ModuleLayer {
// the empty layer
private static final ModuleLayer EMPTY_LAYER
= new ModuleLayer(Configuration.empty(), List.of(), null);
// the configuration from which this layer was created
private final Configuration cf;
// parent layers, empty in the case of the empty layer
private final ListUnless otherwise specified, passing a {@code null} argument to a * method in this class causes a {@link NullPointerException * NullPointerException} to be thrown.
* * @apiNote Care should be taken with {@code Controller} objects, they * should never be shared with untrusted code. * * @since 9 * @spec JPMS */ public static final class Controller { private final ModuleLayer layer; Controller(ModuleLayer layer) { this.layer = layer; } /** * Returns the layer that this object controls. * * @return the module layer */ public ModuleLayer layer() { return layer; } private void ensureInLayer(Module source) { if (source.getLayer() != layer) throw new IllegalArgumentException(source + " not in layer"); } /** * Updates module {@code source} in the layer to read module * {@code target}. This method is a no-op if {@code source} already * reads {@code target}. * * @implNote Read edges added by this method are weak * and do not prevent {@code target} from being GC'ed when {@code source} * is strongly reachable. * * @param source * The source module * @param target * The target module to read * * @return This controller * * @throws IllegalArgumentException * If {@code source} is not in the module layer * * @see Module#addReads */ public Controller addReads(Module source, Module target) { ensureInLayer(source); source.implAddReads(target); return this; } /** * Updates module {@code source} in the layer to export a package to * module {@code target}. This method is a no-op if {@code source} * already exports the package to at least {@code target}. * * @param source * The source module * @param pn * The package name * @param target * The target module * * @return This controller * * @throws IllegalArgumentException * If {@code source} is not in the module layer or the package * is not in the source module * * @see Module#addExports */ public Controller addExports(Module source, String pn, Module target) { ensureInLayer(source); source.implAddExports(pn, target); return this; } /** * Updates module {@code source} in the layer to open a package to * module {@code target}. This method is a no-op if {@code source} * already opens the package to at least {@code target}. * * @param source * The source module * @param pn * The package name * @param target * The target module * * @return This controller * * @throws IllegalArgumentException * If {@code source} is not in the module layer or the package * is not in the source module * * @see Module#addOpens */ public Controller addOpens(Module source, String pn, Module target) { ensureInLayer(source); source.implAddOpens(pn, target); return this; } } /** * Creates a new module layer, with this layer as its parent, by defining the * modules in the given {@code Configuration} to the Java virtual machine. * This method creates one class loader and defines all modules to that * class loader. The {@link ClassLoader#getParent() parent} of each class * loader is the given parent class loader. This method works exactly as * specified by the static {@link * #defineModulesWithOneLoader(Configuration,List,ClassLoader) * defineModulesWithOneLoader} method when invoked with this layer as the * parent. In other words, if this layer is {@code thisLayer} then this * method is equivalent to invoking: * {@code
* ModuleLayer.defineModulesWithOneLoader(cf, List.of(thisLayer), parentLoader).layer();
* }
*
* @param cf
* The configuration for the layer
* @param parentLoader
* The parent class loader for the class loader created by this
* method; may be {@code null} for the bootstrap class loader
*
* @return The newly created layer
*
* @throws IllegalArgumentException
* If the given configuration has more than one parent or the parent
* of the configuration is not the configuration for this layer
* @throws LayerInstantiationException
* If the layer cannot be created for any of the reasons specified
* by the static {@code defineModulesWithOneLoader} method
* @throws SecurityException
* If {@code RuntimePermission("createClassLoader")} or
* {@code RuntimePermission("getClassLoader")} is denied by
* the security manager
*
* @see #findLoader
*/
public ModuleLayer defineModulesWithOneLoader(Configuration cf,
ClassLoader parentLoader) {
return defineModulesWithOneLoader(cf, List.of(this), parentLoader).layer();
}
/**
* Creates a new module layer, with this layer as its parent, by defining the
* modules in the given {@code Configuration} to the Java virtual machine.
* Each module is defined to its own {@link ClassLoader} created by this
* method. The {@link ClassLoader#getParent() parent} of each class loader
* is the given parent class loader. This method works exactly as specified
* by the static {@link
* #defineModulesWithManyLoaders(Configuration,List,ClassLoader)
* defineModulesWithManyLoaders} method when invoked with this layer as the
* parent. In other words, if this layer is {@code thisLayer} then this
* method is equivalent to invoking:
* {@code
* ModuleLayer.defineModulesWithManyLoaders(cf, List.of(thisLayer), parentLoader).layer();
* }
*
* @param cf
* The configuration for the layer
* @param parentLoader
* The parent class loader for each of the class loaders created by
* this method; may be {@code null} for the bootstrap class loader
*
* @return The newly created layer
*
* @throws IllegalArgumentException
* If the given configuration has more than one parent or the parent
* of the configuration is not the configuration for this layer
* @throws LayerInstantiationException
* If the layer cannot be created for any of the reasons specified
* by the static {@code defineModulesWithManyLoaders} method
* @throws SecurityException
* If {@code RuntimePermission("createClassLoader")} or
* {@code RuntimePermission("getClassLoader")} is denied by
* the security manager
*
* @see #findLoader
*/
public ModuleLayer defineModulesWithManyLoaders(Configuration cf,
ClassLoader parentLoader) {
return defineModulesWithManyLoaders(cf, List.of(this), parentLoader).layer();
}
/**
* Creates a new module layer, with this layer as its parent, by defining the
* modules in the given {@code Configuration} to the Java virtual machine.
* Each module is mapped, by name, to its class loader by means of the
* given function. This method works exactly as specified by the static
* {@link #defineModules(Configuration,List,Function) defineModules}
* method when invoked with this layer as the parent. In other words, if
* this layer is {@code thisLayer} then this method is equivalent to
* invoking:
* {@code
* ModuleLayer.defineModules(cf, List.of(thisLayer), clf).layer();
* }
*
* @param cf
* The configuration for the layer
* @param clf
* The function to map a module name to a class loader
*
* @return The newly created layer
*
* @throws IllegalArgumentException
* If the given configuration has more than one parent or the parent
* of the configuration is not the configuration for this layer
* @throws LayerInstantiationException
* If the layer cannot be created for any of the reasons specified
* by the static {@code defineModules} method
* @throws SecurityException
* If {@code RuntimePermission("getClassLoader")} is denied by
* the security manager
*/
public ModuleLayer defineModules(Configuration cf,
FunctionThe class loader created by this method implements direct * delegation when loading classes from modules. If the {@link * ClassLoader#loadClass(String, boolean) loadClass} method is invoked to * load a class then it uses the package name of the class to map it to a * module. This may be a module in this layer and hence defined to the same * class loader. It may be a package in a module in a parent layer that is * exported to one or more of the modules in this layer. The class * loader delegates to the class loader of the module, throwing {@code * ClassNotFoundException} if not found by that class loader. * When {@code loadClass} is invoked to load classes that do not map to a * module then it delegates to the parent class loader.
* *The class loader created by this method locates resources * ({@link ClassLoader#getResource(String) getResource}, {@link * ClassLoader#getResources(String) getResources}, and other resource * methods) in all modules in the layer before searching the parent class * loader.
* *Attempting to create a layer with all modules defined to the same * class loader can fail for the following reasons: * *
Overlapping packages: Two or more modules in the * configuration have the same package.
Split delegation: The resulting class loader would * need to delegate to more than one class loader in order to load * classes in a specific package.
In addition, a layer cannot be created if the configuration contains * a module named "{@code java.base}", or a module contains a package named * "{@code java}" or a package with a name starting with "{@code java.}".
* *If there is a security manager then the class loader created by * this method will load classes and resources with privileges that are * restricted by the calling context of this method.
* * @param cf * The configuration for the layer * @param parentLayers * The list of parent layers in search order * @param parentLoader * The parent class loader for the class loader created by this * method; may be {@code null} for the bootstrap class loader * * @return A controller that controls the newly created layer * * @throws IllegalArgumentException * If the parent(s) of the given configuration do not match the * configuration of the parent layers, including order * @throws LayerInstantiationException * If all modules cannot be defined to the same class loader for any * of the reasons listed above * @throws SecurityException * If {@code RuntimePermission("createClassLoader")} or * {@code RuntimePermission("getClassLoader")} is denied by * the security manager * * @see #findLoader */ public static Controller defineModulesWithOneLoader(Configuration cf, ListThe class loaders created by this method implement direct * delegation when loading classes from modules. If the {@link * ClassLoader#loadClass(String, boolean) loadClass} method is invoked to * load a class then it uses the package name of the class to map it to a * module. The package may be in the module defined to the class loader. * The package may be exported by another module in this layer to the * module defined to the class loader. It may be in a package exported by a * module in a parent layer. The class loader delegates to the class loader * of the module, throwing {@code ClassNotFoundException} if not found by * that class loader. When {@code loadClass} is invoked to load a class * that does not map to a module then it delegates to the parent class * loader.
* *The class loaders created by this method locate resources * ({@link ClassLoader#getResource(String) getResource}, {@link * ClassLoader#getResources(String) getResources}, and other resource * methods) in the module defined to the class loader before searching * the parent class loader.
* *If there is a security manager then the class loaders created by * this method will load classes and resources with privileges that are * restricted by the calling context of this method.
* * @param cf * The configuration for the layer * @param parentLayers * The list of parent layers in search order * @param parentLoader * The parent class loader for each of the class loaders created by * this method; may be {@code null} for the bootstrap class loader * * @return A controller that controls the newly created layer * * @throws IllegalArgumentException * If the parent(s) of the given configuration do not match the * configuration of the parent layers, including order * @throws LayerInstantiationException * If the layer cannot be created because the configuration contains * a module named "{@code java.base}" or a module contains a package * named "{@code java}" or a package with a name starting with * "{@code java.}" * * @throws SecurityException * If {@code RuntimePermission("createClassLoader")} or * {@code RuntimePermission("getClassLoader")} is denied by * the security manager * * @see #findLoader */ public static Controller defineModulesWithManyLoaders(Configuration cf, ListThe class loader delegation implemented by the class loaders must * respect module readability. The class loaders should be * {@link ClassLoader#registerAsParallelCapable parallel-capable} so as to * avoid deadlocks during class loading. In addition, the entity creating * a new layer with this method should arrange that the class loaders be * ready to load from these modules before there are any attempts to load * classes or resources.
* *Creating a layer can fail for the following reasons:
* *Two or more modules with the same package are mapped to the * same class loader.
A module is mapped to a class loader that already has a * module of the same name defined to it.
A module is mapped to a class loader that has already * defined types in any of the packages in the module.
In addition, a layer cannot be created if the configuration contains * a module named "{@code java.base}", a configuration contains a module * with a package named "{@code java}" or a package name starting with * "{@code java.}", or the function to map a module name to a class loader * returns {@code null} or the {@linkplain ClassLoader#getPlatformClassLoader() * platform class loader}.
* *If the function to map a module name to class loader throws an error * or runtime exception then it is propagated to the caller of this method. *
* * @apiNote It is implementation specific as to whether creating a layer * with this method is an atomic operation or not. Consequentially it is * possible for this method to fail with some modules, but not all, defined * to the Java virtual machine. * * @param cf * The configuration for the layer * @param parentLayers * The list of parent layers in search order * @param clf * The function to map a module name to a class loader * * @return A controller that controls the newly created layer * * @throws IllegalArgumentException * If the parent(s) of the given configuration do not match the * configuration of the parent layers, including order * @throws LayerInstantiationException * If creating the layer fails for any of the reasons listed above * @throws SecurityException * If {@code RuntimePermission("getClassLoader")} is denied by * the security manager */ public static Controller defineModules(Configuration cf, ListIf there is a security manager then its {@code checkPermission} * method is called with a {@code RuntimePermission("getClassLoader")} * permission to check that the caller is allowed to get access to the * class loader.
* * @apiNote This method does not return an {@code Optional