Package Summary  Overview Summary

class:Layer [CHANGED]

 

  • public final class Layer
extends Object
    A layer of modules in the Java virtual machine.

    A layer is created from a graph of modules that is the Configuration and a function that maps each module to a ClassLoader. Creating a layer informs the Java virtual machine about the classes that may be loaded from modules so that the Java virtual machine knows which module that each class is a member of. Each layer, except the empty layer, has a parent.

    Creating a layer creates a Module object for each ResolvedModule in the configuration. For each resolved module that is read, the Modulereads the corresponding run-time Module, which may be in the same layer or a parent layer. The Moduleexports the packages described by its ModuleDescriptor.

    The defineModulesWithOneLoader and defineModulesWithManyLoaders methods provide convenient ways to create a Layer where all modules are mapped to a single class loader or where each module is mapped to its own class loader. The defineModules method is for more advanced cases where modules are mapped to custom class loaders by means of a function specified to the method.

    A Java virtual machine has at least one non-empty layer, the boot layer, that is created when the Java virtual machine is started. The system modules , includingboot layer contains module java.base , areand is the only layer in the boot layerJava virtual machine with a module named "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 avaJava virtual machine. The boot layer will often be the parent when creating additional layers.

    As when creating a Configuration, automatic modules receive special treatment when creating a layer. An automatic module is created in the Java virtual machine as a Module that reads every unnamed Module in the Java virtual machine.

    Unless otherwise specified, passing a null argument to a method in this class causes a NullPointerException to be thrown.

    Example usage:

    This example creates a configuration by resolving a module named "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. 

    
     ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);

     Layer parent = Layer.boot();

     Configuration cf = parent.configuration()
         .resolveRequires(finder, ModuleFinder.emptyof(), Set.of("myapp"));

     ClassLoader scl = ClassLoader.getSystemClassLoader();

     Layer layer = parent.defineModulesWithOneLoader(cf, scl);

     Class<?> c = layer.findLoader("myapp").loadClass("app.Main");
    Since:
    9
    See Also:
    Module.getLayer() 

  • public final class Layer
extends Object
    A layer of modules in the Java virtual machine.

    A layer is created from a graph of modules that is the Configuration and a function that maps each module to a ClassLoader. Creating a layer informs the Java virtual machine about the classes that may be loaded from modules so that the Java virtual machine knows which module that each class is a member of. Each layer, except the empty layer, has a parent.

    Creating a layer creates a Module object for each ResolvedModule in the configuration. For each resolved module that is read, the Modulereads the corresponding run-time Module, which may be in the same layer or a parent layer. The Moduleexports the packages described by its ModuleDescriptor.

    The defineModulesWithOneLoader and defineModulesWithManyLoaders methods provide convenient ways to create a Layer where all modules are mapped to a single class loader or where each module is mapped to its own class loader. The defineModules method is for more advanced cases where modules are mapped to custom class loaders by means of a function specified to the method.

    A Java virtual machine has at least one non-empty layer, the boot layer, that is created when the Java virtual machine is started. The system modules , including java.base, are in the boot layer. The modules in the boot layer are mapped to the bootstrap class loader and other class loaders that are built-in into the ava virtual machine. The boot layer will often be the parent when creating additional layers.

    As when creating a Configuration, automatic modules receive special treatment when creating a layer. An automatic module is created in the Java virtual machine as a Module that reads every unnamed Module in the Java virtual machine.

    Unless otherwise specified, passing a null argument to a method in this class causes a NullPointerException to be thrown.

    Example usage:

    This example creates a configuration by resolving a module named "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. 

    
     ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);

     Layer parent = Layer.boot();

     Configuration cf = parent.configuration()
         .resolveRequires(finder, ModuleFinder.empty(), Set.of("myapp"));

     ClassLoader scl = ClassLoader.getSystemClassLoader();

     Layer layer = parent.defineModulesWithOneLoader(cf, scl);

     Class<?> c = layer.findLoader("myapp").loadClass("app.Main");
    Since:
    9
    See Also:
    Module.getLayer() 

  • public final class Layer
extends Object
    A layer of modules in the Java virtual machine.

    A layer is created from a graph of modules that is the Configuration and a function that maps each module to a ClassLoader. Creating a layer informs the Java virtual machine about the classes that may be loaded from modules so that the Java virtual machine knows which module that each class is a member of. Each layer, except the empty layer, has a parent.

    Creating a layer creates a Module object for each ResolvedModule in the configuration. For each resolved module that is read, the Modulereads the corresponding run-time Module, which may be in the same layer or a parent layer. The Moduleexports the packages described by its ModuleDescriptor.

    The defineModulesWithOneLoader and defineModulesWithManyLoaders methods provide convenient ways to create a Layer where all modules are mapped to a single class loader or where each module is mapped to its own class loader. The defineModules method is for more advanced cases where modules are mapped to custom class loaders by means of a function specified to the method.

    A Java virtual machine has at least one non-empty layer, the boot layer, that is created when the Java virtual machine is started. The boot layer contains module java.base and is the only layer in the Java virtual machine with a module named "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 parent when creating additional layers.

    As when creating a Configuration, automatic modules receive special treatment when creating a layer. An automatic module is created in the Java virtual machine as a Module that reads every unnamed Module in the Java virtual machine.

    Unless otherwise specified, passing a null argument to a method in this class causes a NullPointerException to be thrown.

    Example usage:

    This example creates a configuration by resolving a module named "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. 

    
     ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);

     Layer parent = Layer.boot();

     Configuration cf = parent.configuration()
         .resolveRequires(finder, ModuleFinder.of(), Set.of("myapp"));

     ClassLoader scl = ClassLoader.getSystemClassLoader();

     Layer layer = parent.defineModulesWithOneLoader(cf, scl);

     Class<?> c = layer.findLoader("myapp").loadClass("app.Main");
    Since:
    9
    See Also:
    Module.getLayer()

method:defineModulesWithOneLoader(java.lang.module.Configuration, java.lang.ClassLoader) [CHANGED]

  • defineModulesWithOneLoader

    public Layer defineModulesWithOneLoader(Configuration cf,
                                        ClassLoader parentLoader)
    Creates a new layer, with this layer as its parent, by defining the modules in the given Configuration to the Java virtual machine. This method creates one class loader and defines all modules to that class loader.

    The class loader created by this method implements direct delegation when loading types from modules. When its 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 ClassNotFoundException if not found by that class loader. When loadClass is invoked to load classes that do not map to a module then it delegates to 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 (exported or concealed).

    • Split delegation : The resulting class loader would need to delegate to more than one class loader in order to load types in a specific package.

    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.

    Parameters:
    cf - The configuration for the layer
    parentLoader - The parent class loader for the class loader created by this method; may be null for the bootstrap class loader
    Returns:
    The newly created layer
    Throws:
    IllegalArgumentException - If the parent of the given configuration is not the configuration for this layer
    LayerInstantiationException - If all modules cannot be defined to the same class loader for any of the reasons listed above or the layer cannot be created because the configuration contains a module named "java.base"
    SecurityException - If RuntimePermission("createClassLoader") or RuntimePermission("getClassLoader") is denied by the security manager
    See Also:
    findLoader(java.lang.String)

  • defineModulesWithOneLoader

    public Layer defineModulesWithOneLoader(Configuration cf,
                                        ClassLoader parentLoader)
    Creates a new layer, with this layer as its parent, by defining the modules in the given Configuration to the Java virtual machine. This method creates one class loader and defines all modules to that class loader.

    The class loader created by this method implements direct delegation when loading types from modules. When its 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 ClassNotFoundException if not found by that class loader. When loadClass is invoked to load classes that do not map to a module then it delegates to 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 (exported or concealed).

    • Split delegation : The resulting class loader would need to delegate to more than one class loader in order to load types in a specific package.

    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.

    Parameters:
    cf - The configuration for the layer
    parentLoader - The parent class loader for the class loader created by this method; may be null for the bootstrap class loader
    Returns:
    The newly created layer
    Throws:
    IllegalArgumentException - If the parent of the given configuration is not the configuration for this layer
    LayerInstantiationException - If all modules cannot be defined to the same class loader for any of the reasons listed above
    SecurityException - If RuntimePermission("createClassLoader") or RuntimePermission("getClassLoader") is denied by the security manager
    See Also:
    findLoader(java.lang.String)

  • defineModulesWithOneLoader

    public Layer defineModulesWithOneLoader(Configuration cf,
                                        ClassLoader parentLoader)
    Creates a new layer, with this layer as its parent, by defining the modules in the given Configuration to the Java virtual machine. This method creates one class loader and defines all modules to that class loader.

    The class loader created by this method implements direct delegation when loading types from modules. When its 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 ClassNotFoundException if not found by that class loader. When loadClass is invoked to load classes that do not map to a module then it delegates to 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 (exported or concealed).

    • Split delegation : The resulting class loader would need to delegate to more than one class loader in order to load types in a specific package.

    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.

    Parameters:
    cf - The configuration for the layer
    parentLoader - The parent class loader for the class loader created by this method; may be null for the bootstrap class loader
    Returns:
    The newly created layer
    Throws:
    IllegalArgumentException - If the parent of the given configuration is not the configuration for this layer
    LayerInstantiationException - If all modules cannot be defined to the same class loader for any of the reasons listed above or the layer cannot be created because the configuration contains a module named "java.base"
    SecurityException - If RuntimePermission("createClassLoader") or RuntimePermission("getClassLoader") is denied by the security manager
    See Also:
    findLoader(java.lang.String)

method:defineModulesWithManyLoaders(java.lang.module.Configuration, java.lang.ClassLoader) [CHANGED]

  • defineModulesWithManyLoaders

    public Layer defineModulesWithManyLoaders(Configuration cf,
                                          ClassLoader parentLoader)
    Creates a new layer, with this layer as its parent, by defining the modules in the given Configuration to the Java virtual machine. Each module is defined to its own ClassLoader created by this method. The parent of each class loader is the given parent class loader.

    The class loaders created by this method implement direct delegation when loading types from modules. When 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 ClassNotFoundException if not found by that class loader. When loadClass is invoked to load classes that do not map to a module then it delegates to 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.

    Parameters:
    cf - The configuration for the layer
    parentLoader - The parent class loader for each of the class loaders created by this method; may be null for the bootstrap class loader
    Returns:
    The newly created layer
    Throws:
    IllegalArgumentException - If the parent of the given configuration is not the configuration for this layer
    LayerInstantiationException - If the layer cannot be created because the configuration contains a module named "java.base"
    SecurityException - If RuntimePermission("createClassLoader") or RuntimePermission("getClassLoader") is denied by the security manager
    See Also:
    findLoader(java.lang.String)

  • defineModulesWithManyLoaders

    public Layer defineModulesWithManyLoaders(Configuration cf,
                                          ClassLoader parentLoader)
    Creates a new layer, with this layer as its parent, by defining the modules in the given Configuration to the Java virtual machine. Each module is defined to its own ClassLoader created by this method. The parent of each class loader is the given parent class loader.

    The class loaders created by this method implement direct delegation when loading types from modules. When 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 ClassNotFoundException if not found by that class loader. When loadClass is invoked to load classes that do not map to a module then it delegates to 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.

    Parameters:
    cf - The configuration for the layer
    parentLoader - The parent class loader for each of the class loaders created by this method; may be null for the bootstrap class loader
    Returns:
    The newly created layer
    Throws:
    IllegalArgumentException - If the parent of the given configuration is not the configuration for this layer
    SecurityException - If RuntimePermission("createClassLoader") or RuntimePermission("getClassLoader") is denied by the security manager
    See Also:
    findLoader(java.lang.String)

  • defineModulesWithManyLoaders

    public Layer defineModulesWithManyLoaders(Configuration cf,
                                          ClassLoader parentLoader)
    Creates a new layer, with this layer as its parent, by defining the modules in the given Configuration to the Java virtual machine. Each module is defined to its own ClassLoader created by this method. The parent of each class loader is the given parent class loader.

    The class loaders created by this method implement direct delegation when loading types from modules. When 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 ClassNotFoundException if not found by that class loader. When loadClass is invoked to load classes that do not map to a module then it delegates to 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.

    Parameters:
    cf - The configuration for the layer
    parentLoader - The parent class loader for each of the class loaders created by this method; may be null for the bootstrap class loader
    Returns:
    The newly created layer
    Throws:
    IllegalArgumentException - If the parent of the given configuration is not the configuration for this layer
    LayerInstantiationException - If the layer cannot be created because the configuration contains a module named "java.base"
    SecurityException - If RuntimePermission("createClassLoader") or RuntimePermission("getClassLoader") is denied by the security manager
    See Also:
    findLoader(java.lang.String)

method:defineModules(java.lang.module.Configuration, java.util.function.Function) [CHANGED]

  • defineModules

    public Layer defineModules(Configuration cf,
                           Function<String,ClassLoader> clf)
    Creates a new layer, with this layer as its parent, by defining the modules in the given Configuration to the Java virtual machine. Each module is mapped, by name, to its class loader by means of the given function. The class loader delegation implemented by these class loaders must respect module readability. In addition, the caller needs to arrange that the class loaders are ready to load from these module 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 (exported or concealed) 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.

    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.

    API Note:
    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 Java virtual machine.
    Parameters:
    cf - The configuration for the layer
    clf - The function to map a module name to a class loader
    Returns:
    The newly created layer
    Throws:
    IllegalArgumentException - If the parent of the given configuration is not the configuration for this layer
    LayerInstantiationException - If creating the Layer fails for any of the reasons listed above or the layer cannot be created because the configuration contains a module named "java.base"
    SecurityException - If RuntimePermission("getClassLoader") is denied by the security manager

  • defineModules

    public Layer defineModules(Configuration cf,
                           Function<String,ClassLoader> clf)
    Creates a new layer, with this layer as its parent, by defining the modules in the given Configuration to the Java virtual machine. Each module is mapped, by name, to its class loader by means of the given function. The class loader delegation implemented by these class loaders must respect module readability. In addition, the caller needs to arrange that the class loaders are ready to load from these module 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 (exported or concealed) 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.

    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.

    API Note:
    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 Java virtual machine.
    Parameters:
    cf - The configuration for the layer
    clf - The function to map a module name to a class loader
    Returns:
    The newly created layer
    Throws:
    IllegalArgumentException - If the parent of the given configuration is not the configuration for this layer
    LayerInstantiationException - If creating the Layer fails for any of the reasons listed above
    SecurityException - If RuntimePermission("getClassLoader") is denied by the security manager

  • defineModules

    public Layer defineModules(Configuration cf,
                           Function<String,ClassLoader> clf)
    Creates a new layer, with this layer as its parent, by defining the modules in the given Configuration to the Java virtual machine. Each module is mapped, by name, to its class loader by means of the given function. The class loader delegation implemented by these class loaders must respect module readability. In addition, the caller needs to arrange that the class loaders are ready to load from these module 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 (exported or concealed) 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.

    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.

    API Note:
    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 Java virtual machine.
    Parameters:
    cf - The configuration for the layer
    clf - The function to map a module name to a class loader
    Returns:
    The newly created layer
    Throws:
    IllegalArgumentException - If the parent of the given configuration is not the configuration for this layer
    LayerInstantiationException - If creating the Layer fails for any of the reasons listed above or the layer cannot be created because the configuration contains a module named "java.base"
    SecurityException - If RuntimePermission("getClassLoader") is denied by the security manager

method:configuration() [NONE]

  • configuration

    public Configuration configuration()
    Returns the configuration for this layer.
    Returns:
    The configuration for this layer

method:parent() [NONE]

  • parent

    public Optional<Layer> parent()
    Returns this layer's parent unless this is the empty layer , which has no parent.
    Returns:
    This layer's parent

method:modules() [NONE]

  • modules

    public Set<Module> modules()
    Returns a set of the modules in this layer.
    Returns:
    A possibly-empty unmodifiable set of the modules in this layer

method:findModule(java.lang.String) [NONE]

  • findModule

    public Optional<Module> findModule(String name)
    Returns the module with the given name in this layer, or if not in this layer, the parent layer.
    Parameters:
    name - The name of the module to find
    Returns:
    The module with the given name or an empty Optional if there isn't a module with this name in this layer or any parent layer

method:findLoader(java.lang.String) [NONE]

  • findLoader

    public ClassLoader findLoader(String name)
    Returns the ClassLoader for the module with the given name. If a module of the given name is not in this layer then the parent layer is checked.

    If there is a security manager then its checkPermission method is called with a RuntimePermission("getClassLoader") permission to check that the caller is allowed to get access to the class loader.

    API Note:
    This method does not return an Optional<ClassLoader> because `null` must be used to represent the bootstrap class loader.
    Parameters:
    name - The name of the module to find
    Returns:
    The ClassLoader that the module is defined to
    Throws:
    IllegalArgumentException - if a module of the given name is not defined in this layer or any parent of this layer
    SecurityException - if denied by the security manager

method:empty() [NONE]

  • empty

    public static Layer empty()
    Returns the empty layer. There are no modules in the empty layer. It has no parent.
    Returns:
    The empty layer

method:boot() [NONE]

  • boot

    public static Layer boot()
    Returns the boot layer. The boot layer contains at least one module, java.base. Its parent is the empty layer.
    API Note:
    This method returns null during startup and before the boot layer is fully initialized.
    Returns:
    The boot layer