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

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