org.jboss.modules
Class ModuleLoader

java.lang.Object
  extended by org.jboss.modules.ModuleLoader
Direct Known Subclasses:
ClassifyingModuleLoader, LocalModuleLoader, SystemClassPathModuleLoader

public abstract 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, Jason T. Greene

Constructor Summary
protected ModuleLoader()
          Construct a new instance.
 
Method Summary
protected  Module findLoadedModuleLocal(ModuleIdentifier identifier)
          Find an already-loaded module, returning null if the module isn't currently loaded.
protected abstract  ModuleSpec findModule(ModuleIdentifier moduleIdentifier)
          Find a Module's specification in this ModuleLoader by its identifier.
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.
 Module loadModule(ModuleIdentifier identifier)
          Load a module based on an identifier.
protected  Module loadModuleLocal(ModuleIdentifier identifier)
          Try to load a module from this module loader.
protected  Module preloadExportedModule(ModuleIdentifier identifier)
          Preload an "exported" module based on an identifier.
protected  Module preloadModule(ModuleIdentifier identifier)
          Preload a module based on an identifier.
protected static Module preloadModule(ModuleIdentifier identifier, ModuleLoader moduleLoader)
          Utility method to delegate to another module loader, accessible from subclasses.
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.
abstract  String toString()
          Get the string representation of this module loader.
protected  void unloadModuleLocal(Module module)
          Unload a module from this module loader.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ModuleLoader

protected ModuleLoader()
Construct a new instance.

Method Detail

forClass

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

Parameters:
clazz - the class
Returns:
the 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

toString

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

Overrides:
toString in class Object
Returns:
the string representation

loadModule

public final Module loadModule(ModuleIdentifier identifier)
                        throws ModuleLoadException
Load a module based on an identifier. This method delegates to preloadModule(ModuleIdentifier) 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

preloadModule

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

Parameters:
identifier - 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(ModuleIdentifier identifier)
                                throws ModuleLoadException
Preload an "exported" module based on an identifier. By default this simply delegates to preloadModule(ModuleIdentifier).

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(ModuleIdentifier identifier,
                                      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:
identifier - the module identifier
moduleLoader - the module loader to delegate to
Returns:
the delegation result
Throws:
ModuleLoadException - if an error occurs

loadModuleLocal

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

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

findLoadedModuleLocal

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

unloadModuleLocal

protected final void unloadModuleLocal(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.

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

findModule

protected abstract ModuleSpec findModule(ModuleIdentifier moduleIdentifier)
                                  throws ModuleLoadException
Find a Module's specification in this ModuleLoader by its identifier. This should be overriden by sub-classes to implement the Module loading strategy for this loader.

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:
moduleIdentifier - The modules Identifier
Returns:
the module specification, or null if no module is found with the given identifier
Throws:
ModuleLoadException - if any problems occur finding the module

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

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

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

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


Copyright © 2011. All Rights Reserved.