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.

See the the Wikipedia entry for Path for a description of the path concept.

Copyright 2005-2006 Partner Software, Inc.

Version:

$Id: Path.java,v 1.4.2.1 2006-07-21 20:54:47 russell Exp $

Author:

Paul Reavis

Constructor Summary

Path()
Constructs a path representing the current relative node ("./").

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 pathString)
Constructs a Path based on the String path representation.

Method Summary

Path	createParentPath() Creates a new instance of Path representing the "parent" of this path.
static java.lang.String	decode(java.lang.String string) Decodes a String representing the name of a node in the path.
static java.lang.String	encode(java.lang.String string) Encodes a String representing the name of a node in the path, so that e.g.
static java.lang.String	encodeAndJoin(java.lang.String[] parts) Encodes each part to deal with embedded slashes and other problems, then joins them together into a single slash-separated String.
java.lang.String	getFileString() Gets the path as a single, file-encoded String.
java.lang.String	getLastPart() Returns the last path part.
int	getLength()
java.lang.String	getPart(int index)
java.lang.String	getPathString() Gets the path as a single, URL-encoded String.
boolean	isAbsolute() Returns true if this is an absolute path.
java.util.Iterator	iterator()
static java.lang.String[]	splitAndDecode(java.lang.String pathString) Splits the given Path String, decodes each part and returns it as a String array.
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	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, 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.

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

Method Detail

encode

public static java.lang.String encode(java.lang.String string)

Encodes a String representing the name of a node in the path, so that e.g. embedded slashes don't confuse the path string parser. Uses URLEncoder.

Parameters:

string - input name

Returns:

encoded name

decode

public static java.lang.String decode(java.lang.String string)

Decodes a String representing the name of a node in the path. Uses URLDecoder.

Parameters:

string - input name

Returns:

decoded name

splitAndDecode

public static java.lang.String[] splitAndDecode(java.lang.String pathString)

Splits the given Path String, decodes each part and returns it as a String array. Eliminates any empty parts, but otherwise makes no judgements about validity or canonicalization.

Parameters:

pathString - Path represented and encoded as a String.

Returns:

array of String node names

encodeAndJoin

public static java.lang.String encodeAndJoin(java.lang.String[] parts)

Encodes each part to deal with embedded slashes and other problems, then joins them together into a single slash-separated String. Does not put an initial slash (indicating absoluteness); you have to do that yourself it it's appropriate.

Parameters:

parts - parts to join

Returns:

encoded path string

createParentPath

public Path createParentPath()

Creates a new instance of Path representing the "parent" of this path.

isAbsolute

public boolean isAbsolute()

Returns true if this is an absolute path.

Returns:

true if this path is absolute (not relative).

getPathString

public java.lang.String getPathString()

Gets the path as a single, URL-encoded String.

getFileString

public java.lang.String getFileString()

Gets the path as a single, file-encoded String.

getLastPart

public java.lang.String getLastPart()

Returns the last path part. This is often a filename or property 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:

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

iterator

public java.util.Iterator iterator()

Specified by:

iterator in interface java.lang.Iterable<java.lang.String>