artofillusion.util
Class SearchlistClassLoader

java.lang.Object
  extended by java.lang.ClassLoader
      extended by artofillusion.util.SearchlistClassLoader

public class SearchlistClassLoader
extends java.lang.ClassLoader

A class loader which loads classes using a searchlist of other classloaders.
The classloaders in the searchlist are of two types: shared and non-shared. A shared classloader may be in use by other code, and so no duplicates should be made of the classes in the loaders.
A non-shared classloader is private to this SearchlistClassLoader, and so there is no possibility that other code could be using them. To avoid problems of isolation, all classes loaded through non-shared loaders are defined as having been loaded by the SearchlistClassLoader itself. This ensures the JVM can find the correct loader when loading associated classes (including shared classes).
The SearchlistClassLoader API therefore makes a clear distinction between shared and non-shared classloaders.
The add(ClassLoader) method adds an existing classloader which means the added classloader is treated as being shared.
The add(URL) method adds a new internally created classloader which loads the content associated with the specified URL, which means the internally created classloader is non-shared.

SearchlistClassLoader therefore also allows control over the order in which classloaders are searched, through the setSearchMode(byte) method.
The possible searchmodes are:


There is also a method which retrieves a class without searching any added classloaders. This effectively retrieves the canonical instance of the requested class (see loadLocalClass(String) and getLocalResource(String)).

Implementation notes:.
Because each class object is associated with the classloader which defined it (see ClassLoader.defineClass(...)), SearchlistClassLoader must associate itself with all class objects it loads through non-shared loaders, and similarly must not associate itself with class objects loaded through shared loaders. (See findClass(String).)
The structure of the internal ClassLoader methods is as per the instructions in ClassLoader. While I don't think this is necessary any longer, it was quite easy to comply with the instructions.


Field Summary
static byte NONSHARED
           
static byte ORDERED
           
static byte SHARED
          search mode enums
 
Constructor Summary
SearchlistClassLoader()
          create a SearchlistClassLoader.
SearchlistClassLoader(java.lang.ClassLoader parent)
          create a SearchlistClassLoader.
SearchlistClassLoader(java.net.URL[] url)
          create a SearchlistClassLoader.
SearchlistClassLoader(java.net.URL[] url, java.lang.ClassLoader parent)
          create a SearchlistClassLoader.
 
Method Summary
 void add(java.lang.ClassLoader loader)
          add a (shared) classloader to the searchlist.
 void add(java.net.URL url)
          add a (non-shared) URL to the searchlist.
 java.lang.Class findClass(java.lang.String name)
          Return a Class object for the specified class name.
 java.lang.String findLibrary(java.lang.String libname)
          return the pathname to the specified native library.
 java.net.URL findResource(java.lang.String path)
          find a resource using the searchlist.
 java.net.URL getLocalResource(java.lang.String name)
          Return the URL for the local resource specified by name.
 java.net.URL[] getSearchPath()
          return the list of URLs in the search list
 java.net.URL[] getURLs()
          return the array of URLs used locally by this class loader
 java.lang.Class loadLocalClass(java.lang.String name)
          Return the local class instance for name.
 void setSearchMode(byte mode)
          set the search mode.
static java.lang.String translate(java.lang.String str, java.lang.String match, java.lang.String replace)
          translate matching chars in a string.
 
Methods inherited from class java.lang.ClassLoader
clearAssertionStatus, getParent, getResource, getResourceAsStream, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, loadClass, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SHARED

public static final byte SHARED
search mode enums

See Also:
Constant Field Values

NONSHARED

public static final byte NONSHARED
See Also:
Constant Field Values

ORDERED

public static final byte ORDERED
See Also:
Constant Field Values
Constructor Detail

SearchlistClassLoader

public SearchlistClassLoader()
create a SearchlistClassLoader.


SearchlistClassLoader

public SearchlistClassLoader(java.lang.ClassLoader parent)
create a SearchlistClassLoader.


SearchlistClassLoader

public SearchlistClassLoader(java.net.URL[] url)
create a SearchlistClassLoader.


SearchlistClassLoader

public SearchlistClassLoader(java.net.URL[] url,
                             java.lang.ClassLoader parent)
create a SearchlistClassLoader.

Method Detail

setSearchMode

public void setSearchMode(byte mode)
set the search mode.

Parameters:
mode - enum for the searchmode: SHARED, NONSHARED, ORDERED

add

public void add(java.lang.ClassLoader loader)
add a (shared) classloader to the searchlist. The loader is added to the list as a shared loader.

Parameters:
loader - the ClassLoader to add to the searchlist.

add

public void add(java.net.URL url)
add a (non-shared) URL to the searchlist. Creates a new URLClassLoader and adds it to the searchlist as a non-shared classloader.

Parameters:
url - the URL to add to the searchlist.

getURLs

public java.net.URL[] getURLs()
return the array of URLs used locally by this class loader


getSearchPath

public java.net.URL[] getSearchPath()
return the list of URLs in the search list


loadLocalClass

public java.lang.Class loadLocalClass(java.lang.String name)
                               throws java.lang.ClassNotFoundException
Return the local class instance for name.
This does not search the searchlist. Only classes loaded directly by this loader or its parent are returned.
This method can be used to retrieve the canonical instance of a class. If this method is called on a set of SearchlistClassLoaders, then the only classloader which will return the class is the one which originally loaded it (assuming no duplicates have been created yet).

Parameters:
name - the fully-qualified name of the class
Returns:
the loaded class.
Throws:
java.lang.ClassNotFoundException - if the class is not found.

getLocalResource

public java.net.URL getLocalResource(java.lang.String name)
Return the URL for the local resource specified by name.
This does not search the searchlist. Only resources loaded directly by this loader or its parent are returned.
This method can be used to retrieve the canonical URL for a resource. If this method is called on a set of SearchlistClassLoaders, then the only classloader which will return the resource is the one which originally loaded it (assuming no duplicates have been created yet).

Parameters:
name - the fully-qualified name of the resource.
Returns:
the located URL, or null.

findClass

public java.lang.Class findClass(java.lang.String name)
                          throws java.lang.ClassNotFoundException
Return a Class object for the specified class name.

Overrides:
findClass in class java.lang.ClassLoader
Parameters:
name - the fully-qualified name of the class
Returns:
the loaded class object
Throws:
java.lang.ClassNotFoundException - if the class could not be loaded.

findResource

public java.net.URL findResource(java.lang.String path)
find a resource using the searchlist.

Overrides:
findResource in class java.lang.ClassLoader
Parameters:
path - the fully-qualified name of the resource to retrieve
Returns:
the URL if the resource is found, and null otherwise.

findLibrary

public java.lang.String findLibrary(java.lang.String libname)
return the pathname to the specified native library. If the library is not found on the searchpath, then null is returned, indicating to the Java machine that it should search java.library.path.

Overrides:
findLibrary in class java.lang.ClassLoader
Parameters:
libname - - the String name of the library to find
Returns:
the full path to the found library file, or null.

translate

public static java.lang.String translate(java.lang.String str,
                                         java.lang.String match,
                                         java.lang.String replace)
translate matching chars in a string.

Parameters:
str - the String to translate
match - the list of chars to match, in a string.
replace - the list of corresponding chars to replace matched chars with.
  Eg: translate("the dog.", "o.", "i")
  returns "the dig", because 'o' is replaced with 'i', and '.' is
  replaced with nothing (ie deleted).
Returns:
the result as a string.


Copyright © 1999-2011 by Peter Eastman.