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

public Class Path

extends DataType
implements Cloneable, ResourceCollection
Class Inheritance
All Implemented Interfaces
org.apache.tools.ant.types.ResourceCollection, java.lang.Iterable, java.lang.Cloneable
Imports
java.io.File, java.lang.reflect.Method, java.util.ArrayList, .Arrays, .Collections, .Iterator, .List, .Locale, .Stack, org.apache.tools.ant.BuildException, .MagicNames, .PathTokenizer, .Project, org.apache.tools.ant.types.resources.FileResourceIterator, .Union, org.apache.tools.ant.util.FileUtils, .JavaEnvUtils
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 implementation 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 and Inner Type Summary

Modifier and TypeClass and Description
public class
Path.PathElement

Helper class, holds the nested <pathelement> values.

Field Summary

Modifier and TypeField and Description
private boolean
cache

private Boolean
preserveBC

public static final Path
systemBootClasspath

The system bootclasspath as a Path object.

public static Path
systemClasspath

The system classpath as a Path object

private Union
union

Inherited from org.apache.tools.ant.types.DataType:
checkedref

Constructor Summary

AccessConstructor and Description
public
Path(Project
the Project for this path.
p, String
the String path definition.
path)

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

public
Path(Project
the Project for this path.
project)

Construct an empty Path.

Method Summary

Modifier and TypeMethod and Description
public void
add(Path
a Path to be added to the path
path)

Adds a nested path

public void
add(ResourceCollection
the ResourceCollection to add.
c)

Add a nested ResourceCollection.

public void
addDirset(DirSet
a DirSet to be added to the path
dset)

Adds a nested <dirset> element.

public void
addExisting(Path
- source path whose components are examined for existence
source)

Adds the components on the given path which exist to this Path.

public void
addExisting(Path
the source path
source, boolean
if true try the user directory if the file is not present
tryUserDir)

Same as addExisting, but support classpath behavior if tryUserDir is true.

public void
addExtdirs(Path
- Path to append files to
extdirs)

Emulation of extdirs feature in Java >= 1.2.

public void
addFilelist(FileList
a FileList to be added to the path
fl)

Adds a nested <filelist> element.

public void
addFileset(FileSet
a FileSet to be added to the path
fs)

Adds a nested <fileset> element.

public void
addJavaRuntime()

Add the Java Runtime classes to this Path instance.

public void
append(Path
a Path to be added to the path
other)

Append the contents of the other Path instance to this.

protected ResourceCollection

Returns:

the passed in ResourceCollection.
assertFilesystemOnly(ResourceCollection
the ResourceCollection to check.
rc)

Verify the specified ResourceCollection is filesystem-only.

public Object

Returns:

Path with shallowly cloned Resource children.
clone()

Overrides org.apache.tools.ant.types.DataType.clone.

Clone this Path.
private Path
concatSpecialPath(String defValue, Path p)

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

public Path

Returns:

the concatenated path
concatSystemBootClasspath(String
the order ("first", "last", "only")
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.

public Path

Returns:

the concatenated path
concatSystemClasspath()

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

public Path

Returns:

the concatenated path
concatSystemClasspath(String
the order ("first", "last", "only")
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.

private static boolean
containsWildcards(String path)

Does the given file name contain wildcards?

public Path

Returns:

a Path to be configured
createPath()

Creates a nested <path> element.

public Path.PathElement

Returns:

the PathElement to be configured
createPathElement()

Creates the nested <pathelement> element.

protected boolean

Returns:

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

Helps determine whether to preserve BC by calling list() on subclasses.

protected synchronized void
dieOnCircularReference(Stack<Object>
the stack of data types to use (recursively).
stk, Project
the project to use to dereference the references.
p)

Overrides org.apache.tools.ant.types.DataType.dieOnCircularReference.

Overrides the version of DataType to recurse on all DataType child elements that may have been added.
private synchronized boolean
getPreserveBC()

private Path
getRef()

public synchronized boolean

Returns:

whether this is a filesystem-only resource collection.
isFilesystemOnly()

Implements org.apache.tools.ant.types.ResourceCollection.isFilesystemOnly.

Fulfill the ResourceCollection contract.
public final synchronized Iterator<Resource>

Returns:

a "fail-fast" Iterator.
iterator()

Implements java.lang.Iterable.iterator.

Fulfill the ResourceCollection contract.
public String[]

Returns:

list of path elements.
list()

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

private static File
resolveFile(Project project, String relativeName)

Resolve a filename with Project's help - if we know one that is.

public void
setCache(boolean
boolean
b)

Whether to cache the current path.

public void
setLocation(File
the location of the element to add (must not be null nor empty.
location)

Adds a element definition to the path.

public void
setPath(String
the String path definition.
path)

Parses a path definition and creates single PathElements.

public void
setRefid(Reference
the reference to another Path
r)

Overrides org.apache.tools.ant.types.DataType.setRefid.

Makes this instance in effect a reference to another Path instance.
public synchronized int

Returns:

number of elements as int.
size()

Implements org.apache.tools.ant.types.ResourceCollection.size.

Fulfill the ResourceCollection contract.
public String

Returns:

a textual representation of the path.
toString()

Overrides org.apache.tools.ant.types.DataType.toString.

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

Returns:

the converted path
translateFile(String
the path to convert
source)

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

protected static boolean

Returns:

true if the character was a / or \
translateFileSep(StringBuffer
a buffer containing a string
buffer, int
the position in the string buffer to convert
pos)

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

public static String[]

Returns:

an array of strings, one for each path element
translatePath(Project
the project to use
project, String
a String value
source)

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

Inherited from org.apache.tools.ant.types.DataType:
checkAttributesAllowedcheckChildrenAllowedcircularReferencedieOnCircularReferencedieOnCircularReferencegetCheckedRefgetCheckedRefgetCheckedRefgetCheckedRefgetCheckedRefgetDataTypeNamegetRefidinvokeCircularReferenceCheckisCheckedisReferencenoChildrenAllowedpushAndInvokeCircularReferenceChecksetCheckedtooManyAttributes

Field Detail

cacheback to summary
private boolean cache
preserveBCback to summary
private Boolean preserveBC
systemBootClasspathback to summary
public static final Path systemBootClasspath

The system bootclasspath as a Path object.

Since
Ant 1.6.2
systemClasspathback to summary
public static Path systemClasspath

The system classpath as a Path object

unionback to summary
private Union union

Constructor Detail

Pathback to summary
public Path(Project p, String path)

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

Parameters
p:Project

the Project for this path.

path:String

the String path definition.

Pathback to summary
public Path(Project project)

Construct an empty Path.

Parameters
project:Project

the Project for this path.

Method Detail

addback to summary
public void add(Path path) throws BuildException

Adds a nested path

Parameters
path:Path

a Path to be added to the path

Exceptions
BuildException:
on error
Since
Ant 1.6
addback to summary
public void add(ResourceCollection c)

Add a nested ResourceCollection.

Parameters
c:ResourceCollection

the ResourceCollection to add.

Since
Ant 1.7
addDirsetback to summary
public void addDirset(DirSet dset) throws BuildException

Adds a nested <dirset> element.

Parameters
dset:DirSet

a DirSet to be added to the path

Exceptions
BuildException:
on error
addExistingback to summary
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:Path

- source path whose components are examined for existence

addExistingback to summary
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:Path

the source path

tryUserDir:boolean

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

addExtdirsback to summary
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

- Path to append files to

addFilelistback to summary
public void addFilelist(FileList fl) throws BuildException

Adds a nested <filelist> element.

Parameters
fl:FileList

a FileList to be added to the path

Exceptions
BuildException:
on error
addFilesetback to summary
public void addFileset(FileSet fs) throws BuildException

Adds a nested <fileset> element.

Parameters
fs:FileSet

a FileSet to be added to the path

Exceptions
BuildException:
on error
addJavaRuntimeback to summary
public void addJavaRuntime()

Add the Java Runtime classes to this Path instance.

appendback to summary
public void append(Path other)

Append the contents of the other Path instance to this.

Parameters
other:Path

a Path to be added to the path

assertFilesystemOnlyback to summary
protected ResourceCollection assertFilesystemOnly(ResourceCollection rc)

Verify the specified ResourceCollection is filesystem-only.

Parameters
rc:ResourceCollection

the ResourceCollection to check.

Returns:ResourceCollection

the passed in ResourceCollection.

Exceptions
BuildException:
if rc is not filesystem-only.
cloneback to summary
public Object clone()

Overrides org.apache.tools.ant.types.DataType.clone.

Clone this Path.

Returns:Object

Path with shallowly cloned Resource children.

Annotations
@Override
concatSpecialPathback to summary
private Path concatSpecialPath(String defValue, Path p)

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

concatSystemBootClasspathback to summary
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:String

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

Returns:Path

the concatenated path

concatSystemClasspathback to summary
public Path concatSystemClasspath()

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

Returns:Path

the concatenated path

concatSystemClasspathback to summary
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:String

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

Returns:Path

the concatenated path

containsWildcardsback to summary
private static boolean containsWildcards(String path)

Does the given file name contain wildcards?

Since
Ant 1.8.2
createPathback to summary
public Path createPath() throws BuildException

Creates a nested <path> element.

Returns:Path

a Path to be configured

Exceptions
BuildException:
on error
createPathElementback to summary
public Path.PathElement createPathElement() throws BuildException

Creates the nested <pathelement> element.

Returns:Path.PathElement

the PathElement to be configured

Exceptions
BuildException:
on error
delegateIteratorToListback to summary
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:boolean

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

dieOnCircularReferenceback to summary
protected synchronized void dieOnCircularReference(Stack<Object> stk, Project p) throws BuildException

Overrides org.apache.tools.ant.types.DataType.dieOnCircularReference.

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

Parameters
stk:Stack<Object>

the stack of data types to use (recursively).

p:Project

the project to use to dereference the references.

Annotations
@Override
Exceptions
BuildException:
on error.
getPreserveBCback to summary
private synchronized boolean getPreserveBC()
getRefback to summary
private Path getRef()
isFilesystemOnlyback to summary
public synchronized boolean isFilesystemOnly()

Implements org.apache.tools.ant.types.ResourceCollection.isFilesystemOnly.

Fulfill the ResourceCollection contract.

Returns:boolean

whether this is a filesystem-only resource collection.

Annotations
@Override
iteratorback to summary
public final synchronized Iterator<Resource> iterator()

Implements java.lang.Iterable.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:Iterator<Resource>

a "fail-fast" Iterator.

Annotations
@Override
listback to summary
public String[] list()

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

Returns:String[]

list of path elements.

resolveFileback to summary
private static File resolveFile(Project project, String relativeName)

Resolve a filename with Project's help - if we know one that is.

setCacheback to summary
public void setCache(boolean b)

Whether to cache the current path.

Parameters
b:boolean

boolean

Since
Ant 1.8.0
setLocationback to summary
public void setLocation(File location) throws BuildException

Adds a element definition to the path.

Parameters
location:File

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

Exceptions
BuildException:
on error
setPathback to summary
public void setPath(String path) throws BuildException

Parses a path definition and creates single PathElements.

Parameters
path:String

the String path definition.

Exceptions
BuildException:
on error
setRefidback to summary
public void setRefid(Reference r) throws BuildException

Overrides org.apache.tools.ant.types.DataType.setRefid.

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:Reference

the reference to another Path

Annotations
@Override
Exceptions
BuildException:
on error
sizeback to summary
public synchronized int size()

Implements org.apache.tools.ant.types.ResourceCollection.size.

Fulfill the ResourceCollection contract.

Returns:int

number of elements as int.

Annotations
@Override
toStringback to summary
public String toString()

Overrides org.apache.tools.ant.types.DataType.toString.

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

Returns:String

a textual representation of the path.

Annotations
@Override
translateFileback to summary
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:String

the path to convert

Returns:String

the converted path

translateFileSepback to summary
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:StringBuffer

a buffer containing a string

pos:int

the position in the string buffer to convert

Returns:boolean

true if the character was a / or \

translatePathback to summary
public static String[] translatePath(Project project, String source)

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

Parameters
project:Project

the project to use

source:String

a String value

Returns:String[]

an array of strings, one for each path element

org.apache.tools.ant.types back to summary

public Class Path.PathElement

extends Object
implements ResourceCollection
Class Inheritance
All Implemented Interfaces
org.apache.tools.ant.types.ResourceCollection, java.lang.Iterable
Helper class, holds the nested <pathelement> values.

Field Summary

Modifier and TypeField and Description
private String[]
parts

Constructor Summary

AccessConstructor and Description
public
PathElement()

Method Summary

Modifier and TypeMethod and Description
public String[]

Returns:

a String[] value
getParts()

Return the converted pathelements.

public boolean

Returns:

true.
isFilesystemOnly()

Implements org.apache.tools.ant.types.ResourceCollection.isFilesystemOnly.

Check if this resource is only for filesystems.
public Iterator<Resource>

Returns:

an iterator.
iterator()

Implements java.lang.Iterable.iterator.

Create an iterator.
public void
setLocation(File
a File value
loc)

Set the location.

public void
setPath(String
a String value
path)

Set the path.

public int

Returns:

the number of parts.
size()

Implements org.apache.tools.ant.types.ResourceCollection.size.

Get the number of resources.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

partsback to summary
private String[] parts

Constructor Detail

PathElementback to summary
public PathElement()

Method Detail

getPartsback to summary
public String[] getParts()

Return the converted pathelements.

Returns:String[]

a String[] value

isFilesystemOnlyback to summary
public boolean isFilesystemOnly()

Implements org.apache.tools.ant.types.ResourceCollection.isFilesystemOnly.

Check if this resource is only for filesystems.

Returns:boolean

true.

Annotations
@Override
iteratorback to summary
public Iterator<Resource> iterator()

Implements java.lang.Iterable.iterator.

Create an iterator.

Returns:Iterator<Resource>

an iterator.

Annotations
@Override
setLocationback to summary
public void setLocation(File loc)

Set the location.

Parameters
loc:File

a File value

setPathback to summary
public void setPath(String path)

Set the path.

Parameters
path:String

a String value

sizeback to summary
public int size()

Implements org.apache.tools.ant.types.ResourceCollection.size.

Get the number of resources.

Returns:int

the number of parts.

Annotations
@Override