org.acm.seguin.project
Class ProjectClassLoader

java.lang.Object
  extended by java.lang.ClassLoader
      extended by org.acm.seguin.project.ProjectClassLoader

public class ProjectClassLoader
extends java.lang.ClassLoader

Used to load classes within ant with a different claspath 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.

Since:
2.8.01
Version:
$Id: ProjectClassLoader.java,v 1.4 2004/03/25 20:24:34 mikeatkinson Exp $
Author:
Conor MacNeill, Jesse Glick, Magesh Umasankar, Mike Atkinson

Constructor Summary
ProjectClassLoader(java.lang.ClassLoader parent, boolean parentFirst)
          Creates an empty class loader.
ProjectClassLoader(java.lang.ClassLoader parent, Project project, boolean parentFirst)
          Creates a classloader for the given project.
ProjectClassLoader(Project project)
          Creates a classloader for the given project.
ProjectClassLoader(Project project, boolean parentFirst)
          Creates a classloader for the given project.
 
Method Summary
 void addLoaderPackageRoot(java.lang.String packageRoot)
          Adds a package root to the list of packages which must be loaded using this loader.
 void addPathElement(java.lang.String pathElement)
          Adds an element to the classpath to be searched.
 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.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.
static void initializeClass(java.lang.Class theClass)
          Forces initialization of a class in a JDK 1.1 compatible, albeit hacky way.
protected  java.lang.Class loadClass(java.lang.String classname, boolean resolve)
          Loads a class with this class loader.
protected  void log(java.lang.String message)
          Logs a message through the project object if one has been provided.
 void setIsolated(boolean isolated)
          Sets whether this classloader should run in isolated mode.
 
Methods inherited from class java.lang.ClassLoader
clearAssertionStatus, defineClass, 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, toString, wait, wait, wait
 

Constructor Detail

ProjectClassLoader

public ProjectClassLoader(Project project)
Creates a classloader for the given project.

Parameters:
project - The project to which this classloader is to belong. Must not be null.

ProjectClassLoader

public ProjectClassLoader(java.lang.ClassLoader parent,
                          Project project,
                          boolean parentFirst)
Creates a classloader for the given project.

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.
project - The project to which this classloader is to belong. Must not be null.
parentFirst - If true, indicates that the parent classloader should be consulted before trying to load the a class through this loader.

ProjectClassLoader

public ProjectClassLoader(Project project,
                          boolean parentFirst)
Creates a classloader for the given project.

Parameters:
project - The project to which this classloader is to belong. Must not be null.
parentFirst - If true, indicates that the parent classloader should be consulted before trying to load the a class through this loader.

ProjectClassLoader

public ProjectClassLoader(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

log

protected void log(java.lang.String message)
Logs a message through the project object if one has been provided.

Parameters:
message - The message to log. Should not be null.
priority - The logging priority of the message.

addPathElement

public void addPathElement(java.lang.String pathElement)
                    throws ProjectException
Adds an element to the classpath to be searched.

Parameters:
pathElement - The path element to add. Must not be null.
Throws:
ProjectException - if the given path element cannot be resolved against the project.

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.

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

Overrides:
getResourceAsStream in class java.lang.ClassLoader
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.

Overrides:
getResource in class java.lang.ClassLoader
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.

Overrides:
findResources in class java.lang.ClassLoader
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)

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.

Overrides:
loadClass in class java.lang.ClassLoader
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.

Overrides:
findClass in class java.lang.ClassLoader
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.

cleanup

public void cleanup()
Cleans up any resources held by this classloader. Any open archive files are closed.