org.oddjob.arooa
Class ArooaClassLoader

java.lang.Object
  java.lang.ClassLoader
      org.oddjob.arooa.ArooaClassLoader

public class ArooaClassLoader

extends java.lang.ClassLoader

Used to load classes within ant with a different classpath from that used to start ant. Note that it is possible to force a class into this loader even when that class is on the system classpath by using the forceLoadClass method. Any subsequent classes loaded by that class will then use this loader rather than the system class loader.

Author:

Based on the orginal from Ant.

Constructor Summary

ArooaClassLoader()
Create an Ant Class Loader

ArooaClassLoader(java.lang.ClassLoader parent, boolean parentFirst)
Creates an empty class loader.

ArooaClassLoader(java.lang.ClassLoader parent, java.io.File[] classpath, boolean parentFirst)
Creates a classloader for the given project using the classpath given.

ArooaClassLoader(java.io.File[] classpath)
Creates a classloader for the given project using the classpath given.

ArooaClassLoader(java.io.File[] classpath, boolean parentFirst)
Creates a classloader for the given project using the classpath given.

Method Summary

void	addLoaderPackageRoot(java.lang.String packageRoot) Adds a package root to the list of packages which must be loaded using this loader.
protected void	addPathFile(java.io.File pathComponent) Add a file to the path
void	addSystemPackageRoot(java.lang.String packageRoot) Adds a package root to the list of packages which must be loaded on the parent loader.
void	cleanup() Cleans up any resources held by this classloader.
java.lang.Class	findClass(java.lang.String name) Searches for and load a class on the classpath of this class loader.
protected java.util.Enumeration	findResources(java.lang.String name) Returns an enumeration of URLs representing all the resources with the given name by searching the class loader's classpath.
java.lang.Class	forceLoadClass(java.lang.String classname) Loads a class through this class loader even if that class is available on the parent classpath.
java.lang.Class	forceLoadSystemClass(java.lang.String classname) Loads a class through this class loader but defer to the parent class loader.
java.lang.String	getClasspath() Returns the classpath this classloader will consult.
java.lang.String	getPath() Get the classpath as a string.
java.net.URL	getResource(java.lang.String name) Finds the resource with the given name.
java.io.InputStream	getResourceAsStream(java.lang.String name) Returns a stream to read the requested resource name.
protected java.net.URL	getResourceURL(java.io.File file, java.lang.String resourceName) Returns the URL of a given resource in the given file which may either be a directory or a zip file.
static void	initializeClass(java.lang.Class theClass) Deprecated. use Class.forName with initialize=true instead.
protected boolean	isInPath(java.io.File component) Indicate if the given file is in this loader's path
protected java.lang.Class	loadClass(java.lang.String classname, boolean resolve) Loads a class with this class loader.
void	setClassPath(java.io.File[] classpath) Set the classpath to search for classes to load.
void	setIsolated(boolean isolated) Sets whether this classloader should run in isolated mode.
void	setParent(java.lang.ClassLoader parent) Set the parent for this class loader.
void	setParentFirst(boolean parentFirst) Control whether class lookup is delegated to the parent loader first or after this loader.
java.lang.String	toString()

Methods inherited from class java.lang.ClassLoader

clearAssertionStatus, defineClass, defineClass, defineClass, definePackage, findLibrary, findLoadedClass, findResource, findSystemClass, getPackage, getPackages, getParent, 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, wait, wait, wait

Constructor Detail

ArooaClassLoader

public ArooaClassLoader()

Create an Ant Class Loader

ArooaClassLoader

public ArooaClassLoader(java.io.File[] classpath)

Creates a classloader for the given project using the classpath given.

Parameters:

classpath - The classpath to use to load the classes. This is combined with the system classpath in a manner determined by the value of ${build.sysclasspath}. May be null, in which case no path elements are set up to start with.

ArooaClassLoader

public ArooaClassLoader(java.lang.ClassLoader parent,
                        java.io.File[] classpath,
                        boolean parentFirst)

Creates a classloader for the given project using the classpath given.

Parameters:

parent - The parent classloader to which unsatisfied loading attempts are delegated. May be null, in which case the classloader which loaded this class is used as the parent.

classpath - the classpath to use to load the classes. May be null, in which case no path elements are set up to start with.

parentFirst - If true, indicates that the parent classloader should be consulted before trying to load the a class through this loader.

ArooaClassLoader

public ArooaClassLoader(java.io.File[] classpath,
                        boolean parentFirst)

Creates a classloader for the given project using the classpath given.

Parameters:

classpath - The classpath to use to load the classes. May be null, in which case no path elements are set up to start with.

parentFirst - If true, indicates that the parent classloader should be consulted before trying to load the a class through this loader.

ArooaClassLoader

public ArooaClassLoader(java.lang.ClassLoader parent,
                        boolean parentFirst)

Creates an empty class loader. The classloader should be configured with path elements to specify where the loader is to look for classes.

Parameters:

parent - The parent classloader to which unsatisfied loading attempts are delegated. May be null, in which case the classloader which loaded this class is used as the parent.

parentFirst - If true, indicates that the parent classloader should be consulted before trying to load the a class through this loader.

Method Detail

setClassPath

public void setClassPath(java.io.File[] classpath)

Set the classpath to search for classes to load. This should not be changed once the classloader starts to server classes

Parameters:

classpath - the search classpath consisting of directories and jar/zip files.

setParent

public void setParent(java.lang.ClassLoader parent)

Set the parent for this class loader. This is the class loader to which this class loader will delegate to load classes

Parameters:

parent - the parent class loader.

setParentFirst

public void setParentFirst(boolean parentFirst)

Control whether class lookup is delegated to the parent loader first or after this loader. Use with extreme caution. Setting this to false violates the class loader hierarchy and can lead to Linkage errors

Parameters:

parentFirst - if true, delegate initial class search to the parent classloader.

addPathFile

protected void addPathFile(java.io.File pathComponent)
                    throws java.io.IOException

Add a file to the path

Parameters:

pathComponent - the file which is to be added to the path for this class loader

Throws:

java.io.IOException - if data needed from the file cannot be read.

getClasspath

public java.lang.String getClasspath()

Returns the classpath this classloader will consult.

Returns:

the classpath used for this classloader, with elements separated by the path separator for the system.

toString

public java.lang.String toString()

setIsolated

public void setIsolated(boolean isolated)

Sets whether this classloader should run in isolated mode. In isolated mode, classes not found on the given classpath will not be referred to the parent class loader but will cause a ClassNotFoundException.

Parameters:

isolated - Whether or not this classloader should run in isolated mode.

initializeClass

public static void initializeClass(java.lang.Class theClass)

Deprecated. use Class.forName with initialize=true instead.

Forces initialization of a class in a JDK 1.1 compatible, albeit hacky way.

Parameters:

theClass - The class to initialize. Must not be null.

addSystemPackageRoot

public void addSystemPackageRoot(java.lang.String packageRoot)

Adds a package root to the list of packages which must be loaded on the parent loader. All subpackages are also included.

Parameters:

packageRoot - The root of all packages to be included. Should not be null.

addLoaderPackageRoot

public void addLoaderPackageRoot(java.lang.String packageRoot)

Adds a package root to the list of packages which must be loaded using this loader. All subpackages are also included.

Parameters:

packageRoot - The root of all packages to be included. Should not be null.

forceLoadClass

public java.lang.Class forceLoadClass(java.lang.String classname)
                               throws java.lang.ClassNotFoundException

Loads a class through this class loader even if that class is available on the parent classpath. This ensures that any classes which are loaded by the returned class will use this classloader.

Parameters:

classname - The name of the class to be loaded. Must not be null.

Returns:

the required Class object

Throws:

java.lang.ClassNotFoundException - if the requested class does not exist on this loader's classpath.

forceLoadSystemClass

public java.lang.Class forceLoadSystemClass(java.lang.String classname)
                                     throws java.lang.ClassNotFoundException

Loads a class through this class loader but defer to the parent class loader. This ensures that instances of the returned class will be compatible with instances which have already been loaded on the parent loader.

Parameters:

classname - The name of the class to be loaded. Must not be null.

Returns:

the required Class object

Throws:

java.lang.ClassNotFoundException - if the requested class does not exist on this loader's classpath.

getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.String name)

Returns a stream to read the requested resource name.

Parameters:

name - The name of the resource for which a stream is required. Must not be null.

Returns:

a stream to the required resource or null if the resource cannot be found on the loader's classpath.

getResource

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

Finds the resource with the given name. A resource is some data (images, audio, text, etc) that can be accessed by class code in a way that is independent of the location of the code.

Parameters:

name - The name of the resource for which a stream is required. Must not be null.

Returns:

a URL for reading the resource, or null if the resource could not be found or the caller doesn't have adequate privileges to get the resource.

findResources

protected java.util.Enumeration findResources(java.lang.String name)
                                       throws java.io.IOException

Returns an enumeration of URLs representing all the resources with the given name by searching the class loader's classpath.

Parameters:

name - The resource name to search for. Must not be null.

Returns:

an enumeration of URLs for the resources

Throws:

java.io.IOException - if I/O errors occurs (can't happen)

getResourceURL

protected java.net.URL getResourceURL(java.io.File file,
                                      java.lang.String resourceName)

Returns the URL of a given resource in the given file which may either be a directory or a zip file.

Parameters:

file - The file (directory or jar) in which to search for the resource. Must not be null.

resourceName - The name of the resource for which a stream is required. Must not be null.

Returns:

a stream to the required resource or null if the resource cannot be found in the given file object.

loadClass

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

Loads a class with this class loader. This class attempts to load the class in an order determined by whether or not the class matches the system/loader package lists, with the loader package list taking priority. If the classloader is in isolated mode, failure to load the class in this loader will result in a ClassNotFoundException.

Parameters:

classname - The name of the class to be loaded. Must not be null.

resolve - true if all classes upon which this class depends are to be loaded.

Returns:

the required Class object

Throws:

java.lang.ClassNotFoundException - if the requested class does not exist on the system classpath (when not in isolated mode) or this loader's classpath.

findClass

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

Searches for and load a class on the classpath of this class loader.

Parameters:

name - The name of the class to be loaded. Must not be null.

Returns:

the required Class object

Throws:

java.lang.ClassNotFoundException - if the requested class does not exist on this loader's classpath.

isInPath

protected boolean isInPath(java.io.File component)

Indicate if the given file is in this loader's path

Parameters:

component - the file which is to be checked

Returns:

true if the file is in the class path

cleanup

public void cleanup()

Cleans up any resources held by this classloader. Any open archive files are closed.

getPath

public java.lang.String getPath()

Get the classpath as a string. useful for debugging.

Returns:

A string classpath.