org.ungoverned.moduleloader
Interface SearchPolicy

All Known Implementing Classes:
ExhaustiveSearchPolicy, ImportSearchPolicy, OSGiImportSearchPolicy, SelfContainedSearchPolicy

public interface SearchPolicy

This interface represents a policy to define the most basic behavior of how classes, resources, and native libraries within a specific instance of ModuleManager are found. A ModuleManager manages a set of Modules, each of which is a potential source of classes, resources, and native libraries. The search policy makes it possible to consult these sources without hard-coding assumptions about application behavior or structure. Applicaitons inject their own specific class loading policy by creating a custom search policy or by selecting a pre-existing search policy that matches their needs.

The search policy is used by ModuleClassLoader, of which, there is one per Module within a given ModuleManager instance. The search policy is consulted by the ModuleClassLoader whenever there is a request for a class, resource, or native library. The search policy will generally search other modules in an application-specific way in order to find the requested item; for example, an application may use a policy where module's may import from one another. If the search policy provides an answer, then the ModuleClassLoader will use this to answer the originating 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.

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


Method Summary
 java.lang.Class findClass(Module module, java.lang.String name)
           This method tries to find the specified class for the specified module.
 java.net.URL findResource(Module module, java.lang.String name)
           This method tries to find the specified resource for the specified module.
 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.
 

Method Detail

setModuleManager

void setModuleManager(ModuleManager mgr)
                      throws java.lang.IllegalStateException

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.

Parameters:
mgr - the module manager associated with this search policy.
Throws:
java.lang.IllegalStateException - if the method is called more than once.

findClass

java.lang.Class findClass(Module module,
                          java.lang.String name)
                          throws java.lang.ClassNotFoundException

This method tries to find the specified class for the specified module. How the class is found or whether it is actually retrieved from the specified module is dependent upon the implementation. The default ModuleClassLoader.loadClass() method does not do any searching of its own, it merely calls ClassLoader.resolveClass() on the class returned by this method.

This method may return null or throw an exception if the specified class is not found. Whether a specific search policy implementation should do one or the other depends on the details of the specific search policy. The ModuleClassLoader first delegates to this method and then to the local resource sources of the module. If this method returns null, then the local resource sources will be searched. On the other hand, if this method throws an exception, then the local resource sources will not be searched.

Important: If the implementation of this method delegates the class loading to a ModuleClassLoader of another module, then it should not use the method ModuleClassLoader.loadClass() to load the class; it should use ModuleClassLoader.searchForClass() instead. This is necessary to eliminate an infinite loop that would occur otherwise. Also, with respect to the ModuleLoader framework, this method will only be called by a single thread at a time and is only intended to be called by ModuleClassLoader.loadClass().

Parameters:
parent - the parent class loader of the delegating class loader.
module - the target module that is loading the class.
name - the name of the class being loaded.
Returns:
the class if found, null otherwise.
Throws:
java.lang.ClassNotFoundException - if the class could not be found and the entire search operation should fail.

findResource

java.net.URL findResource(Module module,
                          java.lang.String name)
                          throws ResourceNotFoundException

This method tries to find the specified resource for the specified module. How the resource is found or whether it is actually retrieved from the specified module is dependent upon the implementation. The default ModuleClassLoader.getResource() method does not do any searching on its own.

This method may return null or throw an exception if the specified resource is not found. Whether a specific search policy implementation should do one or the other depends on the details of the specific search policy. The ModuleClassLoader first delegates to this method and then to the local resource sources of the module. If this method returns null, then the local resource sources will be searched. On the other hand, if this method throws an exception, then the local resource sources will not be searched.

Important: If the implementation of this method delegates the resource loading to a ModuleClassLoader of another module, then it should not use the method ModuleClassLoader.getResource() to get the resource; it should use ModuleClassLoader.searchForResource() instead. This is necessary to eliminate an infinite loop that would occur otherwise. Also, with respect to the ModuleLoader framework, this method will only be called by a single thread at a time and is not intended to be called directly.

Parameters:
parent - the parent class loader of the delegating class loader.
module - the target module that is loading the resource.
name - the name of the resource being loaded.
Returns:
a URL to the resource if found, null otherwise.
Throws:
ResourceNotFoundException - if the resource could not be found and the entire search operation should fail.