consciouscode.seedling
Class NodeReference

java.lang.Object
  consciouscode.seedling.NodeReference

Direct Known Subclasses:

NodeLocation

public class NodeReference
extends Object

Identifies a Seedling node by a path relative to a base branch. This class also provides utility methods for finding nodes in a Seedling container.

Put simply, a NodeReference points from one place in the tree to another. It's essentially an installed branch ("one place") and a NodePath interpreted relative to that branch ("to another").

Unlike a NodePath, a NodeReference always denotes a full path anchored at a root branch. That's true because the base branch of the reference must have a full path itself.

NodeReferences are immutable and safe for use by multiple threads.

Method Summary

<T> T	available() Gets the referenced node, provisioning and installing it if possible.
NodeReference	child(String name) Builds a reference to a child of this reference.
boolean	equals(Object object)
static NodeReference	forBranch(BranchNode branch) Builds a reference to a given branch and the identity path.
static NodeLocation	forChild(BranchNode branch, String name) Builds a reference to the child of a branch.
static NodeReference	forParts(BranchNode branch, String... pathParts) Builds a reference to a node from a base branch and a sequence of path parts.
static NodeReference	forPath(BranchNode branch, NodePath path) Builds a reference to a node from a base branch and a path relative to it.
static NodeReference	forPath(BranchNode branch, String path) Builds a node reference, parsing a given canonical path string into its '/'-separated parts.
static NodeReference	from(BranchNode branch) Deprecated. Renamed to forBranch(BranchNode).
static NodeLocation	fromChild(BranchNode branch, String name) Deprecated. Renamed to forChild(BranchNode, String).
static NodeReference	fromParts(BranchNode branch, String... pathParts) Deprecated. Renamed to forParts(BranchNode, String...).
static NodeReference	fromPath(BranchNode branch, NodePath path) Deprecated. Renamed to forPath(BranchNode, NodePath).
static NodeReference	fromPath(BranchNode branch, String path) Deprecated. Renamed to forPath(BranchNode, String).
BranchNode	getBaseBranch() Returns the branch from which this reference starts its traversal.
Object	getInstalledNode() Deprecated. Use installed() instead.
String	getLocalPath() Deprecated. Use toLocalPath() instead.
RootNode	getLocalRoot()
Object	getNode() Deprecated. Use required() instead.
String	getNodeName() Returns the name of the identified node.
NodePath	getNodePath() Gets the path part of this reference, to be interpreted relative to the base branch.
String	getPath() Deprecated. Use getNodePath() instead.
<T> T	installed() Gets the referenced node, without provisioning it if it's not already installed.
boolean	isRoot() Determines whether this is a reference to a RootNode.
NodeReference	parent() Returns a reference to the parent branch of this reference.
NodeReference	parts(String... parts) Builds a reference to a descendant node from a sequence of parts.
NodeReference	path(NodePath path) Builds a reference to a descendant node, extending this with the given path.
NodeReference	path(String path) Builds a reference to a descendant node, parsing the given path into its parts.
<T> T	required() Gets the referenced node, provisioning and installing it if necessary.
NodePath	toLocalPath() Returns this node reference as a full local path, valid within the scope of the parent branch.
String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

forBranch

public static NodeReference forBranch(BranchNode branch)

Builds a reference to a given branch and the identity path.

from

@Deprecated
public static NodeReference from(BranchNode branch)

Deprecated. Renamed to forBranch(BranchNode).

forChild

public static NodeLocation forChild(BranchNode branch,
                                    String name)

Builds a reference to the child of a branch.

Parameters:

branch - must not be null.

name - must be a simple name, not a path. It must not contain any slash ('/') characters. It must not be null or empty.

fromChild

@Deprecated
public static NodeLocation fromChild(BranchNode branch,
                                                String name)

Deprecated. Renamed to forChild(BranchNode, String).

forParts

public static NodeReference forParts(BranchNode branch,
                                     String... pathParts)

Builds a reference to a node from a base branch and a sequence of path parts.

If the first part is "/" then the resulting reference is equivalent to one from the root of the given branch.

Parameters:

branch - must not be null.

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

See Also:

NodePath.forParts(String...)

fromParts

@Deprecated
public static NodeReference fromParts(BranchNode branch,
                                                 String... pathParts)

Deprecated. Renamed to forParts(BranchNode, String...).

forPath

public static NodeReference forPath(BranchNode branch,
                                    String path)

Builds a node reference, parsing a given canonical path string into its '/'-separated parts.

Parameters:

branch - is the base for traversing the path. It must not be null.

path - is interpreted relative to the branch. It may also be a full path.

See Also:

NodePath.forPath(String)

fromPath

@Deprecated
public static NodeReference fromPath(BranchNode branch,
                                                String path)

Deprecated. Renamed to forPath(BranchNode, String).

forPath

public static NodeReference forPath(BranchNode branch,
                                    NodePath path)

Builds a reference to a node from a base branch and a path relative to it.

If the path isFull() then the resulting reference is equivalent to one from the root of the given branch.

Parameters:

branch - must not be null.

path - the path relative to the branch.

fromPath

@Deprecated
public static NodeReference fromPath(BranchNode branch,
                                                NodePath path)

Deprecated. Renamed to forPath(BranchNode, NodePath).

getLocalPath

@Deprecated
public String getLocalPath()

Deprecated. Use toLocalPath() instead.

Returns this node reference as a local path, valid within the scope of the parent branch.

Returns:

the referenced path, starting with "/".

child

public final NodeReference child(String name)

Builds a reference to a child of this reference. In other words, extend this reference.

Parameters:

name - the name of the child node.

Returns:

a reference with the same base branch and a modified path.

parent

public NodeReference parent()

Returns a reference to the parent branch of this reference. If this object refers to a root branch, then the result is null.

Returns:

a reference to the parent.

parts

public final NodeReference parts(String... parts)

Builds a reference to a descendant node from a sequence of parts.

Parameters:

parts -

Returns:

a reference with the same base branch and a modified path.

path

public final NodeReference path(NodePath path)

Builds a reference to a descendant node, extending this with the given path.

Parameters:

path - the extension.

Returns:

a reference with the same base branch and a modified path.

path

public final NodeReference path(String path)

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

Parameters:

path -

Returns:

a reference with the same base branch and a modified path.

getBaseBranch

public final BranchNode getBaseBranch()

Returns the branch from which this reference starts its traversal. This is the branch provided when the reference was constructed.

Returns:

the base branch of this reference; not null.

getNodePath

public final NodePath getNodePath()

Gets the path part of this reference, to be interpreted relative to the base branch.

Returns:

a non-null path; if the the path NodePath.isIdentity(), then the target of this reference is its base branch.

See Also:

getBaseBranch()

getPath

@Deprecated
public final String getPath()

Deprecated. Use getNodePath() instead.

Gets the path part of this reference.

Returns:

a non-null string; if empty, the target of this reference is its base branch.

See Also:

getBaseBranch()

toLocalPath

public NodePath toLocalPath()

Returns this node reference as a full local path, valid within the scope of the parent branch.

Returns:

a full NodePath, not null.

getNodeName

public String getNodeName()

Returns the name of the identified node. This is not necessarily the same as the last path part, since the path may be empty.

Returns:

the node name, not null or empty.

getLocalRoot

public RootNode getLocalRoot()

isRoot

public boolean isRoot()

Determines whether this is a reference to a RootNode.

getNode

@Deprecated
public final Object getNode()
                     throws NodeProvisioningException,
                            NoSuchNodeException

Deprecated. Use required() instead.

Gets the referenced node, instantiating and installing it if necessary. No caching is done, since the node may be uninstalled or replaced between calls.

Returns:

the node identified by this reference.

Throws:

NodeProvisioningException - if there was an error provisioning the node.

NoSuchNodeException - if the requested node doesn't exist and has no configuration, or if the path traverses an intermediate node that's not a BranchNode.

See Also:

BranchNode.getChild(String)

available

public final <T> T available()
                  throws NodeProvisioningException

Gets the referenced node, provisioning and installing it if possible. No caching is done here, since the node may be uninstalled or replaced between calls.

This method will return null if any node in the path is not installed and cannot be provisioned.

Returns:

the node identified by this reference; or null if it's not available. This includes the case where the path includes an intermediate node that is not a branch.

Throws:

NodeProvisioningException - if there was an error provisioning the node.

See Also:

required(), installed(), BranchNode.availableChild(String)

getInstalledNode

@Deprecated
public final Object getInstalledNode()

Deprecated. Use installed() instead.

Gets the referenced node, but doesn't instantiate it if it's not already installed. No caching is done, since the node may be uninstalled or replaced between calls.

Returns:

the referenced node (already installed), or null if no such node exists. This includes the case where the path includes an intermediate node that is not a branch.

See Also:

BranchNode.installedChild(String)

installed

public final <T> T installed()

Gets the referenced node, without provisioning it if it's not already installed. No caching is done here, since the node may be uninstalled or replaced between calls.

Returns:

the referenced node (already installed), or null if no such node exists. This includes the case where the path includes an intermediate node that is not a branch.

See Also:

available(), required(), BranchNode.installedChild(String)

required

public final <T> T required()
                 throws NodeProvisioningException,
                        NoSuchNodeException

Gets the referenced node, provisioning and installing it if necessary. No caching is done here, since the node may be uninstalled or replaced between calls.

This method will not return null; see available() and installed() for alternatives.

Returns:

the node identified by this reference; not null.

Throws:

NoSuchNodeException - if the node isn't installed and its parent branch cannot provision it on demand. This usually means that there's no applicable configuration for the node. Also thrown if the path traverses an intermediate node that's not a BranchNode.

NodeProvisioningException - if there was an error provisioning the node.

See Also:

available(), installed()

equals

public final boolean equals(Object object)

Two NodeReferences are considered equal if they have the same global path.

Overrides:

equals in class Object

toString

public final String toString()

Overrides:

toString in class Object