org.apache.tools.ant.types

Class Path

public class Path extends DataType implements 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
classPath.PathElement
Helper class, holds the nested <pathelement> values.
Field Summary
static PathsystemBootClasspath
The system bootclasspath as a Path object.
static PathsystemClasspath
The system classpath as a Path object
Constructor Summary
Path(Project p, String path)
Invoked by IntrospectionHelper for setXXX(Path p) attribute setters.
Path(Project project)
Construct an empty Path.
Method Summary
voidadd(Path path)
Adds a nested path
voidadd(ResourceCollection c)
Add a nested ResourceCollection.
voidaddDirset(DirSet dset)
Adds a nested <dirset> element.
voidaddExisting(Path source)
Adds the components on the given path which exist to this Path.
voidaddExisting(Path source, boolean tryUserDir)
Same as addExisting, but support classpath behavior if tryUserDir is true.
voidaddExtdirs(Path extdirs)
Emulation of extdirs feature in java >= 1.2.
voidaddFilelist(FileList fl)
Adds a nested <filelist> element.
voidaddFileset(FileSet fs)
Adds a nested <fileset> element.
voidaddJavaRuntime()
Add the Java Runtime classes to this Path instance.
voidappend(Path other)
Append the contents of the other Path instance to this.
protected ResourceCollectionassertFilesystemOnly(ResourceCollection rc)
Verify the specified ResourceCollection is filesystem-only.
Objectclone()
Clone this Path.
PathconcatSystemBootClasspath(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.
PathconcatSystemClasspath()
Concatenates the system class path in the order specified by the ${build.sysclasspath} property - using "last" as default value.
PathconcatSystemClasspath(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.
PathcreatePath()
Creates a nested <path> element.
Path.PathElementcreatePathElement()
Creates the nested <pathelement> element.
protected booleandelegateIteratorToList()
Helps determine whether to preserve BC by calling list() on subclasses.
protected voiddieOnCircularReference(Stack stk, Project p)
Overrides the version of DataType to recurse on all DataType child elements that may have been added.
booleanisFilesystemOnly()
Fulfill the ResourceCollection contract.
Iteratoriterator()
Fulfill the ResourceCollection contract.
String[]list()
Returns all path elements defined by this and nested path objects.
voidsetCache(boolean b)
Whether to cache the current path.
voidsetLocation(File location)
Adds a element definition to the path.
voidsetPath(String path)
Parses a path definition and creates single PathElements.
voidsetRefid(Reference r)
Makes this instance in effect a reference to another Path instance.
intsize()
Fulfill the ResourceCollection contract.
StringtoString()
Returns a textual representation of the path, which can be used as CLASSPATH or PATH environment variable definition.
static StringtranslateFile(String source)
Returns its argument with all file separator characters replaced so that they match the local OS conventions.
protected static booleantranslateFileSep(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 String[]translatePath(Project project, String source)
Splits a PATH (with : or ; as separators) into its parts.

Field Detail

systemBootClasspath

public static Path systemBootClasspath
The system bootclasspath as a Path object.

Since: Ant 1.6.2

systemClasspath

public static Path systemClasspath
The system classpath as a Path object

Constructor Detail

Path

public Path(Project p, 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

add

public void add(Path path)
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

addDirset

public void addDirset(DirSet dset)
Adds a nested <dirset> element.

Parameters: dset a DirSet to be added to the path

Throws: BuildException on error

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

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

addFilelist

public void addFilelist(FileList fl)
Adds a nested <filelist> element.

Parameters: fl a FileList to be added to the path

Throws: BuildException on error

addFileset

public void addFileset(FileSet fs)
Adds a nested <fileset> element.

Parameters: fs a FileSet to be added to the path

Throws: BuildException on error

addJavaRuntime

public void addJavaRuntime()
Add the Java Runtime classes to this Path instance.

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

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.

clone

public Object clone()
Clone this Path.

Returns: Path with shallowly cloned Resource children.

concatSystemBootClasspath

public Path concatSystemBootClasspath(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

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

createPath

public Path createPath()
Creates a nested <path> element.

Returns: a Path to be configured

Throws: BuildException on error

createPathElement

public Path.PathElement createPathElement()
Creates the nested <pathelement> element.

Returns: the PathElement to be configured

Throws: BuildException on error

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

dieOnCircularReference

protected void dieOnCircularReference(Stack stk, Project p)
Overrides the version of DataType to recurse on all DataType child elements that may have been added.

Parameters: stk the stack of data types to use (recursively). p the project to use to dereference the references.

Throws: BuildException on error.

isFilesystemOnly

public boolean isFilesystemOnly()
Fulfill the ResourceCollection contract.

Returns: whether this is a filesystem-only resource collection.

iterator

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

Returns: a "fail-fast" Iterator.

list

public String[] list()
Returns all path elements defined by this and nested path objects.

Returns: list of path elements.

setCache

public void setCache(boolean b)
Whether to cache the current path.

Since: Ant 1.8.0

setLocation

public void setLocation(File location)
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(String path)
Parses a path definition and creates single PathElements.

Parameters: path the String path definition.

Throws: BuildException on error

setRefid

public void setRefid(Reference r)
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.

Parameters: r the reference to another Path

Throws: BuildException on error

size

public int size()
Fulfill the ResourceCollection contract.

Returns: number of elements as int.

toString

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

Returns: a textual representation of the path.

translateFile

public static String translateFile(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(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 \

translatePath

public static String[] translatePath(Project project, 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