Path (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.types, class: Path

Package 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:
  `Cloneable`, `Iterable<Resource>`, `ResourceCollection`

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 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 Class Summary

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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final 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
  Description
  `Path(Project project)`
  Construct an empty `Path`.
  `Path(Project p, String path)`
  Invoked by IntrospectionHelper for `setXXX(Path p)` attribute setters.

- ## Method Summary

  Modifier and Type
  Method
  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.
  `Object`
  `clone()`
  Clone this Path.
  `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.
  `Path`
  `concatSystemClasspath()`
  Concatenates the system class path in the order specified by the ${build.sysclasspath} property - using "last" as default value.
  `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.
  `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(Stack<Object> 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.
  `final Iterator<Resource>`
  `iterator()`
  Fulfill the ResourceCollection contract.
  `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(File location)`
  Adds a element definition to the path.
  `void`
  `setPath(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.
  `String`
  `toString()`
  Returns a textual representation of the path, which can be used as CLASSPATH or PATH environment variable definition.
  `static String`
  `translateFile(String source)`
  Returns its argument with all file separator characters replaced so that they match the local OS conventions.
  `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.
  `static String[]`
  `translatePath(Project project, 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, 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`

  ### Methods inherited from interface java.lang.Iterable

  `forEach, spliterator`

  ### Methods inherited from interface org.apache.tools.ant.types.ResourceCollection

  `isEmpty, stream`

- ## Field Details

  - ### systemClasspath

    public static Path systemClasspath
    The system classpath as a Path object

  - ### systemBootClasspath

    public static final Path systemBootClasspath
    The system bootclasspath as a Path object.
    Since:
      Ant 1.6.2

- ## Constructor Details

  - ### 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 Details

  - ### setLocation

    public void setLocation(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(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.
    Parameters:
      `b` - boolean
    Since:
      Ant 1.8.0

  - ### list

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

  - ### toString

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

  - ### 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 \

  - ### size

    public int size()
    Fulfill the ResourceCollection contract.
    Specified by:
      `size` in interface `ResourceCollection`
    Returns:
      number of elements as int.

  - ### clone

    public Object clone()
    Clone this Path.
    Overrides:
      `clone` in class `DataType`
    Returns:
      Path with shallowly cloned Resource children.

  - ### dieOnCircularReference

    protected void dieOnCircularReference(Stack<Object> 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(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(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 Iterator<Resource> 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 `Iterable<Resource>`
    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()`.