Package nl.esciencecenter.xenon.filesystems

Class Path

  • All Implemented Interfaces:
    java.lang.Iterable<Path>
    public class Path
extends java.lang.Object
implements java.lang.Iterable<Path>
    Path contains a sequence of path elements separated by a separator. It is designed to be immutable.
    Since:
    1.0

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static char DEFAULT_SEPARATOR
      The default separator to use.

    • Constructor Summary

      Constructors 
      Constructor Description
      Path()
      Create a new empty Path using the default separator.
      Path​(boolean isAbsolute, java.lang.String... elements)
      Create a new Path using the given path elements and the default separator.
      Path​(boolean isAbsolute, java.util.List<java.lang.String> elements)
      Create a new Path using the given path elements and the default separator.
      Path​(char separator, boolean isAbsolute, java.lang.String... elements)
      Create a new Path using the given path elements and the provided separator.
      Path​(char separator, boolean isAbsolute, java.util.List<java.lang.String> elements)
      Create a new Path using the given path separator, absoluteness, and elements.
      Path​(char separator, java.lang.String path)
      Create a new Path by parsing path using the provided separator.
      Path​(java.lang.String path)
      Create a new Path by parsing path using the default separator.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean endsWith​(java.lang.String other)
      Tests if this Path ends with the given Path represented as a String.
      boolean endsWith​(Path other)
      Tests if this Path ends with the given Path.
      boolean equals​(java.lang.Object obj)  
      Path getFileName()
      Get the file name or null if the Path is empty.
      java.lang.String getFileNameAsString()
      Get the file name as a String, or null if the Path is empty.
      Path getName​(int index)
      Get an element of this Path.
      int getNameCount()
      Get the number of elements in the Path.
      Path getParent()
      Get the parent Path, or null if this Path does not have a parent.
      char getSeparator()
      Get the separator.
      int hashCode()  
      boolean isAbsolute()  
      boolean isEmpty()
      Is this Path empty ?
      java.util.Iterator<Path> iterator()
      Create an Iterator that returns all possible sub Paths of this Path, in order of increasing length.
      Path normalize()
      Normalize this Path by removing as many redundant path elements as possible.
      Path relativize​(Path other)
      Create a relative Path between the given Path and this Path.
      Path resolve​(java.lang.String other)
      Resolve a Path represented as a String against this path.
      Path resolve​(Path other)
      Resolve a Path against this Path.
      Path resolveSibling​(Path other)
      Resolves the given Path to this paths parent Path, thereby creating a sibling to this Path.
      boolean startsWith​(java.lang.String other)
      Tests if this Path starts with the given Path represented as a String.
      boolean startsWith​(Path other)
      Tests if this Path starts with the given Path.
      Path subpath​(int beginIndex, int endIndex)
      Returns a Path that is a subsequence of the name elements of this path.
      Path toAbsolutePath()  
      Path toRelativePath()  
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Field Detail

      • DEFAULT_SEPARATOR

        public static final char DEFAULT_SEPARATOR
        The default separator to use.
        See Also:
        Constant Field Values

    • Constructor Detail

      • Path

        public Path()
        Create a new empty Path using the default separator.

      • Path

        public Path​(java.lang.String path)
        Create a new Path by parsing path using the default separator. If path is null or an empty String, the resulting Path is empty and relative. Otherwise it will be split into multiple elements using the default separator. If path starts with a separator, the resulting path will be absolute. Otherwise, it will be relative.
        Parameters:
        path - the path to parse

      • Path

        public Path​(char separator,
            java.lang.String path)
        Create a new Path by parsing path using the provided separator. If path is null or an empty String, the resulting Path is empty and relative. Otherwise it will be split into multiple elements using the provided separator. If path starts with a separator, the resulting path will be absolute. Otherwise, it will be relative.
        Parameters:
        separator - the separator to use
        path - the path to parse

      • Path

        public Path​(boolean isAbsolute,
            java.lang.String... elements)
        Create a new Path using the given path elements and the default separator. If elements is null or empty, the resulting Path is empty. The elements may not contain null or empty Strings. The elements will not be parsed individually, and may not contain the separator character.
        Parameters:
        isAbsolute - should the resulting path must be absolute?
        elements - the path elements to use.

      • Path

        public Path​(char separator,
            boolean isAbsolute,
            java.lang.String... elements)
        Create a new Path using the given path elements and the provided separator. If elements is null or empty, the resulting Path is empty. The elements may not contain null or empty Strings. The elements will not be parsed individually, and may not contain the separator character.
        Parameters:
        separator - the separator to use.
        isAbsolute - should the resulting path must be absolute?
        elements - the path elements to use.

      • Path

        public Path​(boolean isAbsolute,
            java.util.List<java.lang.String> elements)
        Create a new Path using the given path elements and the default separator. If elements is null or empty, the resulting Path is empty. The elements list may not contain null or empty Strings, or Strings that contain the separator character. If they do, an IllegalArgumentException will be thrown.
        Parameters:
        isAbsolute - should the resulting path must be absolute?
        elements - the path elements to use.

      • Path

        public Path​(char separator,
            boolean isAbsolute,
            java.util.List<java.lang.String> elements)
        Create a new Path using the given path separator, absoluteness, and elements. If elements is null or empty, the resulting Path is empty. The elements list may not contain null or empty Strings, or Strings that contain the separator character. If they do, an IllegalArgumentException will be thrown.
        Parameters:
        separator - the separator to use.
        isAbsolute - should the resulting path should be absolute ?
        elements - the path elements to use.

    • Method Detail

      • getFileName

        public Path getFileName()
        Get the file name or null if the Path is empty. The file name is the last element of the Path.
        Returns:
        the resulting file name or null.

      • getFileNameAsString

        public java.lang.String getFileNameAsString()
        Get the file name as a String, or null if the Path is empty. The file name is the last element of the Path.
        Returns:
        the resulting file name or null.

      • getSeparator

        public char getSeparator()
        Get the separator.
        Returns:
        the separator.

      • getParent

        public Path getParent()
        Get the parent Path, or null if this Path does not have a parent. The parent path will contain all path elements in this pasth except the last one.
        Returns:
        a Path representing this Paths parent.

      • getNameCount

        public int getNameCount()
        Get the number of elements in the Path.
        Returns:
        the number of elements in the Path, or 0 if this path is empty.

      • getName

        public Path getName​(int index)
        Get an element of this Path. Path elements indices start at 0.
        Parameters:
        index - the index of the element
        Returns:
        the element at the specified index
        Throws:
        java.lang.IndexOutOfBoundsException - If the index is negative or greater or equal to the number of elements in the path.

      • subpath

        public Path subpath​(int beginIndex,
                    int endIndex)
        Returns a Path that is a subsequence of the name elements of this path. Path elements indices start at 0.
        Parameters:
        beginIndex - the index of the first element, inclusive
        endIndex - the index of the last element, exclusive
        Returns:
        a new Path that is a subsequence of the name elements in this path.
        Throws:
        java.lang.IllegalArgumentException - If beginIndex is larger than or equal to the endIndex.
        java.lang.ArrayIndexOutOfBoundsException - If beginIndex < 0 or beginIndex > elements.length

      • startsWith

        public boolean startsWith​(Path other)
        Tests if this Path starts with the given Path. This method returns true if this Path starts with the same sequence of the name elements as the given Path. In addition, the absoluteness of this Path should match the absoluteness of the given Path. False is returned if the given Path starts with a different sequence of elements, has more name elements than this path, or has a different absoluteness than this path.
        Parameters:
        other - the Path to compare to.
        Returns:
        If this Path start with the name elements in the other Path and has the same absoluteness.

      • endsWith

        public boolean endsWith​(Path other)
        Tests if this Path ends with the given Path. This method returns true if this Path end with the name elements in the given Path. If the given Path has more name elements than this Path then false is returned.
        Parameters:
        other - the Path to compare to.
        Returns:
        If this Path ends with the name elements in the other Path.

      • startsWith

        public boolean startsWith​(java.lang.String other)
        Tests if this Path starts with the given Path represented as a String. This method converts other into a Path using Path(String) and then uses startsWith(Path) to compare the result to this Path.
        Parameters:
        other - the path to test.
        Returns:
        If this Path start with the name elements in other.

      • endsWith

        public boolean endsWith​(java.lang.String other)
        Tests if this Path ends with the given Path represented as a String. This method converts the other into a Path using Path(String) and then uses endsWith(Path) to compare the result to this path.
        Parameters:
        other - the path to test.
        Returns:
        If this Path ends with the elements in other.

      • resolve

        public Path resolve​(Path other)
        Resolve a Path against this Path. Returns a new Path that concatenates the path elements of this Path with other. The resulting path will use the separator and absoluteness of this path.
        Parameters:
        other - the Path to concatenate with.
        Returns:
        concatenation of this Path with the other

      • resolve

        public Path resolve​(java.lang.String other)
        Resolve a Path represented as a String against this path. Converts other into a Path using Path(char, String) and the separator of the this path. Next, resolve(Path) is used to resolve the result against this path.
        Parameters:
        other - the path to concatenate with.
        Returns:
        concatenation of this Path with the other

      • isEmpty

        public boolean isEmpty()
        Is this Path empty ?
        Returns:
        If this Path is empty.

      • resolveSibling

        public Path resolveSibling​(Path other)
        Resolves the given Path to this paths parent Path, thereby creating a sibling to this Path. If this Path is empty, other will be returned, unless other is null in which case an empty Path is returned. If this Path is not empty, but other is null or empty, the parent of this Path will be returned. If neither this Path and other are empty, getParent.resolve(other) will be returned.
        Parameters:
        other - the Path to resolve as sibling.
        Returns:
        a Path representing the sibling.
        Throws:
        java.lang.IllegalArgumentException - If the Path can not be resolved as a sibling to this Path.

      • relativize

        public Path relativize​(Path other)
        Create a relative Path between the given Path and this Path. Relativation is the inverse of resolving. This method returns a Path that, when resolved against this Path, results in the given Path other.
        Parameters:
        other - the Path to relativize.
        Returns:
        a Path representing a relative path between the given path and this path.
        Throws:
        java.lang.IllegalArgumentException - If the path can not be relativized to this path.

      • iterator

        public java.util.Iterator<Path> iterator()
        Create an Iterator that returns all possible sub Paths of this Path, in order of increasing length. For example, for the Path "/a/b/c/d" the iterator returns "/a", "/a/b", "/a/b/c", "/a/b/c/d".
        Specified by:
        iterator in interface java.lang.Iterable<Path>
        Returns:
        the iterator.

      • normalize

        public Path normalize()
        Normalize this Path by removing as many redundant path elements as possible. Redundant path elements are "." (indicating the current directory) and ".." (indicating the parent directory). Note that the resulting normalized path does may still contain ".." elements which are not redundant.
        Returns:
        the normalize path.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • isAbsolute

        public boolean isAbsolute()

      • toRelativePath

        public Path toRelativePath()

      • toAbsolutePath

        public Path toAbsolutePath()