Top Description Inners Fields Constructors Methods
org.apache.tools.ant.util

public Class ClasspathUtils

extends Object
Class Inheritance
Imports
org.apache.tools.ant.AntClassLoader, .BuildException, .MagicNames, .Project, .ProjectComponent, org.apache.tools.ant.types.Path, .Reference, java.lang.reflect.InvocationTargetException, .Modifier
Offers some helper methods on the Path structure in ant.

The basic idea behind this utility class is to use it from inside the different Ant objects (and user defined objects) that need classLoading for their operation. Normally those would have a setClasspathRef() {for the @classpathref} and/or a createClasspath() {for the nested <classpath>} Typically one would have in your Ant Task or DataType


ClasspathUtils.Delegate cpDelegate;

public void init() {
    this.cpDelegate = ClasspathUtils.getDelegate(this);
    super.init();
}

public void setClasspathRef(Reference r) {
    this.cpDelegate.setClasspathRef(r);
}

public Path createClasspath() {
    return this.cpDelegate.createClasspath();
}

public void setClassname(String fqcn) {
    this.cpDelegate.setClassname(fqcn);
}

At execution time, when you actually need the classloading you can just:


    Object o = this.cpDelegate.newInstance();
Since
Ant 1.6

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
ClasspathUtils.Delegate

Delegate that helps out any specific ProjectComponent that needs dynamic classloading.

Field Summary

Modifier and TypeField and Description
public static final String
REUSE_LOADER_REF

Name of the magic property that controls classloader reuse in Ant 1.4.

Constructor Summary

AccessConstructor and Description
private
ClasspathUtils()

Method Summary

Modifier and TypeMethod and Description
public static ClassLoader

Returns:

The class loader
getClassLoaderForPath(Project
the project
p, Reference
the reference
ref)

Convenience overloaded version of getClassLoaderForPath(Project, Reference, boolean).

public static ClassLoader

Returns:

The class loader
getClassLoaderForPath(Project
current Ant project
p, Reference
Reference to Path structure
ref, boolean
if set to true this new loader will take precedence over its parent (which is contra the regular classloader behaviour)
reverseLoader)

Convenience overloaded version of getClassLoaderForPath(Project, Path, String, boolean).

public static ClassLoader

Returns:

The class loader
getClassLoaderForPath(Project
current Ant project
p, Path
the path
path, String
the loader id string
loaderId)

Convenience overloaded version of getClassLoaderForPath(Project, Path, String, boolean).

public static ClassLoader

Returns:

The class loader
getClassLoaderForPath(Project
the project
p, Path
the path
path, String
the loader id string
loaderId, boolean
if set to true this new loader will take precedence over its parent (which is contra the regular classloader behaviour)
reverseLoader)

Convenience overloaded version of getClassLoaderForPath(Project, Path, String, boolean, boolean).

public static ClassLoader

Returns:

ClassLoader that uses the Path as its classpath.
getClassLoaderForPath(Project
Ant Project where the handled components are living in.
p, Path
Path object to be used as classpath for this classloader
path, String
identification for this Loader,
loaderId, boolean
if set to true this new loader will take precedence over its parent (which is contra the regular classloader behaviour)
reverseLoader, boolean
if true reuse the loader if it is found
reuseLoader)

Gets a classloader that loads classes from the classpath defined in the path argument.

public static ClasspathUtils.Delegate

Returns:

the helper, delegate.
getDelegate(ProjectComponent
your projectComponent that needs the assistance
component)

Obtains a delegate that helps out with classic classpath configuration.

public static ClassLoader

Returns:

The fresh, different, previously unused class loader.
getUniqueClassLoaderForPath(Project
Ant Project where the handled components are living in.
p, Path
the classpath for this loader
path, boolean
if set to true this new loader will take precedence over its parent (which is contra the regular classloader behaviour)
reverseLoader)

Gets a fresh, different, previously unused classloader that uses the passed path as its classpath.

private static boolean
isMagicPropertySet(Project p)

Checks for the magic property that enables class loader reuse for <taskdef> and <typedef> in Ant 1.5 and earlier.

public static Object

Returns:

The fresh object instance
newInstance(String
the full qualified class name to load.
className, ClassLoader
the classloader to use.
userDefinedLoader)

Creates a fresh object instance of the specified classname.

public static <
desired type
T> T

Returns:

The fresh object instance
newInstance(String
the full qualified class name to load.
className, ClassLoader
the classloader to use.
userDefinedLoader, Class<T>
the Class that the result should be assignment compatible with. (No ClassCastException will be thrown in case the result of this method is casted to the expectedType)
expectedType)

Creates a fresh object instance of the specified classname.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

REUSE_LOADER_REFback to summary
public static final String REUSE_LOADER_REF

Name of the magic property that controls classloader reuse in Ant 1.4.

Constructor Detail

ClasspathUtilsback to summary
private ClasspathUtils()

Method Detail

getClassLoaderForPathback to summary
public static ClassLoader getClassLoaderForPath(Project p, Reference ref)

Convenience overloaded version of getClassLoaderForPath(Project, Reference, boolean).

Assumes the logical 'false' for the reverseLoader.

Parameters
p:Project

the project

ref:Reference

the reference

Returns:ClassLoader

The class loader

getClassLoaderForPathback to summary
public static ClassLoader getClassLoaderForPath(Project p, Reference ref, boolean reverseLoader)

Convenience overloaded version of getClassLoaderForPath(Project, Path, String, boolean).

Delegates to the other one after extracting the referenced Path from the Project. This checks also that the passed Reference is pointing to a Path all right.

Parameters
p:Project

current Ant project

ref:Reference

Reference to Path structure

reverseLoader:boolean

if set to true this new loader will take precedence over its parent (which is contra the regular classloader behaviour)

Returns:ClassLoader

The class loader

getClassLoaderForPathback to summary
public static ClassLoader getClassLoaderForPath(Project p, Path path, String loaderId)

Convenience overloaded version of getClassLoaderForPath(Project, Path, String, boolean).

Assumes the logical 'false' for the reverseLoader.

Parameters
p:Project

current Ant project

path:Path

the path

loaderId:String

the loader id string

Returns:ClassLoader

The class loader

getClassLoaderForPathback to summary
public static ClassLoader getClassLoaderForPath(Project p, Path path, String loaderId, boolean reverseLoader)

Convenience overloaded version of getClassLoaderForPath(Project, Path, String, boolean, boolean).

Sets value for 'reuseLoader' to true if the magic property has been set.

Parameters
p:Project

the project

path:Path

the path

loaderId:String

the loader id string

reverseLoader:boolean

if set to true this new loader will take precedence over its parent (which is contra the regular classloader behaviour)

Returns:ClassLoader

The class loader

getClassLoaderForPathback to summary
public static ClassLoader getClassLoaderForPath(Project p, Path path, String loaderId, boolean reverseLoader, boolean reuseLoader)

Gets a classloader that loads classes from the classpath defined in the path argument.

Based on the setting of the magic property 'ant.reuse.loader' this will try to reuse the previously created loader with that id, and of course store it there upon creation.

Parameters
p:Project

Ant Project where the handled components are living in.

path:Path

Path object to be used as classpath for this classloader

loaderId:String

identification for this Loader,

reverseLoader:boolean

if set to true this new loader will take precedence over its parent (which is contra the regular classloader behaviour)

reuseLoader:boolean

if true reuse the loader if it is found

Returns:ClassLoader

ClassLoader that uses the Path as its classpath.

getDelegateback to summary
public static ClasspathUtils.Delegate getDelegate(ProjectComponent component)

Obtains a delegate that helps out with classic classpath configuration.

Parameters
component:ProjectComponent

your projectComponent that needs the assistance

Returns:ClasspathUtils.Delegate

the helper, delegate.

See Also
ClasspathUtils.Delegate
getUniqueClassLoaderForPathback to summary
public static ClassLoader getUniqueClassLoaderForPath(Project p, Path path, boolean reverseLoader)

Gets a fresh, different, previously unused classloader that uses the passed path as its classpath.

This method completely ignores the ant.reuse.loader magic property and should be used with caution.

Parameters
p:Project

Ant Project where the handled components are living in.

path:Path

the classpath for this loader

reverseLoader:boolean

if set to true this new loader will take precedence over its parent (which is contra the regular classloader behaviour)

Returns:ClassLoader

The fresh, different, previously unused class loader.

isMagicPropertySetback to summary
private static boolean isMagicPropertySet(Project p)

Checks for the magic property that enables class loader reuse for and in Ant 1.5 and earlier.

newInstanceback to summary
public static Object newInstance(String className, ClassLoader userDefinedLoader)

Creates a fresh object instance of the specified classname.

This uses the userDefinedLoader to load the specified class, and then makes an instance using the default no-argument constructor.

Parameters
className:String

the full qualified class name to load.

userDefinedLoader:ClassLoader

the classloader to use.

Returns:Object

The fresh object instance

Exceptions
BuildException:
when loading or instantiation failed.
newInstanceback to summary
public static <T> T newInstance(String className, ClassLoader userDefinedLoader, Class<T> expectedType)

Creates a fresh object instance of the specified classname.

This uses the userDefinedLoader to load the specified class, and then makes an instance using the default no-argument constructor.

Parameters
<T>
desired type
className:String

the full qualified class name to load.

userDefinedLoader:ClassLoader

the classloader to use.

expectedType:Class<T>

the Class that the result should be assignment compatible with. (No ClassCastException will be thrown in case the result of this method is casted to the expectedType)

Returns:T

The fresh object instance

Exceptions
BuildException:
when loading or instantiation failed.
Since
Ant 1.7
org.apache.tools.ant.util back to summary

public Class ClasspathUtils.Delegate

extends Object
Class Inheritance
Delegate that helps out any specific ProjectComponent that needs dynamic classloading.

Ant ProjectComponents that need a to be able to dynamically load Classes and instantiate them often expose the following ant syntax sugar:

This class functions as a delegate handling the configuration issues for this recurring pattern. Its usage pattern, as the name suggests, is delegation rather than inheritance.

Since
Ant 1.6

Field Summary

Modifier and TypeField and Description
private String
className

private Path
classpath

private String
classpathId

private final ProjectComponent
component

private String
loaderId

private boolean
reverseLoader

Constructor Summary

AccessConstructor and Description
pack-priv
Delegate(ProjectComponent
the ProjectComponent this delegate is for.
component)

Construct a Delegate

Method Summary

Modifier and TypeMethod and Description
public Path

Returns:

the created path.
createClasspath()

Delegate method handling the <classpath> tag.

public ClassLoader

Returns:

The class loader.
getClassLoader()

Finds or creates the classloader for this object.

public String

Returns:

a loader identifier.
getClassLoadId()

Computes the loaderId based on the configuration of the component.

public Path

Returns:

the classpath.
getClasspath()

The classpath.

private Project
getContextProject()

The project of the ProjectComponent we are working for.

public boolean

Returns:

true if looking up in reverse order.
isReverseLoader()

Get the reverseLoader setting.

public Object

Returns:

the fresh instantiated object.
newInstance()

Helper method obtaining a fresh instance of the class specified in the @classname and using the specified classpath.

public void
setClassname(String
the name of the class to load.
fcqn)

Delegate method handling the @classname attribute.

public void
setClasspath(Path
the path to use for the classpath.
classpath)

This method is a Delegate method handling the @classpath attribute.

public void
setClasspathref(Reference
the reference to the classpath.
r)

Delegate method handling the @classpathref attribute.

public void
setLoaderRef(Reference
the reference to the loader.
r)

Sets the loaderRef.

public void
setReverseLoader(boolean
if true reverse the order of looking up a class.
reverseLoader)

Delegate method handling the @reverseLoader attribute.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

classNameback to summary
private String className
classpathback to summary
private Path classpath
classpathIdback to summary
private String classpathId
componentback to summary
private final ProjectComponent component
loaderIdback to summary
private String loaderId
reverseLoaderback to summary
private boolean reverseLoader

Constructor Detail

Delegateback to summary
pack-priv Delegate(ProjectComponent component)

Construct a Delegate

Parameters
component:ProjectComponent

the ProjectComponent this delegate is for.

Method Detail

createClasspathback to summary
public Path createClasspath()

Delegate method handling the <classpath> tag.

This nested path-like structure can set a path to add to the classpath.

Returns:Path

the created path.

getClassLoaderback to summary
public ClassLoader getClassLoader()

Finds or creates the classloader for this object.

Returns:ClassLoader

The class loader.

getClassLoadIdback to summary
public String getClassLoadId()

Computes the loaderId based on the configuration of the component.

Returns:String

a loader identifier.

getClasspathback to summary
public Path getClasspath()

The classpath.

Returns:Path

the classpath.

getContextProjectback to summary
private Project getContextProject()

The project of the ProjectComponent we are working for.

isReverseLoaderback to summary
public boolean isReverseLoader()

Get the reverseLoader setting.

Returns:boolean

true if looking up in reverse order.

newInstanceback to summary
public Object newInstance()

Helper method obtaining a fresh instance of the class specified in the @classname and using the specified classpath.

Returns:Object

the fresh instantiated object.

setClassnameback to summary
public void setClassname(String fcqn)

Delegate method handling the @classname attribute.

This attribute sets the full qualified class name of the class to load and instantiate.

Parameters
fcqn:String

the name of the class to load.

setClasspathback to summary
public void setClasspath(Path classpath)

This method is a Delegate method handling the @classpath attribute.

This attribute can set a path to add to the classpath.

Parameters
classpath:Path

the path to use for the classpath.

setClasspathrefback to summary
public void setClasspathref(Reference r)

Delegate method handling the @classpathref attribute.

This attribute can add a referenced path-like structure to the classpath.

Parameters
r:Reference

the reference to the classpath.

setLoaderRefback to summary
public void setLoaderRef(Reference r)

Sets the loaderRef.

Parameters
r:Reference

the reference to the loader.

setReverseLoaderback to summary
public void setReverseLoader(boolean reverseLoader)

Delegate method handling the @reverseLoader attribute.

This attribute can set a boolean indicating that the used classloader should NOT follow the classical parent-first scheme.

By default this is supposed to be false.

Caution: this behaviour is contradictory to the normal way classloaders work. Do not let your ProjectComponent use it if you are not really sure.

Parameters
reverseLoader:boolean

if true reverse the order of looking up a class.