Package org.jboss.modules

# Class ModuleLoader

java.lang.Object
org.jboss.modules.ModuleLoader

Direct Known Subclasses:
  `ClassifyingModuleLoader`, `DelegatingModuleLoader`

public class ModuleLoader extends Object
A repository for modules, from which a module may be loaded by identifier. Module loaders may additionally delegate to one or more other module loaders.

Author:
  David M. Lloyd, John Bailey, Richard Opalka, Jason T. Greene

## Field Summary

Fields
Modifier and Type
Field
Description
`static final ModuleFinder[]`
`NO_FINDERS`
A constant representing zero module finders.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`ModuleLoader()`
Construct a new instance.
``
`ModuleLoader(ModuleFinder finder)`
Construct a new instance.
``
`ModuleLoader(ModuleFinder[] finders)`
Construct a new instance.

## Method Summary

Modifier and Type
Method
Description
`protected final Module`
`findLoadedModuleLocal(String name)`
Find an already-loaded module, returning `null` if the module isn't currently loaded.
`protected final Module`
`findLoadedModuleLocal(ModuleIdentifier identifier)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `findLoadedModuleLocal(String)` instead.
`protected ModuleSpec`
`findModule(String name)`
Find a Module's specification in this ModuleLoader by its name.
`protected ModuleSpec`
`findModule(ModuleIdentifier moduleIdentifier)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `findModule(String)` instead.
`static ModuleLoader`
`forClass(Class<?> clazz)`
Get the module loader for a class.
`static ModuleLoader`
`forClassLoader(ClassLoader classLoader)`
Get the module loader for a class loader.
`protected DependencySpec[]`
`getDependencies(Module module)`
Get the current dependency list for a module which was defined by this module loader, without any access checks.
`protected final ModuleFinder[]`
`getFinders()`
Get the module finders configured for this module loader.
`String`
`getModuleDescription(Module module)`
Get a string representation of the given module, used in debug output and stack traces.
`static void`
`installMBeanServer()`
Install JBoss Modules MBeans.
`final Iterator<String>`
`iterateModules(String baseName, boolean recursive)`
Iterate the modules which can be located via this module loader.
`final Iterator<ModuleIdentifier>`
`iterateModules(ModuleIdentifier baseIdentifier, boolean recursive)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `iterateModules(String, boolean)` instead.
`final Module`
`loadModule(String name)`
Load a module based on an identifier.
`final Module`
`loadModule(ModuleIdentifier identifier)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `loadModule(String)` instead.
`protected final Module`
`loadModuleLocal(String name)`
Try to load a module from this module loader.
`protected final Module`
`loadModuleLocal(ModuleIdentifier moduleIdentifier)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `loadModuleLocal(String)` instead.
`protected Module`
`preloadExportedModule(String name)`
Preload an "exported" module based on an identifier.
`protected Module`
`preloadExportedModule(ModuleIdentifier identifier)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `preloadModule(String)` instead.
`protected Module`
`preloadModule(String name)`
Preload a module based on an identifier.
`protected static Module`
`preloadModule(String name, ModuleLoader moduleLoader)`
Utility method to delegate to another module loader, accessible from subclasses.
`protected Module`
`preloadModule(ModuleIdentifier identifier)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `preloadModule(String)` instead.
`protected static Module`
`preloadModule(ModuleIdentifier identifier, ModuleLoader moduleLoader)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `preloadModule(String, ModuleLoader)` instead.
`protected void`
`refreshResourceLoaders(Module module)`
Refreshes the paths provided by resource loaders associated with the specified Module.
`protected void`
`relink(Module module)`
Relinks the dependencies associated with the specified Module.
`protected void`
`setAndRefreshResourceLoaders(Module module, Collection<ResourceLoaderSpec> loaders)`
Replaces the resources loaders for the specified module and refreshes the internal path list that is derived from the loaders.
`protected void`
`setAndRelinkDependencies(Module module, List<DependencySpec> dependencies)`
Replaces the dependencies for the specified module and relinks against the new modules This is an advanced method that should be used carefully, since it alters a live module.
`String`
`toString()`
Get the string representation of this module loader.
`protected final boolean`
`unloadModuleLocal(String moduleId, Module module)`
Unload a module from this module loader.
`protected final void`
`unloadModuleLocal(Module module)`
Deprecated.
use `unloadModuleLocal(String,Module)` instead

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Field Details

### NO_FINDERS

public static final ModuleFinder[] NO_FINDERS
A constant representing zero module finders.

## Constructor Details

### ModuleLoader

protected ModuleLoader()
Construct a new instance.

### ModuleLoader

public ModuleLoader(ModuleFinder[] finders)
Construct a new instance.

Parameters:
  `finders` - the module finders to search, in order

### ModuleLoader

public ModuleLoader(ModuleFinder finder)
Construct a new instance.

Parameters:
  `finder` - the single module finder to search (must not be `null`)

## Method Details

### forClass

public static ModuleLoader forClass(Class<?> clazz)
Get the module loader for a class.

Parameters:
  `clazz` - the class
Returns:
  the module loader or `null` if the class's class loader does not belong to a module loader.

### forClassLoader

public static ModuleLoader forClassLoader(ClassLoader classLoader)
Get the module loader for a class loader.

Parameters:
  `classLoader` - the class loader
Returns:
  the module loader or `null` if the class loader does not belong to a module loader.

### toString

public String toString()
Get the string representation of this module loader.

Overrides:
  `toString` in class `Object`
Returns:
  the string representation

### getModuleDescription

public String getModuleDescription(Module module)
Get a string representation of the given module, used in debug output and stack traces. This method may be overridden to provide a more detailed description. By default it returns a string consisting of the module's name and version (if any).

Parameters:
  `module` - the module to describe
Returns:
  the description string

### installMBeanServer

public static void installMBeanServer()
Install JBoss Modules MBeans. WARNING: This method is not intended to be called by application code.

### loadModule

@Deprecated(forRemoval=true) public final Module loadModule(ModuleIdentifier identifier) throws ModuleLoadException
Deprecated, for removal: This API element is subject to removal in a future version.
Use `loadModule(String)` instead.
Load a module based on an identifier. This method delegates to `preloadModule(String)` and then links the returned module if necessary.

Parameters:
  `identifier` - The module identifier
Returns:
  The loaded Module
Throws:
  `ModuleLoadException` - if the Module can not be loaded

### loadModule

public final Module loadModule(String name) throws ModuleLoadException
Load a module based on an identifier. This method delegates to `preloadModule(String)` and then links the returned module if necessary.

Parameters:
  `name` - The module name
Returns:
  The loaded Module
Throws:
  `ModuleLoadException` - if the Module can not be loaded

### iterateModules

@Deprecated(forRemoval=true) public final Iterator<ModuleIdentifier> iterateModules(ModuleIdentifier baseIdentifier, boolean recursive)
Deprecated, for removal: This API element is subject to removal in a future version.
Use `iterateModules(String, boolean)` instead.
Iterate the modules which can be located via this module loader.

Parameters:
  `baseIdentifier` - the identifier to start with, or `null` to iterate all modules
  `recursive` - `true` to find recursively nested modules, `false` to only find immediately nested modules
Returns:
  an iterator for the modules in this module finder
Throws:
  `SecurityException` - if the caller does not have permission to iterate module loaders

### iterateModules

public final Iterator<String> iterateModules(String baseName, boolean recursive)
Iterate the modules which can be located via this module loader.

Parameters:
  `baseName` - the identifier to start with, or `null` to iterate all modules; ignored if this module loader does not have a concept of nested modules
  `recursive` - `true` to find recursively nested modules, `false` to only find immediately nested modules; ignored if this module finder does not have a concept of nested modules
Returns:
  an iterator for the modules in this module finder
Throws:
  `SecurityException` - if the caller does not have permission to iterate module loaders

### preloadModule

@Deprecated(forRemoval=true) protected Module preloadModule(ModuleIdentifier identifier) throws ModuleLoadException
Deprecated, for removal: This API element is subject to removal in a future version.
Use `preloadModule(String)` instead.
This compatibility method just calls `preloadModule(methodIdentifier.toString())` and is usually not used; if however a legacy subclass overrides this method, then it will be called instead of `preloadModule(String)`, and that method will redirect to this one.

Parameters:
  `identifier` - the module identifier (must not be `null`)
Returns:
  the load result, or `null` if the module is not found
Throws:
  `ModuleLoadException` - if an error occurs

### preloadModule

protected Module preloadModule(String name) throws ModuleLoadException
Preload a module based on an identifier. By default, delegation is only done for system and this method otherwise simply invokes `loadModuleLocal(String)`. A delegating module loader may delegate to the appropriate module loader based on loader-specific criteria (via the `preloadModule(String, ModuleLoader)` method).

Parameters:
  `name` - the module identifier
Returns:
  the load result, or `null` if the module is not found
Throws:
  `ModuleLoadException` - if an error occurs

### preloadExportedModule

protected Module preloadExportedModule(String name) throws ModuleLoadException
Preload an "exported" module based on an identifier. By default this simply delegates to `preloadModule(String)`.

Parameters:
  `name` - the module name
Returns:
  the load result, or `null` if the module is not found
Throws:
  `ModuleLoadException` - if an error occurs

### preloadExportedModule

@Deprecated(forRemoval=true) protected Module preloadExportedModule(ModuleIdentifier identifier) throws ModuleLoadException
Deprecated, for removal: This API element is subject to removal in a future version.
Use `preloadModule(String)` instead.
Preload an "exported" module based on an identifier. By default this simply delegates to `preloadModule(String)`.

Parameters:
  `identifier` - the module identifier
Returns:
  the load result, or `null` if the module is not found
Throws:
  `ModuleLoadException` - if an error occurs

### preloadModule

protected static Module preloadModule(String name, ModuleLoader moduleLoader) throws ModuleLoadException
Utility method to delegate to another module loader, accessible from subclasses. The delegate module loader will be queried for exported modules only.

Parameters:
  `name` - the module name
  `moduleLoader` - the module loader to delegate to
Returns:
  the delegation result
Throws:
  `ModuleLoadException` - if an error occurs

### preloadModule

@Deprecated(forRemoval=true) protected static Module preloadModule(ModuleIdentifier identifier, ModuleLoader moduleLoader) throws ModuleLoadException
Deprecated, for removal: This API element is subject to removal in a future version.
Use `preloadModule(String, ModuleLoader)` instead.
Utility method to delegate to another module loader, accessible from subclasses. The delegate module loader will be queried for exported modules only.

Parameters:
  `identifier` - the module identifier
  `moduleLoader` - the module loader to delegate to
Returns:
  the delegation result
Throws:
  `ModuleLoadException` - if an error occurs

### loadModuleLocal

@Deprecated(forRemoval=true) protected final Module loadModuleLocal(ModuleIdentifier moduleIdentifier) throws ModuleLoadException
Deprecated, for removal: This API element is subject to removal in a future version.
Use `loadModuleLocal(String)` instead.
Try to load a module from this module loader. Returns `null` if the module is not found. The returned module may not yet be resolved. The returned module may have a different name than the given identifier if the identifier is an alias for another module.

Parameters:
  `moduleIdentifier` - the module identifier
Returns:
  the module
Throws:
  `ModuleLoadException` - if an error occurs while loading the module

### loadModuleLocal

protected final Module loadModuleLocal(String name) throws ModuleLoadException
Try to load a module from this module loader. Returns `null` if the module is not found. The returned module may not yet be resolved. The returned module may have a different name than the given identifier if the identifier is an alias for another module.

Parameters:
  `name` - the module name
Returns:
  the module
Throws:
  `ModuleLoadException` - if an error occurs while loading the module

### findLoadedModuleLocal

@Deprecated(forRemoval=true) protected final Module findLoadedModuleLocal(ModuleIdentifier identifier)
Deprecated, for removal: This API element is subject to removal in a future version.
Use `findLoadedModuleLocal(String)` instead.
Find an already-loaded module, returning `null` if the module isn't currently loaded. May block while the loaded state of the module is in question (if the module is being concurrently loaded from another thread, for example).

Parameters:
  `identifier` - the module identifier
Returns:
  the module, or `null` if it wasn't found

### findLoadedModuleLocal

protected final Module findLoadedModuleLocal(String name)
Find an already-loaded module, returning `null` if the module isn't currently loaded. May block while the loaded state of the module is in question (if the module is being concurrently loaded from another thread, for example).

Parameters:
  `name` - the module identifier
Returns:
  the module, or `null` if it wasn't found

### unloadModuleLocal

@Deprecated protected final void unloadModuleLocal(Module module) throws SecurityException
Deprecated.
use `unloadModuleLocal(String,Module)` instead
Unload a module from this module loader. Note that this has no effect on existing modules which refer to the module being unloaded. Also, only modules from the current module loader can be unloaded. Unloading the same module more than once has no additional effect. This method only removes the mapping for the module; any running threads which are currently accessing or linked to the module will continue to function, however attempts to load this module will fail until a new module is loaded with the same name. Once this happens, if all references to the previous module are not cleared, the same module may be loaded more than once, causing possible class duplication and class cast exceptions if proper care is not taken.

Parameters:
  `module` - the module to unload
Throws:
  `SecurityException` - if an attempt is made to unload a module which does not belong to this module loader
  `SecurityException` - if the module was not defined by this module loader

### unloadModuleLocal

protected final boolean unloadModuleLocal(String moduleId, Module module) throws SecurityException
Unload a module from this module loader. Note that this has no effect on existing modules which refer to the module being unloaded. Also, only modules from the current module loader can be unloaded. Unloading the same module more than once has no additional effect. This method only removes the mapping for the module; any running threads which are currently accessing or linked to the module will continue to function, however attempts to load this module will fail until a new module is loaded with the same name. Once this happens, if all references to the previous module are not cleared, the same module may be loaded more than once, causing possible class duplication and class cast exceptions if proper care is not taken.

If the given `moduleName` is an alias of the given `module` then only alias mapping to `module` is removed. Aliased `module` with its canonical name and other aliases mapping is left intact.

If the given `moduleName` is the canonical `module` name then all its alias plus canonical `moduleName` association mappings are removed.

Parameters:
  `moduleId` - the module identifier
  `module` - the module to unload
Returns:
  true iff module was unloaded
Throws:
  `SecurityException` - if an attempt is made to unload a module which does not belong to this module loader
  `SecurityException` - if the module was not defined by this module loader

### findModule

@Deprecated(forRemoval=true) protected ModuleSpec findModule(ModuleIdentifier moduleIdentifier) throws ModuleLoadException
Deprecated, for removal: This API element is subject to removal in a future version.
Use `findModule(String)` instead.
This compatibility method just calls `findModule(methodIdentifier.toString())` and is usually not used; if however a legacy subclass overrides this method, then it will be called instead of `findModule(String)`, and that method will redirect to this one.

Parameters:
  `moduleIdentifier` - the module identifier
Returns:
  the module specification
Throws:
  `ModuleLoadException`

### findModule

protected ModuleSpec findModule(String name) throws ModuleLoadException
Find a Module's specification in this ModuleLoader by its name. This can be overriden by sub-classes to implement the Module loading strategy for this loader. The default implementation iterates the module finders provided during construction.

If no module is found in this module loader with the given identifier, then this method should return `null`. If the module is found but some problem occurred (for example, a transitive dependency failed to load) then this method should throw a `ModuleLoadException` of the relevant type.

Parameters:
  `name` - the module name
Returns:
  the module specification, or `null` if no module is found with the given identifier
Throws:
  `ModuleLoadException` - if any problems occur finding the module

### getFinders

protected final ModuleFinder[] getFinders()
Get the module finders configured for this module loader.

Returns:
  the module finders

### refreshResourceLoaders

protected void refreshResourceLoaders(Module module)
Refreshes the paths provided by resource loaders associated with the specified Module. This is an advanced method that is intended to be called on modules that have a resource loader implementation that has changed and is returning different paths.

Parameters:
  `module` - the module to refresh
Throws:
  `SecurityException` - if the module was not defined by this module loader, or if the module loader does not have the required permissions associated with it

### setAndRefreshResourceLoaders

protected void setAndRefreshResourceLoaders(Module module, Collection<ResourceLoaderSpec> loaders)
Replaces the resources loaders for the specified module and refreshes the internal path list that is derived from the loaders. This is an advanced method that should be used carefully, since it alters a live module. Modules that import resources from the specified module will not automatically be updated to reflect the change. For this to occur `relink(Module)` must be called on all of them.

Parameters:
  `module` - the module to update and refresh
  `loaders` - the new collection of loaders the module should use
Throws:
  `SecurityException` - if the module was not defined by this module loader, or if the module loader does not have the required permissions associated with it

### relink

protected void relink(Module module) throws ModuleLoadException
Relinks the dependencies associated with the specified Module. This is an advanced method that is intended to be called on all modules that directly or indirectly import dependencies that are re-exported by a module that has recently been updated and relinked via `setAndRelinkDependencies(Module, java.util.List)`.

Parameters:
  `module` - the module to relink
Throws:
  `ModuleLoadException` - if relinking failed
  `SecurityException` - if the module was not defined by this module loader, or if the module loader does not have the required permissions associated with it

### setAndRelinkDependencies

protected void setAndRelinkDependencies(Module module, List<DependencySpec> dependencies) throws ModuleLoadException
Replaces the dependencies for the specified module and relinks against the new modules This is an advanced method that should be used carefully, since it alters a live module. Modules that import dependencies that are re-exported from the specified module will not automatically be updated to reflect the change. For this to occur `relink(Module)` must be called on all of them.

Parameters:
  `module` - the module to update and relink
  `dependencies` - the new dependency list
Throws:
  `ModuleLoadException` - if relinking failed
  `SecurityException` - if the module was not defined by this module loader, or if the module loader does not have the required permissions associated with it

### getDependencies

protected DependencySpec[] getDependencies(Module module)
Get the current dependency list for a module which was defined by this module loader, without any access checks.

Returns:
  the current dependency list for the module
Throws:
  `SecurityException` - if the module was not defined by this module loader