org.apache.tools.ant

Class AntClassLoader

public class AntClassLoader extends ClassLoader implements SubBuildListener

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.

Note that this classloader has a feature to allow loading in reverse order and for "isolation". Due to the fact that a number of methods in java.lang.ClassLoader are final (at least in java 1.4 getResources) this means that the class has to fake the given parent.

Constructor Summary
	AntClassLoader(ClassLoader parent, Project project, Path classpath) Create an Ant ClassLoader for a given project, with a parent classloader and an initial classpath.
	AntClassLoader() Create an Ant Class Loader
	AntClassLoader(Project project, Path classpath) Creates a classloader for the given project using the classpath given.
	AntClassLoader(ClassLoader parent, Project project, Path classpath, boolean parentFirst) Creates a classloader for the given project using the classpath given.
	AntClassLoader(Project project, Path classpath, boolean parentFirst) Creates a classloader for the given project using the classpath given.
	AntClassLoader(ClassLoader parent, boolean parentFirst) Creates an empty class loader.

Method Summary
void	addJavaLibraries() add any libraries that come with different java versions here
void	addLoaderPackageRoot(String packageRoot) Adds a package root to the list of packages which must be loaded using this loader.
void	addPathComponent(File file) Add a path component.
void	addPathElement(String pathElement) Adds an element to the classpath to be searched.
protected void	addPathFile(File pathComponent) Add a file to the path.
void	addSystemPackageRoot(String packageRoot) Adds a package root to the list of packages which must be loaded on the parent loader.
void	buildFinished(BuildEvent event) Cleans up any resources held by this classloader at the end of a build.
void	buildStarted(BuildEvent event) Empty implementation to satisfy the BuildListener interface.
void	cleanup() Cleans up any resources held by this classloader.
protected Class	defineClassFromData(File container, byte[] classData, String classname) Define a class given its bytes
protected void	definePackage(File container, String className) Define the package information associated with a class.
protected void	definePackage(File container, String packageName, Manifest manifest) Define the package information when the class comes from a jar with a manifest
Class	findClass(String name) Searches for and load a class on the classpath of this class loader.
protected Enumeration	findResources(String name) Returns an enumeration of URLs representing all the resources with the given name by searching the class loader's classpath.
Class	forceLoadClass(String classname) Loads a class through this class loader even if that class is available on the parent classpath.
Class	forceLoadSystemClass(String classname) Loads a class through this class loader but defer to the parent class loader.
String	getClasspath() Returns the classpath this classloader will consult.
URL	getResource(String name) Finds the resource with the given name.
InputStream	getResourceAsStream(String name) Returns a stream to read the requested resource name.
protected URL	getResourceURL(File file, 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(Class theClass) Forces initialization of a class in a JDK 1.1 compatible, albeit hacky way.
protected boolean	isInPath(File component) Indicate if the given file is in this loader's path
protected Class	loadClass(String classname, boolean resolve) Loads a class with this class loader.
protected void	log(String message, int priority) Logs a message through the project object if one has been provided.
void	messageLogged(BuildEvent event) Empty implementation to satisfy the BuildListener interface.
void	resetThreadContextLoader() Resets the current thread's context loader to its original value.
void	setClassPath(Path 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(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.
void	setProject(Project project) Set the project associated with this class loader
void	setThreadContextLoader() Sets the current thread's context loader to this classloader, storing the current loader value for later resetting.
void	subBuildFinished(BuildEvent event) Cleans up any resources held by this classloader at the end of a subbuild if it has been created for the subbuild's project instance.
void	subBuildStarted(BuildEvent event) Empty implementation to satisfy the BuildListener interface.
void	targetFinished(BuildEvent event) Empty implementation to satisfy the BuildListener interface.
void	targetStarted(BuildEvent event) Empty implementation to satisfy the BuildListener interface.
void	taskFinished(BuildEvent event) Empty implementation to satisfy the BuildListener interface.
void	taskStarted(BuildEvent event) Empty implementation to satisfy the BuildListener interface.
String	toString() Returns a `String` representing this loader.

Constructor Detail

AntClassLoader

public AntClassLoader(ClassLoader parent, Project project, Path classpath)

Create an Ant ClassLoader for a given project, with a parent classloader and an initial classpath.

Parameters: parent the parent for this classloader. project The project to which this classloader is to belong. classpath The classpath to use to load classes.

Since: Ant 1.7.

AntClassLoader

public AntClassLoader()

Create an Ant Class Loader

AntClassLoader

public AntClassLoader(Project project, Path classpath)

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

Parameters: project The project to which this classloader is to belong. Must not be null. 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.

AntClassLoader

public AntClassLoader(ClassLoader parent, Project project, Path 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. project The project to which this classloader is to belong. Must not be null. 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.

AntClassLoader

public AntClassLoader(Project project, Path classpath, boolean parentFirst)

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

Parameters: project The project to which this classloader is to belong. Must not be null. 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.

AntClassLoader

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

addJavaLibraries

public void addJavaLibraries()

add any libraries that come with different java versions here

addLoaderPackageRoot

public void addLoaderPackageRoot(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.

addPathComponent

public void addPathComponent(File file)

Add a path component. This simply adds the file, unlike addPathElement it does not open jar files and load files from their CLASSPATH entry in the manifest file.

Parameters: file the jar file or directory to add.

addPathElement

public void addPathElement(String pathElement)

Adds an element to the classpath to be searched.

Parameters: pathElement The path element to add. Must not be null.

Throws: BuildException if the given path element cannot be resolved against the project.

addPathFile

protected void addPathFile(File pathComponent)

Add a file to the path. Reads the manifest, if available, and adds any additional class path jars specified in the manifest.

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

Throws: IOException if data needed from the file cannot be read.

addSystemPackageRoot

public void addSystemPackageRoot(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.

buildFinished

public void buildFinished(BuildEvent event)

Cleans up any resources held by this classloader at the end of a build.

Parameters: event the buildFinished event

buildStarted

public void buildStarted(BuildEvent event)

Empty implementation to satisfy the BuildListener interface.

Parameters: event the buildStarted event

cleanup

public void cleanup()

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

defineClassFromData

protected Class defineClassFromData(File container, byte[] classData, String classname)

Define a class given its bytes

Parameters: container the container from which the class data has been read may be a directory or a jar/zip file. classData the bytecode data for the class classname the name of the class

Returns: the Class instance created from the given data

Throws: IOException if the class data cannot be read.

definePackage

protected void definePackage(File container, String className)

Define the package information associated with a class.

Parameters: container the file containing the class definition. className the class name of for which the package information is to be determined.

Throws: IOException if the package information cannot be read from the container.

definePackage

protected void definePackage(File container, String packageName, Manifest manifest)

Define the package information when the class comes from a jar with a manifest

Parameters: container the jar file containing the manifest packageName the name of the package being defined. manifest the jar's manifest

findClass

public Class findClass(String name)

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: ClassNotFoundException if the requested class does not exist on this loader's classpath.

findResources

protected Enumeration findResources(String name)

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: IOException if I/O errors occurs (can't happen)

forceLoadClass

public Class forceLoadClass(String classname)

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: ClassNotFoundException if the requested class does not exist on this loader's classpath.

forceLoadSystemClass

public Class forceLoadSystemClass(String classname)

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: ClassNotFoundException if the requested class does not exist on this loader's classpath.

getClasspath

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

getResource

public URL getResource(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.

getResourceAsStream

public InputStream getResourceAsStream(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.

getResourceURL

protected URL getResourceURL(File file, 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.

initializeClass

public static void initializeClass(Class theClass)

Deprecated: since 1.6.x. 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.

isInPath

protected boolean isInPath(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

loadClass

protected Class loadClass(String classname, boolean resolve)

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: ClassNotFoundException if the requested class does not exist on the system classpath (when not in isolated mode) or this loader's classpath.

log

protected void log(String message, int priority)

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.

messageLogged

public void messageLogged(BuildEvent event)

Empty implementation to satisfy the BuildListener interface.

Parameters: event the messageLogged event

resetThreadContextLoader

public void resetThreadContextLoader()

Resets the current thread's context loader to its original value.

setClassPath

public void setClassPath(Path 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.

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.

setParent

public void setParent(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.