Path (Apache Ant API)
Date: 2018-07-10

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, java.lang.Iterable<Resource>, 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 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 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

    All Methods Static Methods Instance Methods Concrete 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<java.lang.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.
    `java.util.Iterator<Resource>` | `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`

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

      `isEmpty, stream`

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

      `forEach, spliterator`

- - ### Field Detail

    - #### 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 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.
      Parameters:
        `b` - boolean
      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<java.lang.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(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<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 `java.lang.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()`.