consciouscode.seedling
Class NodePath

java.lang.Object
  consciouscode.seedling.NodePath

public final class NodePath
extends Object

An immutable, abstract path identifying components within a Seedling container.

A Seedling path consists of a sequence of parts, each of which represents the name of a component within the container. The sequence denotes a traversal through successive branches in the hierarchy: each part denotes a child of the previous branch.

Paths can be represented in three ways:

• an instance of NodePath
• an array of Strings representing the sequence of parts in the path
• a single String containing the canonical text form of the path

A path is either full or partial depending on whether it starts at a root branch. When represented as an array of strings, a path is full when it has the string "/" as its first element. When represented as a single string, a path is full when it starts with the character '/'.

A special partial path is the identity path which denotes a traversal that "goes nowhere" within the hierarchy: has no parts. The canonical text representation of the identity path is ".". The empty string "" is also parsed into the identity path.

NodePaths are immutable and safe for use by multiple threads.

Field Summary

static NodePath	IDENTITY_PATH A partial path that denotes an identity traversal from some unspecified point in the Seedling container to itself.
static String	IDENTITY_PATH_STRING The canonical representation of the identity path.
static String	ROOT_NAME The name of every root node.
static NodePath	ROOT_PATH A full path to the local root node.
static String	ROOT_PATH_STRING The canonical representation of the root path.

Method Summary

void	appendTo(Appendable out) Appends the canonical text representation of this path to the given output stream.
NodePath	child(String name) Builds a path to a child node, extending this path.
boolean	equals(Object obj)
static NodePath	forParts(String... parts) Builds an object representation of a path from it's constituent parts: a sequence of node names.
static NodePath	forPath(String path) Builds an object representation of a path from it's canonical text form.
static NodePath	fromParts(String... parts) Deprecated. Renamed to forParts(java.lang.String...).
static NodePath	fromPath(String path) Deprecated. Renamed to forPath(String).
String	getNodeName() Gets the name of the node identified by this path.
String[]	getParts() Gets the individual parts of this path.
int	hashCode()
boolean	isFull() Determines whether this path is full.
static boolean	isFull(String... parts) Determines whether a given path is full.
static boolean	isFull(String path) Determines whether a given path is full.
boolean	isIdentity() Determines whether this path is the identity path denoting a go-nowhere traversal.
boolean	isRoot() Determines whether this path is the full path denoting the local root.
NodePath	parts(String... parts) Builds a path to a descendant node, from a sequence of path parts.
NodePath	path(NodePath path) Builds a path extending this one.
NodePath	path(String path) Builds a path to a descendant node, parsing the given path into its parts.
static String[]	toParts(String path) Parses the canonical text representation of a path into its individual parts.
String	toString() Gets the canonical text representation of this path.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ROOT_NAME

public static final String ROOT_NAME

The name of every root node.

See Also:

Constant Field Values

ROOT_PATH_STRING

public static final String ROOT_PATH_STRING

The canonical representation of the root path.

See Also:

Constant Field Values

ROOT_PATH

public static final NodePath ROOT_PATH

A full path to the local root node.

IDENTITY_PATH_STRING

public static final String IDENTITY_PATH_STRING

The canonical representation of the identity path.

See Also:

Constant Field Values

IDENTITY_PATH

public static final NodePath IDENTITY_PATH

A partial path that denotes an identity traversal from some unspecified point in the Seedling container to itself. This path has no parts: IDENTITY_PATH.getParts().length == 0.

See Also:

IDENTITY_PATH_STRING

Method Detail

forParts

public static NodePath forParts(String... parts)

Builds an object representation of a path from it's constituent parts: a sequence of node names.

If the first part is "/" then the result is a full path, otherwise it's a partial path.

Parameters:

parts - the parts of the path. None of the parts may be null or empty.

Returns:

a NodePath that's equivalent to the given path parts; IDENTITY_PATH if the given parts array is null or empty.

forPath

public static NodePath forPath(String path)

Builds an object representation of a path from it's canonical text form.

Parameters:

path - the path to build, represented in the canonical text form.

Returns:

a NodePath that's equivalent to the given path; IDENTITY_PATH if the given path is null, empty, or the IDENTITY_PATH_STRING.

fromPath

@Deprecated
public static NodePath fromPath(String path)

Deprecated. Renamed to forPath(String).

fromParts

@Deprecated
public static NodePath fromParts(String... parts)

Deprecated. Renamed to forParts(java.lang.String...).

isFull

public static boolean isFull(String path)

Determines whether a given path is full.

Parameters:

path - the path to check, represented in the canonical text form.

isFull

public static boolean isFull(String... parts)

Determines whether a given path is full.

Parameters:

parts - the path to check, represented as a sequence of node names.

toParts

public static String[] toParts(String path)

Parses the canonical text representation of a path into its individual parts.

Parameters:

path - the path to parse, represented in the canonical text form.

Returns:

the string-array representation of the path; an empty array if the given path is null, empty, or the IDENTITY_PATH_STRING.

isFull

public boolean isFull()

Determines whether this path is full.

isIdentity

public final boolean isIdentity()

Determines whether this path is the identity path denoting a go-nowhere traversal.

See Also:

IDENTITY_PATH

isRoot

public final boolean isRoot()

Determines whether this path is the full path denoting the local root.

See Also:

ROOT_PATH

getParts

public String[] getParts()

Gets the individual parts of this path.

Returns:

the parts of this path, empty if this is the identity path, never null.

getNodeName

public String getNodeName()

Gets the name of the node identified by this path.

Returns:

the last path part, or null if this is the identity path.

child

public NodePath child(String name)

Builds a path to a child node, extending this path.

Parameters:

name - the name of the child node.

Returns:

the extended path; or this path if the name is null or empty.

path

public NodePath path(NodePath path)

Builds a path extending this one.

Parameters:

path - the extension.

Returns:

the extended path; this path if the parameter is null or the identity path.

path

public NodePath path(String path)

Builds a path to a descendant node, parsing the given path into its parts.

Parameters:

path - the canonical text form to be append to this path.

Returns:

the extended path; this path if the parameter is null or empty.

parts

public NodePath parts(String... parts)

Builds a path to a descendant node, from a sequence of path parts.

Parameters:

parts - the parts of the path to be appended to this path. None of the parts may be null or empty.

Returns:

the extended path; this path if the parameter is null or empty.

appendTo

public void appendTo(Appendable out)
              throws IOException

Appends the canonical text representation of this path to the given output stream.

Parameters:

out - the output stream; not null.

Throws:

IOException - if thrown by the output stream.

toString

public String toString()

Gets the canonical text representation of this path.

Overrides:

toString in class Object

Returns:

not null or empty.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object