|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.ungoverned.moduleloader.search.ImportSearchPolicy
public class ImportSearchPolicy
This class implements a ModuleLoader search policy to support modules that import and export classes and resources from/to one another. Modules import from other modules by specifying a set of import identifiers and associated version numbers. Modules export their classes and resources by specifying a set of export identifiers and associated versions. Exports for a given module are also treated as imports for that module, meaning that it is possible for a module that exports classes to not use the classes it exports, but to actually use classes that are exported from another module. This search policy requires the following meta-data attributes be attached to each module:
The value of the ImportSearchPolicy.EXPORTS_ATTR attribute is an array of Object arrays, i.e., Object[][]. Each element in the array signifies a particular export that is offered by this associated module. Each element is an array triple of Object, where the index into this triple is:
The value of the ImportSearchPolicy.IMPORTS_ATTR attribute is essentially the same as the ImportSearchPolicy.EXPORTS_ATTR defined above; the only difference is that the array of versioned identifiers denote import targets rather than exports.
The value of the ImportSearchPolicy.PROPAGATES_ATTR attribute is an array of Objects, i.e., Object[]. Each element in the array is an identifier of a propagated import target from the ImportSearchPolicy.IMPORTS_ATTR attribute. Only identifiers for import targets are candidates for inclusion and the version number is unnecessary since it is assumed from the corresponding import target.
The value of the ImportSearchPolicy.VALID_ATTR attribute is a Boolean. The value is initially set to Boolean.FALSE and indicates that the module has not yet been validated. After the module is validated, the value is set to Boolean.TRUE. The search policy automatically adds this attribute to all modules and maintains its value.
These meta-data attributes help the search policy enforce consistency using a process called validation; validation ensures that classes and resources are only loaded from a module whose imports are satisfied. Therefore, a valid module is a module whose imports are satisfied and an invalid module is a module whose imports are not yet satisfied. An invalid module may be invalid for two reasons:
These two possibilities arise due to the fact that module validation is not performed until it is necessary (i.e., lazy evaluation). A module is automatically validated when an attempt is made to get classes or resources from it, although it is possible to manually validate a module. For a given module, called M, the validation process attempts to find an exporting module for every import target of M. If an exporter is not found for a specific import target, then the validation of module M fails. If an exporting module is found, then this module is also validated, if it is not already. As a result, the validation of module M depends on the validation of the transitive closure of all modules on which M depends. It is also possible for modules to exhibit dependency cycles; circular dependencies are allowed. Initially, a module's VALID_ATTR is set to Boolean.FALSE, but after the module is successfully validated, this attribute is set to Boolean.TRUE.
Besides ensuring that every import target is resolved to an appropriate exporting module, the validation process also attempts to maintain consistency along "propagation" chains. Propagation occurs when a module imports classes that are also visible from its own exports; for example, an HTTP server implementation may import classes from javax.servlet and export classes that have methods that use the type javax.servlet.Servlet in their signatures. Monitoring these types of occurences is important to uncover import source and version conflicts when multiple sources or versions of an import target are available within one virtual machine. When a module M is validated, the propagation information of each module that resolves the imports of M is checked to ensure that they do not propagate conflicting sources of M's imports; specifically, it is verified that all propagators of a particular import target have the same source module for that import target.
To facilitate applicability in as many scenarios as possible, this search policy delegates some decisions via additional policy interfaces. The following two policy interfaces must be specified by the code that instantiates the ImportSearchPolicy object:
Once an instance is created with definitions of the above policy interfaces, this search policy will operate largely self-contained. There are a few utility methods for manually validating modules, adding validation listeners, and access meta-data attributes, but for the most part these are not necessary except for implementing more sophisticated infrastructure.
The follow snippet of code illustrates a typical usage scenario for this search policy:
... ImportSearchPolicy searchPolicy = new ImportSearchPolicy( new MyCompatibilityPolicy(), new MySelectionPolicy()); ModuleManager mgr = new ModuleManager(searchPolicy); ... Object[][] exports = new Object[][] { { "org.apache.jasper", "2.1.0", null } }; Object[][] imports = new Object[][] { { "javax.servlet", "2.3.1", null } }; Object[][] attributes = new Object[][] { new Object[] { ImportSearchPolicy.EXPORTS_ATTR, exports }, new Object[] { ImportSearchPolicy.IMPORTS_ATTR, imports }, new Object[] { ImportSearchPolicy.PROPAGATES_ATTR, new Object[] { "javax.servlet" } } }; ResourceSource[] resSources = new ResourceSource[] { new JarResourceSource(file1) new JarResourceSource(file2) }; Module module = mgr.addModule(id, attributes, resSources, null); ClassLoader loader = module.getClassLoader(); // Assuming that all imports are satisfied... Class clazz = loader.loadClass("org.foo.MyClass"); ...
The above code snippet illustrates creating a module with one export and one import, where the import is also propagated via the module's export. The module has multiple resource sources, but no library sources.
SearchPolicy
,
Module
,
ModuleClassLoader
,
ModuleManager
Field Summary | |
---|---|
static java.lang.String |
EXPORTS_ATTR
This is the name of the "exports" meta-data attribute that should be attached to each module. |
static int |
IDENTIFIER_IDX
This is the index used to retrieve the import or export identifier from a given element of the EXPORTS_ATTR or the IMPORTS_ATTR attribute. |
static java.lang.String |
IMPORTS_ATTR
This is the name of the "imports" meta-data attribute that should be attached to each module. |
static java.lang.String |
PROPAGATES_ATTR
This is the name of the "propagates" meta-data attribute that should be attached to each module. |
static int |
RESOLVING_MODULE_IDX
This is the index used to retrieve the resolving module for an import or export target from a given element of the EXPORTS_ATTR or the IMPORTS_ATTR attribute. |
static java.lang.String |
VALID_ATTR
This is the name of the "valid" meta-data attribute that is automatically attached to each module. |
static int |
VERSION_IDX
This is the index used to retrieve the import or export version number from a given element of the EXPORTS_ATTR or the IMPORTS_ATTR attribute. |
Constructor Summary | |
---|---|
ImportSearchPolicy(CompatibilityPolicy compatPolicy,
SelectionPolicy selectPolicy)
Constructs an import search policy instance with the supplied compatibility and selection policies. |
Method Summary | |
---|---|
void |
addValidationListener(ValidationListener l)
Adds a validation listener to this import search policy. |
static java.util.List |
createImporterList(ModuleManager mgr,
Module module)
Utility method to create a list of modules that import from the specified module. |
static boolean |
doesImport(Module module,
java.lang.Object identifier)
Utility method to determine if the specified module imports a given import identifier, regardless of version. |
java.lang.Class |
findClass(Module module,
java.lang.String name)
This method is part of the SearchPolicy interface; it should not be called directly. |
java.net.URL |
findResource(Module module,
java.lang.String name)
This method is part of the SearchPolicy interface; it should not be called directly. |
protected void |
fireModuleInvalidated(Module module)
Fires an invalidation event for the specified module. |
protected void |
fireModuleValidated(Module module)
Fires a validation event for the specified module. |
CompatibilityPolicy |
getCompatibilityPolicy()
Returns the compatibility policy used by this import search policy instance. |
protected Module[] |
getCompatibleModules(java.lang.Object identifier,
java.lang.Object version)
This method returns a list of modules that have an export that is compatible with the given import identifier and version. |
static Module |
getExportResolvingModule(Module module,
java.lang.Object identifier)
Utility method to get the resolving module of a specific export identifier for the specified module. |
static java.lang.Object[][] |
getExportsAttribute(Module module)
Utility method that returns the EXPORTS_ATTR attribute for the specified module. |
static java.lang.Object |
getExportVersion(Module module,
java.lang.Object identifier)
Utility method to get the export version number associated with a specific export identifier of the specified module. |
static Module |
getImportResolvingModule(Module module,
java.lang.Object identifier)
Utility method to get the resolving module of a specific import identifier for the specified module. |
static java.lang.Object[][] |
getImportsAttribute(Module module)
Utility method that returns the IMPORTS_ATTR attribute for the specified module. |
static java.lang.Object[][] |
getImportsOrExports(Module module,
java.lang.String name)
Utility method that returns the IMPORTS_ATTR or the EXPORTS_ATTR attribute for the specified module. |
static java.lang.Object |
getImportVersion(Module module,
java.lang.Object identifier)
Utility method to get the import version number associated with a specific import identifier of the specified module. |
static java.lang.Object[] |
getPropagatesAttribute(Module module)
Utility method that returns the PROPAGATES_ATTR attribute for the specified module. |
SelectionPolicy |
getSelectionPolicy()
Returns the selection policy used by this import search policy instance. |
static java.lang.Boolean |
getValidAttribute(Module module)
Utility method that returns the VALID_ATTR attribute for the specified module. |
void |
invalidate(Module module,
java.lang.Object[][] attributes,
ResourceSource[] resSources,
LibrarySource[] libSources)
Invalidates a module by flushing its class loader and re-initializing its meta-data values. |
void |
moduleAdded(ModuleEvent event)
Callback method for ModuleListener; this should not be called directly. |
void |
moduleRemoved(ModuleEvent event)
Callback method for ModuleListener; this should not be called directly. |
void |
moduleReset(ModuleEvent event)
Callback method for ModuleListener; this should not be called directly. |
void |
removeValidationListener(ValidationListener l)
Removes a validation listener to this import search policy. |
Module |
resolveImportTarget(java.lang.Object identifier,
java.lang.Object version)
This utility method returns the module that exports the specified import identifier and version. |
void |
setModuleManager(ModuleManager mgr)
This method is called once by the ModuleManager to give the search policy instance a reference to its associated module manager. |
void |
validate(Module module)
This method validates the specified target module. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String EXPORTS_ATTR
public static final java.lang.String IMPORTS_ATTR
public static final java.lang.String PROPAGATES_ATTR
public static final java.lang.String VALID_ATTR
public static final int IDENTIFIER_IDX
public static final int VERSION_IDX
public static final int RESOLVING_MODULE_IDX
Constructor Detail |
---|
public ImportSearchPolicy(CompatibilityPolicy compatPolicy, SelectionPolicy selectPolicy)
compatPolicy
- the compatibility policy implementation to be used
by the search policy.selectPolicy
- the selection policy implementation to be used
by the search policy.Method Detail |
---|
public CompatibilityPolicy getCompatibilityPolicy()
public SelectionPolicy getSelectionPolicy()
public void setModuleManager(ModuleManager mgr) throws java.lang.IllegalStateException
SearchPolicy
This method is called once by the ModuleManager to give the search policy instance a reference to its associated module manager. This method should be implemented such that it cannot be called twice; calling this method a second time should produce an illegal state exception.
setModuleManager
in interface SearchPolicy
mgr
- the module manager associated with this search policy.
java.lang.IllegalStateException
- if the method is called
more than once.public java.lang.Class findClass(Module module, java.lang.String name) throws java.lang.ClassNotFoundException
findClass
in interface SearchPolicy
module
- the target module that is loading the class.name
- the name of the class being loaded.
java.lang.ClassNotFoundException
- if the target module
could not be validated.public java.net.URL findResource(Module module, java.lang.String name) throws ResourceNotFoundException
findResource
in interface SearchPolicy
module
- the target module that is loading the resource.name
- the name of the resource being loaded.
ResourceNotFoundException
- if the
resource could not be found and the entire search operation
should fail.public void validate(Module module) throws ValidationException
module
- the module to validate.
ValidationException
- if
the module or any dependent modules could not be validated.protected Module[] getCompatibleModules(java.lang.Object identifier, java.lang.Object version)
identifier
- the import identifier.version
- the version of the import identifier.
public void invalidate(Module module, java.lang.Object[][] attributes, ResourceSource[] resSources, LibrarySource[] libSources)
module
- the module to be invalidated.attributes
- the attributes associated with the module, since they
might have changed.resSources
- the resource sources associated wih the module, since they
might have changed.libSources
- the library sources associated wih the module, since they
might have changed.public void addValidationListener(ValidationListener l)
l
- the validation listener to add.public void removeValidationListener(ValidationListener l)
l
- the validation listener to remove.protected void fireModuleValidated(Module module)
module
- the module that was validated.protected void fireModuleInvalidated(Module module)
module
- the module that was invalidated.public void moduleAdded(ModuleEvent event)
moduleAdded
in interface ModuleListener
event
- the event object containing the event details.public void moduleReset(ModuleEvent event)
moduleReset
in interface ModuleListener
event
- the event object containing the event details.public void moduleRemoved(ModuleEvent event)
moduleRemoved
in interface ModuleListener
event
- the event object containing the event details.public Module resolveImportTarget(java.lang.Object identifier, java.lang.Object version)
identifier
- the identifier of the import to resolve.version
- the version of the import to resolve.
public static java.lang.Boolean getValidAttribute(Module module)
module
- the module whose VALID_ATTR attribute is to
be retrieved.
public static java.lang.Object[][] getImportsAttribute(Module module)
module
- the module whose IMPORTS_ATTR attribute is to
be retrieved.
public static java.lang.Object[][] getExportsAttribute(Module module)
module
- the module whose EXPORTS_ATTR attribute is to
be retrieved.
public static java.lang.Object[][] getImportsOrExports(Module module, java.lang.String name)
module
- the module whose IMPORTS_ATTR or
EXPORTS_ATTR attribute is to be retrieved.name
- either IMPORTS_ATTR or EXPORTS_ATTR
depending on which attribute should be retrieved.
public static java.lang.Object[] getPropagatesAttribute(Module module)
module
- the module whose PROPAGATES_ATTR attribute is to
be retrieved.
public static boolean doesImport(Module module, java.lang.Object identifier)
module
- the module to check.identifier
- the import identifier to check.
public static java.util.List createImporterList(ModuleManager mgr, Module module)
mgr
- the module manager that contains the module.module
- the module for which to create an importer list.
public static java.lang.Object getImportVersion(Module module, java.lang.Object identifier)
module
- the module to investigate.identifier
- the import identifier for which the version should
be retrieved.
public static java.lang.Object getExportVersion(Module module, java.lang.Object identifier)
module
- the module to investigate.identifier
- the export identifier for which the version should
be retrieved.
public static Module getImportResolvingModule(Module module, java.lang.Object identifier)
module
- the module to investigate.identifier
- the import identifier for which the resolving
module should be retrieved.
public static Module getExportResolvingModule(Module module, java.lang.Object identifier)
module
- the module to investigate.identifier
- the export identifier for which the resolving
module should be retrieved.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |