org.ungoverned.moduleloader
Class ModuleClassLoader

java.lang.Object
  extended byjava.lang.ClassLoader
      extended byjava.security.SecureClassLoader
          extended byorg.ungoverned.moduleloader.ModuleClassLoader

public class ModuleClassLoader
extends java.security.SecureClassLoader

Each module that is managed by a ModuleManager has a ModuleClassLoader associated with it. The ModuleClassLoader is responsible for loading all classes, resources, and native libraries for its module. The ModuleClassLoader of a module is accessed using the Module.getClassLoader() method. The ModuleClassLoader uses its module's ResourceSources and LibrarySources to perform its function.

When loading a class or resource, the ModuleClassLoader does not immediately search its module's ResourceSources, instead it first delegates the request to the SearchPolicy of the ModuleManager; this allows applications to inject specific class/resource loading policies. When the ModuleClassLoader delegates to the search policy, the search policy uses application-specific behavior to typically service the request from the ResourceSources of other modules. If the search policy returns a result, then this result is returned immediately by the ModuleClassLoader; otherwise, it searches the ResourceSources its module in an attempt to satisfy the original request.

Important: The search policy searches modules in some application-specific manner in order to find a class or resource. This search is instigated, either directly or indirectly, by calls to ModuleClassLoader.loadClass() and ModuleClassLoader.getResource(), respectively. In order for the search policy to load a class or resource, it must not use ModuleClassLoader.loadClass() or ModuleClassLoader.getResource() again, because this would result in an infinite loop. Instead, the ModuleClassLoader offers the the methods ModuleClassLoader.searchForClass() and ModuleClassLoader.searchForResource() to search a given module and to avoid an infinite loop. As an example, consider the following snippet of code that implements an "exhaustive" search policy:

     ...
     public Class findClass(Module module, String name)
     {
         Module[] modules = m_mgr.getModules();
         for (int i = 0; i < modules.length; i++)
         {
             try {
                 Class clazz = modules[i].getClassLoader().searchForClass(name);
                 if (clazz != null)
                 {
                     return clazz;
                 }
             } catch (Throwable th) {
             }
         }

         return null;
     }
     ...
 

In the above code, the search policy "exhaustively" searches every module in the ModuleManager to find the requested resource. Note that this policy will also search the module that originated the request, which is not totally necessary since returning null will cause the ModuleClassLoader to search the originating module's ResourceSources.


Constructor Summary
protected ModuleClassLoader(ModuleManager mgr, Module module)
           Constructs an instance using the specified ModuleManager, for the specified Module.
 
Method Summary
protected  java.lang.Class findClass(java.lang.String name)
           This method overriden from from ClassLoader.
protected  java.lang.String findLibrary(java.lang.String name)
           This method overriden from from ClassLoader.
protected  java.net.URL findResource(java.lang.String name)
           This method overriden from from ClassLoader.
protected  java.util.Enumeration findResources(java.lang.String name)
           
 java.net.URL getResource(java.lang.String name)
           This method is nearly an exact copy of the ClassLoader.getResource() method.
protected  java.lang.Class loadClass(java.lang.String name, boolean resolve)
           This method is nearly an exact copy of the ClassLoader.loadClass() method.
 java.lang.Class searchForClass(java.lang.String name)
           This method is used by SearchPolicy instances when they want to load a class from a module.
 java.net.URL searchForResource(java.lang.String name)
           This method is used by SearchPolicy instances when they want to load a resource from a module.
 
Methods inherited from class java.security.SecureClassLoader
defineClass, getPermissions
 
Methods inherited from class java.lang.ClassLoader
clearAssertionStatus, defineClass, defineClass, defineClass, definePackage, findLoadedClass, findSystemClass, getPackage, getPackages, getParent, getResourceAsStream, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, loadClass, resolveClass, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus, setSigners
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ModuleClassLoader

protected ModuleClassLoader(ModuleManager mgr,
                            Module module)

Constructs an instance using the specified ModuleManager, for the specified Module. This constructor is protected so that it cannot be created publicly.

Parameters:
mgr - the ModuleManager of the Module.
module - the Module instance associated with the class loader.
Method Detail

loadClass

protected java.lang.Class loadClass(java.lang.String name,
                                    boolean resolve)
                             throws java.lang.ClassNotFoundException

This method is nearly an exact copy of the ClassLoader.loadClass() method. The main difference is that it delegates to its associated ModuleManager's search policy before calling the ClassLoader.findClass() method. Additionally, the synchronized modifier was removed from the superclass method; this change was necessary because ClassLoader class assumes a tree of class loaders, but the class loading structure in the ModuleManager might actually be a graph of class loaders; thus, it was necessary to loosen the concurrency locking to allow for cycles.

Parameters:
name - the class to be loaded.
resolve - flag indicating whether the class should be resolved or not.
Returns:
the loaded class.
Throws:
java.lang.ClassNotFoundException - if the class could not be loaded.

findClass

protected java.lang.Class findClass(java.lang.String name)
                             throws java.lang.ClassNotFoundException

This method overriden from from ClassLoader. It is implemented such that it loads classes from the set of ResourceSources from its associated module.

Parameters:
name - the name of the resource to load.
Returns:
the loaded Class object.
Throws:
java.lang.ClassNotFoundException - if the class could not be loaded.

searchForClass

public java.lang.Class searchForClass(java.lang.String name)

This method is used by SearchPolicy instances when they want to load a class from a module. The search policy is initially invoked when ModuleClassLoader.loadClass() delegates a class loading request to it. In general, the ultimate goal of the search policy is to return a class from another module if possible. Unfortunately, if a search policy tries to directly load a class from another module's class loader, an infinite loop will result because the module's class loader will delegate the request back to the search policy. To avoid this situation, search policies must use this method when trying to load a class from a module.

Parameters:
name - the name of the class to load.
Returns:
the loaded class or null.

getResource

public java.net.URL getResource(java.lang.String name)

This method is nearly an exact copy of the ClassLoader.getResource() method. The main difference is that it delegates to its associated ModuleManager's search policy before calling the ClassLoader.findResource() method.

Parameters:
name - the class to be loaded.
Returns:
a URL to the resource or null if the resource was not found.

findResource

protected java.net.URL findResource(java.lang.String name)

This method overriden from from ClassLoader. It is implemented such that it loads resources from the set of ResourceSources from its associated module.

Parameters:
name - the name of the resource to load.
Returns:
the URL associated with the resource or null.

searchForResource

public java.net.URL searchForResource(java.lang.String name)

This method is used by SearchPolicy instances when they want to load a resource from a module. The search policy is initially invoked when ModuleClassLoader.loadClass() delegates a resource loading request to it. In general, the ultimate goal of the search policy is to return a resource from another module if possible. Unfortunately, if a search policy tries to directly load a resource from another module's class loader, an infinite loop will result because the module's class loader will delegate the request back to the search policy. To avoid this situation, search policies must use this method when trying to load a resource from a module.

Parameters:
name - the name of the resource to load.
Returns:
a URL to the resource or null.

findResources

protected java.util.Enumeration findResources(java.lang.String name)

findLibrary

protected java.lang.String findLibrary(java.lang.String name)

This method overriden from from ClassLoader. It maps a library name to a library path by consulting the LibrarySources of the class loader's module.

Parameters:
name - the name of the library to find.
Returns:
the file system path of library or null