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 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 Module	findLoadedModuleLocal(String name)	Find an already-loaded module, returning null if the module isn't currently loaded.
protected Module	findLoadedModuleLocal(ModuleIdentifier identifier)	Deprecated. 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. 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 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.
Iterator<String>	iterateModules(String baseName, boolean recursive)	Iterate the modules which can be located via this module loader.
Iterator<ModuleIdentifier>	iterateModules(ModuleIdentifier baseIdentifier, boolean recursive)	Deprecated. Use iterateModules(String, boolean) instead.
Module	loadModule(String name)	Load a module based on an identifier.
Module	loadModule(ModuleIdentifier identifier)	Deprecated. Use loadModule(String) instead.
protected Module	loadModuleLocal(String name)	Try to load a module from this module loader.
protected Module	loadModuleLocal(ModuleIdentifier moduleIdentifier)	Deprecated. Use loadModuleLocal(String) instead.
protected Module	preloadExportedModule(String name)	Preload an "exported" module based on an identifier.
protected Module	preloadExportedModule(ModuleIdentifier identifier)	Deprecated. 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. Use preloadModule(String) instead.
protected static Module	preloadModule(ModuleIdentifier identifier, ModuleLoader moduleLoader)	Deprecated. 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 boolean	unloadModuleLocal(String moduleId, Module module)	Unload a module from this module loader.
protected 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 Detail

NO_FINDERS

public static final ModuleFinder[] NO_FINDERS

A constant representing zero module finders.

Constructor Detail

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 Detail

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

loadModule

@Deprecated
public final Module loadModule(ModuleIdentifier identifier)
                        throws ModuleLoadException

Deprecated. 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
public final Iterator<ModuleIdentifier> iterateModules(ModuleIdentifier baseIdentifier,
                                                       boolean recursive)

Deprecated. 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
protected Module preloadModule(ModuleIdentifier identifier)
                        throws ModuleLoadException

Deprecated. 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
protected Module preloadExportedModule(ModuleIdentifier identifier)
                                throws ModuleLoadException

Deprecated. 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
protected static Module preloadModule(ModuleIdentifier identifier,
                                      ModuleLoader moduleLoader)
                               throws ModuleLoadException

Deprecated. 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
protected final Module loadModuleLocal(ModuleIdentifier moduleIdentifier)
                                throws ModuleLoadException

Deprecated. 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
protected final Module findLoadedModuleLocal(ModuleIdentifier identifier)

Deprecated. 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
protected ModuleSpec findModule(ModuleIdentifier moduleIdentifier)
                         throws ModuleLoadException

Deprecated. 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