org.apache.tools.ant.types

Class Path

java.lang.Object

org.apache.tools.ant.ProjectComponent

org.apache.tools.ant.types.DataType

org.apache.tools.ant.types.Path

All Implemented Interfaces:

java.lang.Cloneable, ResourceCollection

public class Path
extends DataType
implements java.lang.Cloneable, ResourceCollection

This object represents a path as used by CLASSPATH or PATH environment variable. A path might also be described as a collection of unique filesystem resources.

<sometask>
<somepath>
<pathelement location="/path/to/file.jar" />
<pathelement path="/path/to/file2.jar:/path/to/class2;/path/to/class3" />
<pathelement location="/path/to/file3.jar" />
<pathelement location="/path/to/file4.jar" />
</somepath>
</sometask>


The object implemention sometask must provide a method called createSomepath which returns an instance of Path. Nested path definitions are handled by the Path object and must be labeled pathelement.

The path element takes a parameter path which will be parsed and split into single elements. It will usually be used to define a path from an environment variable.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	Path.PathElement Helper class, holds the nested <pathelement> values.

Field Summary

Fields

Modifier and Type	Field and Description
static Path	systemBootClasspath The system bootclasspath as a Path object.
static Path	systemClasspath The system classpath as a Path object

Fields inherited from class org.apache.tools.ant.types.DataType

checked, ref

Fields inherited from class org.apache.tools.ant.ProjectComponent

description, location, project

Constructor Summary

Constructors

Constructor and Description
Path(Project project) Construct an empty Path.
Path(Project p, java.lang.String path) Invoked by IntrospectionHelper for setXXX(Path p) attribute setters.

Method Summary

Methods

Modifier and Type	Method and Description
void	add(Path path) Adds a nested path
void	add(ResourceCollection c) Add a nested ResourceCollection.
void	addDirset(DirSet dset) Adds a nested <dirset> element.
void	addExisting(Path source) Adds the components on the given path which exist to this Path.
void	addExisting(Path source, boolean tryUserDir) Same as addExisting, but support classpath behavior if tryUserDir is true.
void	addExtdirs(Path extdirs) Emulation of extdirs feature in java >= 1.2.
void	addFilelist(FileList fl) Adds a nested <filelist> element.
void	addFileset(FileSet fs) Adds a nested <fileset> element.
void	addJavaRuntime() Add the Java Runtime classes to this Path instance.
void	append(Path other) Append the contents of the other Path instance to this.
protected ResourceCollection	assertFilesystemOnly(ResourceCollection rc) Verify the specified ResourceCollection is filesystem-only.
java.lang.Object	clone() Clone this Path.
Path	concatSystemBootClasspath(java.lang.String defValue) Concatenates the system boot class path in the order specified by the ${build.sysclasspath} property - using the supplied value if ${build.sysclasspath} has not been set.
Path	concatSystemClasspath() Concatenates the system class path in the order specified by the ${build.sysclasspath} property - using "last" as default value.
Path	concatSystemClasspath(java.lang.String defValue) Concatenates the system class path in the order specified by the ${build.sysclasspath} property - using the supplied value if ${build.sysclasspath} has not been set.
Path	createPath() Creates a nested <path> element.
Path.PathElement	createPathElement() Creates the nested <pathelement> element.
protected boolean	delegateIteratorToList() Helps determine whether to preserve BC by calling list() on subclasses.
protected void	dieOnCircularReference(java.util.Stack stk, Project p) Overrides the version of DataType to recurse on all DataType child elements that may have been added.
boolean	isFilesystemOnly() Fulfill the ResourceCollection contract.
java.util.Iterator	iterator() Fulfill the ResourceCollection contract.
java.lang.String[]	list() Returns all path elements defined by this and nested path objects.
void	setCache(boolean b) Whether to cache the current path.
void	setLocation(java.io.File location) Adds a element definition to the path.
void	setPath(java.lang.String path) Parses a path definition and creates single PathElements.
void	setRefid(Reference r) Makes this instance in effect a reference to another Path instance.
int	size() Fulfill the ResourceCollection contract.
java.lang.String	toString() Returns a textual representation of the path, which can be used as CLASSPATH or PATH environment variable definition.
static java.lang.String	translateFile(java.lang.String source) Returns its argument with all file separator characters replaced so that they match the local OS conventions.
protected static boolean	translateFileSep(java.lang.StringBuffer buffer, int pos) Translates occurrences at a position of / or \ to correct separator of the current platform and returns whether it had to do a replacement.
static java.lang.String[]	translatePath(Project project, java.lang.String source) Splits a PATH (with : or ; as separators) into its parts.

Methods inherited from class org.apache.tools.ant.types.DataType

checkAttributesAllowed, checkChildrenAllowed, circularReference, dieOnCircularReference, dieOnCircularReference, getCheckedRef, getCheckedRef, getCheckedRef, getCheckedRef, getDataTypeName, getRefid, invokeCircularReferenceCheck, isChecked, isReference, noChildrenAllowed, pushAndInvokeCircularReferenceCheck, setChecked, tooManyAttributes

Methods inherited from class org.apache.tools.ant.ProjectComponent

getDescription, getLocation, getProject, log, log, setDescription, setLocation, setProject

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

systemClasspath

public static Path systemClasspath

The system classpath as a Path object

systemBootClasspath

public static Path systemBootClasspath

The system bootclasspath as a Path object.

Since:

Ant 1.6.2

Constructor Detail

Path

public Path(Project p,
    java.lang.String path)

Invoked by IntrospectionHelper for setXXX(Path p) attribute setters.

Parameters:

p - the Project for this path.

path - the String path definition.

Path

public Path(Project project)

Construct an empty Path.

Parameters:

project - the Project for this path.

Method Detail

setLocation

public void setLocation(java.io.File location)
                 throws BuildException

Adds a element definition to the path.

Parameters:

location - the location of the element to add (must not be null nor empty.

Throws:

BuildException - on error

setPath

public void setPath(java.lang.String path)
             throws BuildException

Parses a path definition and creates single PathElements.

Parameters:

path - the String path definition.

Throws:

BuildException - on error

setRefid

public void setRefid(Reference r)
              throws BuildException

Makes this instance in effect a reference to another Path instance.

You must not set another attribute or nest elements inside this element if you make it a reference.

Overrides:

setRefid in class DataType

Parameters:

r - the reference to another Path

Throws:

BuildException - on error

createPathElement

public Path.PathElement createPathElement()
                                   throws BuildException

Creates the nested <pathelement> element.

Returns:

the PathElement to be configured

Throws:

BuildException - on error

addFileset

public void addFileset(FileSet fs)
                throws BuildException

Adds a nested <fileset> element.

Parameters:

fs - a FileSet to be added to the path

Throws:

BuildException - on error

addFilelist

public void addFilelist(FileList fl)
                 throws BuildException

Adds a nested <filelist> element.

Parameters:

fl - a FileList to be added to the path

Throws:

BuildException - on error

addDirset

public void addDirset(DirSet dset)
               throws BuildException

Adds a nested <dirset> element.

Parameters:

dset - a DirSet to be added to the path

Throws:

BuildException - on error

add

public void add(Path path)
         throws BuildException

Adds a nested path

Parameters:

path - a Path to be added to the path

Throws:

BuildException - on error

Since:

Ant 1.6

add

public void add(ResourceCollection c)

Add a nested ResourceCollection.

Parameters:

c - the ResourceCollection to add.

Since:

Ant 1.7

createPath

public Path createPath()
                throws BuildException

Creates a nested <path> element.

Returns:

a Path to be configured

Throws:

BuildException - on error

append

public void append(Path other)

Append the contents of the other Path instance to this.

Parameters:

other - a Path to be added to the path

addExisting

public void addExisting(Path source)

Adds the components on the given path which exist to this Path. Components that don't exist aren't added.

Parameters:

source - - source path whose components are examined for existence

addExisting

public void addExisting(Path source,
               boolean tryUserDir)

Same as addExisting, but support classpath behavior if tryUserDir is true. Classpaths are relative to user dir, not the project base. That used to break jspc test

Parameters:

source - the source path

tryUserDir - if true try the user directory if the file is not present

setCache

public void setCache(boolean b)

Whether to cache the current path.

Since:

Ant 1.8.0

list

public java.lang.String[] list()

Returns all path elements defined by this and nested path objects.

Returns:

list of path elements.

toString

public java.lang.String toString()

Returns a textual representation of the path, which can be used as CLASSPATH or PATH environment variable definition.

Overrides:

toString in class DataType

Returns:

a textual representation of the path.

translatePath

public static java.lang.String[] translatePath(Project project,
                               java.lang.String source)

Splits a PATH (with : or ; as separators) into its parts.

Parameters:

project - the project to use

source - a String value

Returns:

an array of strings, one for each path element

translateFile

public static java.lang.String translateFile(java.lang.String source)

Returns its argument with all file separator characters replaced so that they match the local OS conventions.

Parameters:

source - the path to convert

Returns:

the converted path

translateFileSep

protected static boolean translateFileSep(java.lang.StringBuffer buffer,
                       int pos)

Translates occurrences at a position of / or \ to correct separator of the current platform and returns whether it had to do a replacement.

Parameters:

buffer - a buffer containing a string

pos - the position in the string buffer to convert

Returns:

true if the character was a / or \

size

public int size()

Fulfill the ResourceCollection contract.

Specified by:

size in interface ResourceCollection

Returns:

number of elements as int.

clone

public java.lang.Object clone()

Clone this Path.

Overrides:

clone in class DataType

Returns:

Path with shallowly cloned Resource children.

dieOnCircularReference

protected void dieOnCircularReference(java.util.Stack stk,
                          Project p)
                               throws BuildException

Overrides the version of DataType to recurse on all DataType child elements that may have been added.

Overrides:

dieOnCircularReference in class DataType

Parameters:

stk - the stack of data types to use (recursively).

p - the project to use to dereference the references.

Throws:

BuildException - on error.

concatSystemClasspath

public Path concatSystemClasspath()

Concatenates the system class path in the order specified by the ${build.sysclasspath} property - using "last" as default value.

Returns:

the concatenated path

concatSystemClasspath

public Path concatSystemClasspath(java.lang.String defValue)

Concatenates the system class path in the order specified by the ${build.sysclasspath} property - using the supplied value if ${build.sysclasspath} has not been set.

Parameters:

defValue - the order ("first", "last", "only")

Returns:

the concatenated path

concatSystemBootClasspath

public Path concatSystemBootClasspath(java.lang.String defValue)

Concatenates the system boot class path in the order specified by the ${build.sysclasspath} property - using the supplied value if ${build.sysclasspath} has not been set.

Parameters:

defValue - the order ("first", "last", "only")

Returns:

the concatenated path

addJavaRuntime

public void addJavaRuntime()

Add the Java Runtime classes to this Path instance.

addExtdirs

public void addExtdirs(Path extdirs)

Emulation of extdirs feature in java >= 1.2. This method adds all files in the given directories (but not in sub-directories!) to the classpath, so that you don't have to specify them all one by one.

Parameters:

extdirs - - Path to append files to

iterator

public final java.util.Iterator iterator()

Fulfill the ResourceCollection contract. The Iterator returned will throw ConcurrentModificationExceptions if ResourceCollections are added to this container while the Iterator is in use.

Specified by:

iterator in interface ResourceCollection

Returns:

a "fail-fast" Iterator.

isFilesystemOnly

public boolean isFilesystemOnly()

Fulfill the ResourceCollection contract.

Specified by:

isFilesystemOnly in interface ResourceCollection

Returns:

whether this is a filesystem-only resource collection.

assertFilesystemOnly

protected ResourceCollection assertFilesystemOnly(ResourceCollection rc)

Verify the specified ResourceCollection is filesystem-only.

Parameters:

rc - the ResourceCollection to check.

Returns:

the passed in ResourceCollection.

Throws:

BuildException - if rc is not filesystem-only.

delegateIteratorToList

protected boolean delegateIteratorToList()

Helps determine whether to preserve BC by calling list() on subclasses. The default behavior of this method is to return true for any subclass that implements list(); this can, of course, be avoided by overriding this method to return false. It is not expected that the result of this method should change over time, thus it is called only once.

Returns:

true if iterator() should delegate to list().