com.partnersoft.data
Class Path

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

All Implemented Interfaces:

java.lang.Iterable<java.lang.String>

public class Path
extends java.lang.Object
implements java.lang.Iterable<java.lang.String>

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.

Version:

$Id: Path.java 2046 2009-08-25 05:28:53Z paul $

Author:

Paul Reavis

Constructor Summary

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

Path	childNamed(java.lang.String childName) Creates a new instance of Path representing the named "child" of this path.
int	compareTo(Path nother)
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()
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()
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)

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)

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