org.ungoverned.moduleloader
Class ModuleManager

java.lang.Object
  extended byorg.ungoverned.moduleloader.ModuleManager

public class ModuleManager
extends java.lang.Object

The ModuleManager class is the core facility for defining a re-usable, policy-driven class loader for applications that require flexible class loading mechanisms. The ModuleManager is not class loader itself, but it supports the concept of a Module, which is a unit of organization for application classes and resources. The ModuleManager has only a handful of methods that allow an application to add, remove, reset, and query modules; the intent is to place as few assumptions in the ModuleManager as possible.

The idea is simple, allow the application to map itself into modules however it sees fit and let the ModuleManager assume the responsibility of managing the modules and loading classes and resources from them as necessary via ModuleClassLoaders that are associated with each module. In order to achieve this goal, though, the ModuleManager must make at least one assumption on behalf of the application. This assumption is that the loading of classes and resources from the available modules must happen using a search algorithm that is particular to the application itself. As a result of this assumption, the ModuleManager requires that the application provide a concrete implementation of the SearchPolicy interface.

The search policy allows the ModuleLoader to let applications inject their own particular class loading policies, without dictating strict or constraining base assumptions. Of course, it is likely that many applications will use the same or very similar search policies. Because of this, another goal of the ModuleLoader approach is to foster a common library of search policies that applications are free to use or customize as they see fit. These common search policies are analagous to patterns, where each search policy is viewable as a class loading pattern. Some initial search policies included with the ModuleLoader are ExhaustiveSearchPolicy, SelfContainedSearchPolicy, and ImportSearchPolicy.

Due to the fact that class loaders are tied to security and resource loading, the search policy alone is not sufficient for the ModuleLoader to perform its function. To fulfill these other purposes, the ModuleLoader introduces another policy interface, called the URLPolicy. The URLPolicy allows the application to inject its particular policy for to purposes:

  1. Creating the URL associated with loading a resource, such as the URL returned from a call to Class.getResource().
  2. Creating the URL that will be associated with a class's CodeSource when defining the class for purposes of security and assigning permissions.

The ModuleLoader defines a default URLPolicy, called DefaultURLPolicy, that provides a simple URLStreamHandler for accessing resources inside of modules and that returns null for the CodeSource URL. Applications only need to supply their own URLPolicy if the default one does not provide the appropriate behavior.

It is possible for an application to create multiple instances of the ModuleManager within a single JVM, but it is not possible to share modules across multiple ModuleManagers. A given ModuleManager can only have one SelectionPolicy and one URLPolicy.

See Also:
Module, ModuleClassLoader, SearchPolicy, URLPolicy, DefaultURLPolicy

Constructor Summary
ModuleManager(SearchPolicy searchPolicy)
           Constructs a ModuleManager instance using the specified search policy and the default URL policy.
ModuleManager(SearchPolicy searchPolicy, URLPolicy urlPolicy)
           Constructs a ModuleManager instance using the specified search policy and the specified URL policy.
 
Method Summary
 Module addModule(java.lang.String id, java.lang.Object[][] attributes, ResourceSource[] resSources, LibrarySource[] libSources)
           Adds a module to the module manager.
 void addModuleListener(ModuleListener l)
           Adds a listener to the ModuleManager to listen for module added, reset, and removed events.
protected  void fireModuleAdded(Module module)
           Fires an event indicating that the specified module was added to the ModuleManager.
protected  void fireModuleRemoved(Module module)
           Fires an event indicating that the specified module was removed from the ModuleManager.
protected  void fireModuleReset(Module module)
           Fires an event indicating that the specified module was reset.
 Module getModule(java.lang.String id)
           Returns a module associated with the specified identifier.
 Module[] getModules()
           Returns an array of all modules being managed by the ModuleManager instance.
 SearchPolicy getSearchPolicy()
           Returns the search policy used by this instance.
 URLPolicy getURLPolicy()
           Returns the URL policy used by this instance.
 void removeModule(Module module)
           Removes the specified module from the ModuleManager.
 void removeModuleListener(ModuleListener l)
           Removes a listener from the ModuleManager.
 void resetModule(Module module, java.lang.Object[][] attributes, ResourceSource[] resSources, LibrarySource[] libSources)
           Resets a given module.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ModuleManager

public ModuleManager(SearchPolicy searchPolicy)

Constructs a ModuleManager instance using the specified search policy and the default URL policy.

Parameters:
searchPolicy - the search policy that the instance should use.
See Also:
SearchPolicy

ModuleManager

public ModuleManager(SearchPolicy searchPolicy,
                     URLPolicy urlPolicy)

Constructs a ModuleManager instance using the specified search policy and the specified URL policy.

Parameters:
searchPolicy - the search policy that the instance should use.
urlPolicy - the URL policy that the instance should use.
See Also:
SearchPolicy, URLPolicy
Method Detail

getURLPolicy

public URLPolicy getURLPolicy()

Returns the URL policy used by this instance.

Returns:
the URL policy used by this instance.
See Also:
URLPolicy

getSearchPolicy

public SearchPolicy getSearchPolicy()

Returns the search policy used by this instance.

Returns:
the search policy used by this instance.
See Also:
SearchPolicy

getModules

public Module[] getModules()

Returns an array of all modules being managed by the ModuleManager instance. The array contains a snapshot of all modules in the ModuleManager at the time when this method was called.

Returns:
an array of all modules being managed by the ModuleManager instance.
See Also:
Module

getModule

public Module getModule(java.lang.String id)

Returns a module associated with the specified identifier.

Parameters:
id - the identifier for the module to be retrieved.
Returns:
the module associated with the identifier or null.
See Also:
Module

addModule

public Module addModule(java.lang.String id,
                        java.lang.Object[][] attributes,
                        ResourceSource[] resSources,
                        LibrarySource[] libSources)

Adds a module to the module manager. The module will have the specified unique identifier, with the associated attributes, resource sources, and library sources. If the identifier is not unique, then an exception is thrown.

Parameters:
id - the unique identifier of the new module.
attributes - an array of key-value attribute pairs to associate with the module.
resSources - an array of ResourceSources to associate with the module.
libSources - an array of LibrarySources to associate with the module.
Returns:
the newly created module.
Throws:
java.lang.IllegalArgumentException - if the module identifier is not unique.
See Also:
Module, ResourceSource, LibrarySource

resetModule

public void resetModule(Module module,
                        java.lang.Object[][] attributes,
                        ResourceSource[] resSources,
                        LibrarySource[] libSources)

Resets a given module. In resetting a module, the module's associated class loader is thrown away; it is the application's responsibility to determine when and how that application code stops using classes (and subsequent instances) from the class loader of the reset module. This method allows the associated elements of the module (i.e., attributes, resource sources, and library sources) to be changed also; if these elements have not changed then they simply need to be passed back in from the existing module. This method is useful in situations where the underlying module needs to be changed at run time, such as might be necessary if a module was updated.

The same effect could be achieved by first removing and then re-adding a module, but with one subtle different. By removing and then re-adding a module, a new module is created and, thus, all existing references become invalid. By explicitly having this method, the ModuleManager maintains the integrity of the module reference, which is more intuitive in the case where an updated module is intended to be the same module, only updated.

Parameters:
module - the module reset.
attributes - an array of key-value attribute pairs to associate with the module.
resSources - an array of ResourceSources to associate with the module.
libSources - an array of LibrarySources to associate with the module.
See Also:
Module, ResourceSource, LibrarySource

removeModule

public void removeModule(Module module)

Removes the specified module from the ModuleManager. Removing a module only removed the module from the ModuleManager. It is the application's responsibility to determine when and how application code stop using classes (and subsequent instances) that were loaded from the class loader of the removed module.

Parameters:
module - the module to remove.

addModuleListener

public void addModuleListener(ModuleListener l)

Adds a listener to the ModuleManager to listen for module added, reset, and removed events.

Parameters:
l - the ModuleListener to add.

removeModuleListener

public void removeModuleListener(ModuleListener l)

Removes a listener from the ModuleManager.

Parameters:
l - the ModuleListener to remove.

fireModuleAdded

protected void fireModuleAdded(Module module)

Fires an event indicating that the specified module was added to the ModuleManager.

Parameters:
module - the module that was added.

fireModuleReset

protected void fireModuleReset(Module module)

Fires an event indicating that the specified module was reset.

Parameters:
module - the module that was reset.

fireModuleRemoved

protected void fireModuleRemoved(Module module)

Fires an event indicating that the specified module was removed from the ModuleManager.

Parameters:
module - the module that was removed.