java.lang.Object
org.jboss.modules.ModuleLoader
- Direct Known Subclasses:
ClassifyingModuleLoader
,DelegatingModuleLoader
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
FieldsModifier and TypeFieldDescriptionstatic final ModuleFinder[]
A constant representing zero module finders. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
Construct a new instance.ModuleLoader
(ModuleFinder finder) Construct a new instance.ModuleLoader
(ModuleFinder[] finders) Construct a new instance. -
Method Summary
Modifier and TypeMethodDescriptionprotected final Module
findLoadedModuleLocal
(String name) Find an already-loaded module, returningnull
if the module isn't currently loaded.protected final Module
findLoadedModuleLocal
(ModuleIdentifier identifier) Deprecated.protected ModuleSpec
findModule
(String name) Find a Module's specification in this ModuleLoader by its name.protected ModuleSpec
findModule
(ModuleIdentifier moduleIdentifier) Deprecated.UsefindModule(String)
instead.static ModuleLoader
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[]
Get the module finders configured for this module loader.getModuleDescription
(Module module) Get a string representation of the given module, used in debug output and stack traces.static void
Install JBoss Modules MBeans.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.UseiterateModules(String, boolean)
instead.final Module
loadModule
(String name) Load a module based on an identifier.final Module
loadModule
(ModuleIdentifier identifier) Deprecated.UseloadModule(String)
instead.protected final Module
loadModuleLocal
(String name) Try to load a module from this module loader.protected final Module
loadModuleLocal
(ModuleIdentifier moduleIdentifier) Deprecated.UseloadModuleLocal(String)
instead.protected Module
preloadExportedModule
(String name) Preload an "exported" module based on an identifier.protected Module
preloadExportedModule
(ModuleIdentifier identifier) Deprecated.UsepreloadModule(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.UsepreloadModule(String)
instead.protected static Module
preloadModule
(ModuleIdentifier identifier, ModuleLoader moduleLoader) Deprecated.UsepreloadModule(String, ModuleLoader)
instead.protected void
refreshResourceLoaders
(Module module) Refreshes the paths provided by resource loaders associated with the specified Module.protected void
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.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.useunloadModuleLocal(String,Module)
instead
-
Field Details
-
NO_FINDERS
A constant representing zero module finders.
-
-
Constructor Details
-
ModuleLoader
protected ModuleLoader()Construct a new instance. -
ModuleLoader
Construct a new instance.- Parameters:
finders
- the module finders to search, in order
-
ModuleLoader
Construct a new instance.- Parameters:
finder
- the single module finder to search (must not benull
)
-
-
Method Details
-
forClass
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
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
Get the string representation of this module loader. -
getModuleDescription
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.UseloadModule(String)
instead.Load a module based on an identifier. This method delegates topreloadModule(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
Load a module based on an identifier. This method delegates topreloadModule(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 public final Iterator<ModuleIdentifier> iterateModules(ModuleIdentifier baseIdentifier, boolean recursive) Deprecated.UseiterateModules(String, boolean)
instead.Iterate the modules which can be located via this module loader.- Parameters:
baseIdentifier
- the identifier to start with, ornull
to iterate all modulesrecursive
-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
Iterate the modules which can be located via this module loader.- Parameters:
baseName
- the identifier to start with, ornull
to iterate all modules; ignored if this module loader does not have a concept of nested modulesrecursive
-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.UsepreloadModule(String)
instead.This compatibility method just callspreloadModule(methodIdentifier.toString())
and is usually not used; if however a legacy subclass overrides this method, then it will be called instead ofpreloadModule(String)
, and that method will redirect to this one.- Parameters:
identifier
- the module identifier (must not benull
)- Returns:
- the load result, or
null
if the module is not found - Throws:
ModuleLoadException
- if an error occurs
-
preloadModule
Preload a module based on an identifier. By default, delegation is only done for system and this method otherwise simply invokesloadModuleLocal(String)
. A delegating module loader may delegate to the appropriate module loader based on loader-specific criteria (via thepreloadModule(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
Preload an "exported" module based on an identifier. By default this simply delegates topreloadModule(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 protected Module preloadExportedModule(ModuleIdentifier identifier) throws ModuleLoadException Deprecated.UsepreloadModule(String)
instead.Preload an "exported" module based on an identifier. By default this simply delegates topreloadModule(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 namemoduleLoader
- the module loader to delegate to- Returns:
- the delegation result
- Throws:
ModuleLoadException
- if an error occurs
-
preloadModule
@Deprecated protected static Module preloadModule(ModuleIdentifier identifier, ModuleLoader moduleLoader) throws ModuleLoadException Deprecated.UsepreloadModule(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 identifiermoduleLoader
- the module loader to delegate to- Returns:
- the delegation result
- Throws:
ModuleLoadException
- if an error occurs
-
loadModuleLocal
@Deprecated protected final Module loadModuleLocal(ModuleIdentifier moduleIdentifier) throws ModuleLoadException Deprecated.UseloadModuleLocal(String)
instead.Try to load a module from this module loader. Returnsnull
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
Try to load a module from this module loader. Returnsnull
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.UsefindLoadedModuleLocal(String)
instead.Find an already-loaded module, returningnull
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
Find an already-loaded module, returningnull
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.useunloadModuleLocal(String,Module)
insteadUnload 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 loaderSecurityException
- if the module was not defined by this module loader
-
unloadModuleLocal
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 givenmoduleName
is an alias of the givenmodule
then only alias mapping tomodule
is removed. Aliasedmodule
with its canonical name and other aliases mapping is left intact. If the givenmoduleName
is the canonicalmodule
name then all its alias plus canonicalmoduleName
association mappings are removed.- Parameters:
moduleId
- the module identifiermodule
- 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 loaderSecurityException
- if the module was not defined by this module loader
-
findModule
@Deprecated protected ModuleSpec findModule(ModuleIdentifier moduleIdentifier) throws ModuleLoadException Deprecated.UsefindModule(String)
instead.This compatibility method just callsfindModule(methodIdentifier.toString())
and is usually not used; if however a legacy subclass overrides this method, then it will be called instead offindModule(String)
, and that method will redirect to this one.- Parameters:
moduleIdentifier
- the module identifier- Returns:
- the module specification
- Throws:
ModuleLoadException
-
findModule
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 returnnull
. If the module is found but some problem occurred (for example, a transitive dependency failed to load) then this method should throw aModuleLoadException
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
Get the module finders configured for this module loader.- Returns:
- the module finders
-
refreshResourceLoaders
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
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 occurrelink(Module)
must be called on all of them.- Parameters:
module
- the module to update and refreshloaders
- 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
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 viasetAndRelinkDependencies(Module, java.util.List)
.- Parameters:
module
- the module to relink- Throws:
ModuleLoadException
- if relinking failedSecurityException
- 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 occurrelink(Module)
must be called on all of them.- Parameters:
module
- the module to update and relinkdependencies
- the new dependency list- Throws:
ModuleLoadException
- if relinking failedSecurityException
- 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
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
-
findLoadedModuleLocal(String)
instead.