Path

java.lang.Object
- com.partnersoft.data.Path

All Implemented Interfaces:

java.lang.Comparable<Path>, java.lang.Iterable<java.lang.String>
```
public class Path
extends java.lang.Object
implements java.lang.Iterable<java.lang.String>, java.lang.Comparable<Path>
```
A general solution to the problem of dealing with representing a path to a node in a hierarchy. Generally you need a string representation, which of course causes encoding issues (embedded separators etc.). You also generally want to move up and down the hierarchy by pushing and popping subpaths.
This solution matches the way URLs represents paths. The string representation uses forward slashes (/) to separate subpaths. The root is represented as a single slash (/). Other paths look like /path/to/something.
Embedded slashes and other characters that are illegal in URLs are encoded the same way they are in URLs, using the recommended UTF-8 encoding. This may make the string representations look a little strange, since even spaces will be encoded.
Since one of the most common use for paths is to represent the locations of files, there are also methods to translate between Paths and the OS-specific String representation of a file path. Generally where you see the term "path string" that means the URL-encoded style, while "file string" means a file-encoded style.
See the the Wikipedia entry for Path for a description of the path concept.
Copyright 2005-2006 Partner Software, Inc.

Author:

Paul Reavis

Constructor Summary

Constructors
Constructor and Description
`Path()` Constructs a path representing the current relative node ("./").
`Path(boolean absolute, java.util.List<java.lang.String> parts)` Create a relative path from the given parts.
`Path(java.util.List<java.lang.String> parts)` Create a relative path from the given parts.
`Path(PathBuilder builder)` Create a Path from a PathBuilder.
`Path(Path start, Path subpath)` Creates a path derived from the given root and relative subpath.
`Path(Path start, java.lang.String part)` Creates a path derived from the given root and part.
`Path(java.lang.String... parts)` Create a relative path from the given parts.
`Path(java.lang.String pathString)` Constructs a Path based on the String path representation (URL-encoded).

Method Summary

Methods
Modifier and Type	Method and Description
`Path`	`childNamed(java.lang.String childName)` Creates a new instance of Path representing the named "child" of this path.
`int`	`compareTo(Path nother)`
`boolean`	`contains(java.lang.String sub)` Returns true if and only if this Path contains the specified string
`Path`	`descendentFor(Path sub)` Creates a new instance of Path representing the named "descendent" of this path.
`Path`	`descendentFor(java.lang.String pathString)` Creates a new instance of Path representing the named "descendent" of this path.
`boolean`	`equals(java.lang.Object nother)`
`Path`	`findAncestorNamed(java.lang.String name)` Returns the closest ancestor of this Path with the given case-insensitive name.
`static Path`	`forFile(java.io.File file)` Creates a Path object from the given File.
`static Path`	`forFileString(java.lang.String filePath)` Creates a Path object from the given path, expressed in file notation (e.g.
`static Path`	`forPathString(java.lang.String pathString)` Creates a Path object based on a URL-encoded (similar to Unix, with forward slashes) String.
`static Path`	`forUrl(java.net.URL url)` Creates a Path object based on the given URL.
`java.lang.String`	`getBaseName()` Gets just the base name of the file name (last part without the extension).
`java.lang.String`	`getExtension()` Returns the file extension, generally the part including and after the LAST period (.).
`java.lang.String`	`getFirstPart()` Returns the first path part.
`java.lang.String`	`getHead()` This is a class list operator.
`java.lang.String`	`getLastPart()` Returns the last path part.
`int`	`getLength()`
`java.lang.String`	`getName()` Gets the last part as a single string representing the full file name (including extension, if any).
`Path`	`getParent()` Creates a new instance of Path representing the "parent" of this path.
`java.lang.String`	`getPart(int index)`
`Path`	`getTail()` This is a class list operator.
`int`	`hashCode()`
`int`	`indexOf(java.lang.String sub)` Returns the index of the part of the path matching the argument sub, if no match returns -1
`int`	`indexOf(java.lang.String sub, int fromIndex)` Returns the index of the part of the path matching the argument sub, beginning at the index specified by the arg fromIndex if no match returns -1
`boolean`	`isAbsolute()` Returns true if this is an absolute path.
`boolean`	`isAncestorOf(Path nother)` Returns true if this path is an ancestor of the one given.
`boolean`	`isDescendentOf(Path nother)` Returns true if this path is a descendent of the one given.
`java.util.Iterator<java.lang.String>`	`iterator()`
`int`	`lastIndexOf(java.lang.String sub)` Returns the index of the last occurring part of the path matching the argument sub if no match returns -1
`java.util.List<java.lang.String>`	`listParts()` Returns the parts as a list.
`Path`	`relativeTo(Path ancestor)` Returns a path relative to the one given.
`int`	`size()`
`Path`	`subpath(int first)` This is intended to work like String.substring().
`Path`	`subpath(int first, int last)` This is intended to work like String.substring().
`java.lang.String[]`	`toArray()` Returns an array of Strings representing the parts of the path.
`java.lang.String`	`toFileString()` Gets the path as a single, file-encoded String.
`java.lang.String`	`toPathString()` Gets the path as a single, URL-encoded String.
`java.lang.String`	`toString()`
`Path`	`withAbsolute(boolean isit)`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Path
```
public Path()
```
    Constructs a path representing the current relative node ("./").
  - Path
```
public Path(java.lang.String pathString)
```
    Constructs a Path based on the String path representation (URL-encoded).
    
    Parameters:
    pathString - String representation, "/" delimited, of the path.
  - Path
```
public Path(Path start,
    Path subpath)
```
    Creates a path derived from the given root and relative subpath.
    
    Parameters:
    start - a path representing the starting node
    subpath - relative path to the starting node
  - Path
```
public Path(Path start,
    java.lang.String part)
```
    Creates a path derived from the given root and part.
    
    Parameters:
    start - a path representing the starting node
    part - next part in the path
  - Path
```
public Path(PathBuilder builder)
```
    Create a Path from a PathBuilder.
    
    Parameters:
    builder - builder that built the path
  - Path
```
public Path(java.lang.String... parts)
```
    Create a relative path from the given parts.
  - Path
```
public Path(boolean absolute,
    java.util.List<java.lang.String> parts)
```
    Create a relative path from the given parts.
  - Path
```
public Path(java.util.List<java.lang.String> parts)
```
    Create a relative path from the given parts.
- Method Detail
  - forFileString
```
public static Path forFileString(java.lang.String filePath)
```
    Creates a Path object from the given path, expressed in file notation (e.g. backslash '\' on Windows).
  - forFile
```
public static Path forFile(java.io.File file)
```
    Creates a Path object from the given File.
  - forPathString
```
public static Path forPathString(java.lang.String pathString)
```
    Creates a Path object based on a URL-encoded (similar to Unix, with forward slashes) String.
  - forUrl
```
public static Path forUrl(java.net.URL url)
```
    Creates a Path object based on the given URL.
  - getParent
```
public Path getParent()
```
    Creates a new instance of Path representing the "parent" of this path. For file paths, this means the directory containing the file or directory represented by this path.
  - childNamed
```
public Path childNamed(java.lang.String childName)
```
    Creates a new instance of Path representing the named "child" of this path. For file paths, this treats the current path as a directory and returns a path representing a file or subdirectory in that directory. The argument must be a single name; it will not split it up based on slashes. Use createSubPath(Path) if you want to create an arbitrarily deep descendent.
  - descendentFor
```
public Path descendentFor(Path sub)
```
    Creates a new instance of Path representing the named "descendent" of this path. For file paths, this treats the current path as a directory and returns a path representing a file or subdirectory beneath that directory.
  - descendentFor
```
public Path descendentFor(java.lang.String pathString)
```
    Creates a new instance of Path representing the named "descendent" of this path. For file paths, this treats the current path as a directory and returns a path representing a file or subdirectory beneath that directory. The String given is turned into a Path via forPathString().
  - relativeTo
```
public Path relativeTo(Path ancestor)
```
    Returns a path relative to the one given. Given path must be an ancestor.
  - isAbsolute
```
public boolean isAbsolute()
```
    Returns true if this is an absolute path.
    
    Returns:
    true if this path is absolute (not relative).
  - isDescendentOf
```
public boolean isDescendentOf(Path nother)
```
    Returns true if this path is a descendent of the one given.
  - isAncestorOf
```
public boolean isAncestorOf(Path nother)
```
    Returns true if this path is an ancestor of the one given.
  - toPathString
```
public java.lang.String toPathString()
```
    Gets the path as a single, URL-encoded String.
  - toFileString
```
public java.lang.String toFileString()
```
    Gets the path as a single, file-encoded String.
  - getName
```
public java.lang.String getName()
```
    Gets the last part as a single string representing the full file name (including extension, if any).
  - getBaseName
```
public java.lang.String getBaseName()
```
    Gets just the base name of the file name (last part without the extension).
  - getExtension
```
public java.lang.String getExtension()
```
    Returns the file extension, generally the part including and after the LAST period (.). E.g. if the file is "file.txt", then this will return ".txt". EXCEPT certain standard compressed formats have a double extension - if the file is "archive.tar.gz" this will return ".tar.gz". Returns an empty string if there is none.
  - getLastPart
```
public java.lang.String getLastPart()
```
    Returns the last path part. This is often a filename or property name.
  - getFirstPart
```
public java.lang.String getFirstPart()
```
    Returns the first path part. This is often a root directory name.
  - getLength
```
public int getLength()
```
  - getPart
```
public java.lang.String getPart(int index)
```
  - indexOf
```
public int indexOf(java.lang.String sub)
```
    Returns the index of the part of the path matching the argument sub, if no match returns -1
    
    Parameters:
    sub -
    
    Returns:
  - indexOf
```
public int indexOf(java.lang.String sub,
          int fromIndex)
```
    Returns the index of the part of the path matching the argument sub, beginning at the index specified by the arg fromIndex if no match returns -1
    
    Parameters:
    sub -
    
    Returns:
  - lastIndexOf
```
public int lastIndexOf(java.lang.String sub)
```
    Returns the index of the last occurring part of the path matching the argument sub if no match returns -1
    
    Parameters:
    sub -
    
    Returns:
  - contains
```
public boolean contains(java.lang.String sub)
```
    Returns true if and only if this Path contains the specified string
    
    Parameters:
    sub -
    
    Returns:
  - subpath
```
public Path subpath(int first,
           int last)
```
    This is intended to work like String.substring(). It copies everything starting from the path element at first, up to but not including the path element at last.
    
    Parameters:
    first - the index of the first path element to copy.
    last - the index after the last element to copy.
    
    Returns:
  - subpath
```
public Path subpath(int first)
```
    This is intended to work like String.substring(). It copies everything starting from the path element at first up to the end of the path.
    
    Parameters:
    first - the index of the first path element to copy.
    
    Returns:
  - getHead
```
public java.lang.String getHead()
```
    This is a class list operator. Returns the first element.
  - getTail
```
public Path getTail()
```
    This is a class list operator. Returns everything other than the first element.
  - toArray
```
public java.lang.String[] toArray()
```
    Returns an array of Strings representing the parts of the path.
  - listParts
```
public java.util.List<java.lang.String> listParts()
```
    Returns the parts as a list.
  - size
```
public int size()
```
  - withAbsolute
```
public Path withAbsolute(boolean isit)
```
  - iterator
```
public java.util.Iterator<java.lang.String> iterator()
```
    Specified by:
    
    iterator in interface java.lang.Iterable<java.lang.String>
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - compareTo
```
public int compareTo(Path nother)
```
    Specified by:
    
    compareTo in interface java.lang.Comparable<Path>
  - equals
```
public boolean equals(java.lang.Object nother)
```
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - findAncestorNamed
```
public Path findAncestorNamed(java.lang.String name)
```
    Returns the closest ancestor of this Path with the given case-insensitive name. Return null if none matching is found.
    
    Parameters:
    name - case-insensitive ancestor name
    
    Returns:
    ancestor with the given name, or null

Class Path

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Path

Path

Path

Path

Path

Path

Path

Path

Method Detail

forFileString

forFile

forPathString

forUrl

getParent

childNamed

descendentFor

descendentFor

relativeTo

isAbsolute

isDescendentOf

isAncestorOf

toPathString

toFileString

getName

getBaseName

getExtension

getLastPart

getFirstPart

getLength

getPart

indexOf

indexOf

lastIndexOf

contains

subpath

subpath

getHead

getTail

toArray

listParts

size

withAbsolute

iterator

toString

compareTo

equals

hashCode

findAncestorNamed