co.paralleluniverse.galaxy.cluster

Interface DistributedTree

All Known Implementing Classes:

DistributedTreeAdapter

public interface DistributedTree

Provides access to a distributed, observable filesystem-like node tree for configuration data.

Nodes in the tree are organized in a directory structure: each tree-node (not to be confused with cluster nodes, or machines) may have sub-nodes (children) as well as byte data associated with it (the node's contents). The nodes are named in the following manner: the root of the tree is called "/", and generations are separated by the '/' (forward-slash) character. A node may have the simple name "mynode" and its full path may be "/grandparent/parent/mynode". All full paths must begin with a "/".
The tree is available to all nodes (machines) in the cluster, and any change is immediately visible to all of them. The tree provides an important ordering guarantee: All children (of a certain node) appear (throughout the cluster) in the order in which they've been created.

The tree also provides ephemeral nodes: those are automatically deleted when the creating cluster-node (machine) goes offline, i.e. disconnected from the cluster for whatever reason - intentional or due to some fault.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	DistributedTree.Listener A listener for DistributedTree node events.
static class	DistributedTree.ListenerAdapter An abstract adapter class for receiving DistributedTree events.

Method Summary

Methods

Modifier and Type	Method and Description
void	addListener(String node, DistributedTree.Listener listener) Adds a listener listening for modifications on the given node.
void	create(String node, boolean ephemeral) Creates a new node in the tree.
void	createEphemeralOrdered(String node) Creates an ephemeral node that, when returned by getChildren(), will be placed in the list in relation to other ordered ephemeral nodes by the relative order of its creation.
void	delete(String node) Deletes a node and all its descendents from the tree.
boolean	exists(String node) Returns true if the given node exists in the tree.
void	flush() Ensures that all updates to the tree done by this cluster node will have been seen by all nodes in the cluster when this method returns.
byte[]	get(String node) Returns the contents of a given node.
List<String>	getChildren(String node) Returns all child-nodes (direct descendents) of a given node, with ephemeral ordered nodes returned in the order they were created.
void	print(String node, PrintStream out) Prints the tree's structure, starting at a given node, to the given stream.
void	removeListener(String node, DistributedTree.Listener listener) Removes a listener.
void	set(String node, byte[] data) Associates data with (sets the contents of) a given node.

Method Detail

create

void create(String node,
          boolean ephemeral)

Creates a new node in the tree. All nonexistent parent nodes are also created (i.e. all nonexistent nodes along the path).

The node can be ephemeral in which case, it and all its descendents will be deleted automatically when the creating cluster-node (this machine) goes offline, i.e. disconnected from the cluster for whatever reason - intentional or due to some fault. Non-ephemeral (permanent) nodes persist in the tree until the entire cluster is taken down.
If the node is marked as ephemeral, all nonexistent ancestors that will be created in the process will be ephemeral as well.

Parameters:

node - The full path of the node to create.

ephemeral - true if the node is to be ephemeral; false if it's to be permanent.

createEphemeralOrdered

void createEphemeralOrdered(String node)

Creates an ephemeral node that, when returned by getChildren(), will be placed in the list in relation to other ordered ephemeral nodes by the relative order of its creation. The node's ancestors are not created.

Parameters:

node - The full path of the node to create.

getChildren

List<String> getChildren(String node)

Returns all child-nodes (direct descendents) of a given node, with ephemeral ordered nodes returned in the order they were created.

Parameters:

node - The full path of the node.

Returns:

A list of the simple names (without the full path) of all of the given node's children.

exists

boolean exists(String node)

Returns true if the given node exists in the tree.

Parameters:

node - The full path of the node to test.

Returns:

true if the given node exists in the tree; false otherwise.

set

void set(String node,
       byte[] data)

Associates data with (sets the contents of) a given node.

Parameters:

node - The full path name of the node.

data - The data to be associated with the node.

See Also:

get(java.lang.String)

get

byte[] get(String node)

Returns the contents of a given node.

Parameters:

node - The full path of the node.

Returns:

The given node's data contents.

See Also:

set(java.lang.String, byte[])

delete

void delete(String node)

Deletes a node and all its descendents from the tree.

Parameters:

node - The full path of the node to be removed.

flush

void flush()

Ensures that all updates to the tree done by this cluster node will have been seen by all nodes in the cluster when this method returns.

addListener

void addListener(String node,
               DistributedTree.Listener listener)

Adds a listener listening for modifications on the given node. As soon as the listener is added, nodeAdded is called for each child of node.

Parameters:

node - The full path of the node to observe.

listener - The listener.

removeListener

void removeListener(String node,
                  DistributedTree.Listener listener)

Removes a listener.

Parameters:

node - The full path of the node the listener is currently observing.

listener - The listener to remove.

print

void print(String node,
         PrintStream out)

Prints the tree's structure, starting at a given node, to the given stream.

Parameters:

node - The node that will serve as the root of the dump.

out - The output stream to which the tree structure is to be sent.