consciouscode.seedling
Interface BranchNode

All Superinterfaces:

LocatableNode, ServiceNode

All Known Subinterfaces:

BranchingBranch, EventfulBranch, GrowingBranch, RootNode

All Known Implementing Classes:

EmptyBranch, GenericBranch, ScopeManager, ScopeRoot, StandardBranch, StandardRoot

public interface BranchNode
extends LocatableNode, ServiceNode

A branch in the Seedling component hierarchy. The main function of a branch is to provide access to child nodes.

Branches must also implement these interfaces:

LocatableNode

The branch must be able to identify its location in the Seedling.

ServiceNode

The branch must implement ServiceNode.stopService() such that it will recursively stop any child services. This is necessary so that the Seedling can cleanly release scopes.

Method Summary

Object	availableChild(String nodeName) Gets a child node, provisioning and installing it if possible.
Collection<String>	availableChildNames() Extracts a collection of the names of child nodes that are available on request from this branch.
Object	getChild(String nodeName) Deprecated. Use NodeReference.required() instead.
Object	getInstalledNode(String path) Deprecated. Use NodeReference.installed() instead.
RootNode	getLocalRoot() Gets the root node of the local scope.
Log	getLog() Gets the Log associated with this branch.
Object	getNode(String path) Deprecated. Use NodeReference.required() instead.
Object	installedChild(String nodeName) Gets a child node, but doesn't provision it if it's not already installed.
Collection<String>	installedChildNames() Extracts a collection of the names of this branch's current child nodes.

Methods inherited from interface consciouscode.seedling.LocatableNode

getNodeLocation, nodeInstalled

Methods inherited from interface consciouscode.seedling.ServiceNode

startService, stopService

Method Detail

getLocalRoot

RootNode getLocalRoot()

Gets the root node of the local scope. If this branch implements RootNode, this method returns this.

The local root can be located by recursive use of LocatableNode.getNodeLocation().getParentBranch() but implementations should generally cache the root to avoid the search. This is most effectively done in LocatableNode.nodeInstalled(NodeLocation).

Returns:

the local root; not null after LocatableNode.nodeInstalled(NodeLocation) is invoked.

availableChildNames

Collection<String> availableChildNames()

Extracts a collection of the names of child nodes that are available on request from this branch. This set includes all installed children, as well as any other nodes that could be created on demand (usually via automated injection from configuration files).

The result is a snapshot of the current state: subsequent changes to the branch are not reflected in the result. Thus the actual children may have changed by the time the collection is inspected; in particular, another thread may uninstall a node named in this collection (thereby making it unavailable) before the name is even read from this collection.

Implementations must ensure that the result stays usable even when the branch changes in another thread. For example, iterating the result must not throw ConcurrentModificationException if the branch changes during iteration.

Returns:

not null.

installedChildNames

Collection<String> installedChildNames()

Extracts a collection of the names of this branch's current child nodes.

The result is a snapshot of the current state: subsequent changes to the branch are not reflected in the result. Thus the actual children may have changed by the time the collection is inspected; in particular, another thread may uninstall a node named in this collection before the name is even read from this list.

Implementations must ensure that the result stays usable even when the branch changes in another thread. For example, iterating the result must not throw ConcurrentModificationException if the branch changes during iteration.

Returns:

not null.

getNode

@Deprecated
Object getNode(String path)
               throws NodeProvisioningException

Deprecated. Use NodeReference.required() instead.

Gets a node from a path relative to this branch, instantiating and installing it if necessary.

Parameters:

path - is interpreted relative to this branch. It may also be a (local or global) full path. It must not be null or empty.

Returns:

the requested node.

Throws:

NodeProvisioningException - if no such node exists, or if there was an error instantiating it.

getInstalledNode

@Deprecated
Object getInstalledNode(String path)

Deprecated. Use NodeReference.installed() instead.

Looks for a node relative to this branch, without instantiating any new nodes.

Parameters:

path - is interpreted relative to this branch. It may also be a (local or global) full path. It must not be null or empty.

Returns:

the requested node, or null if no node exists at the given path.

getChild

@Deprecated
Object getChild(String nodeName)
                throws NoSuchNodeException,
                       NodeProvisioningException

Deprecated. Use NodeReference.required() instead.

Gets a required child node, provisioning and installing it if necessary.

Provisioning of uninstalled nodes is defined by the implementation class, which may not do any dynamic provisioning at all.

This method will not return null; see availableChild(String) and installedChild(String) for alternatives.

Parameters:

nodeName - must not be null or empty.

Throws:

NoSuchNodeException - if the node isn't installed and if the branch cannot provision it on demand. This usually means that there's no applicable configuration for the node

NodeProvisioningException - if there was an error provisioning the node.

availableChild

Object availableChild(String nodeName)
                      throws NodeProvisioningException

Gets a child node, provisioning and installing it if possible.

A node is available if its already installed, or if it can be provided for installation, usually by being created from configuration. Provisioning of uninstalled nodes is defined by the implementation class, which may not do any dynamic provisioning at all, in which case this method behaves identically to installedChild(String).

If the requested node is not available then null is returned. This is in contrast to getChild(String), which throws NoSuchNodeException in that case.

Parameters:

nodeName - must not be null or empty.

Returns:

the requested node, or null if it's not available.

Throws:

NodeProvisioningException - if there was an error provisioning the node.

installedChild

Object installedChild(String nodeName)

Gets a child node, but doesn't provision it if it's not already installed.

Parameters:

nodeName - must not be null or empty.

Returns:

the child node installed with the requested name, or null if no such child is installed.

getLog

Log getLog()

Gets the Log associated with this branch. Implementations should return a "do-nothing" log instance if no logging is desired; see for example NoOpLog.

Returns:

the log associated with this branch; not null.