org.terracotta.cluster
Interface ClusterInfo

All Known Implementing Classes:

TerracottaClusterInfo

public interface ClusterInfo

The ClusterInfo interface provides access to cluster events and meta data.

Note that only client nodes are taken into account for the cluster events and meta data, information about server nodes is not available.

See ClusterListener for more information about the events themselves.

Method Summary

void	addClusterListener(ClusterListener listener) Adds a cluster events listener.
boolean	areOperationsEnabled() Indicates whether operations are enabled on the current node.
ClusterTopology	getClusterTopology() Retrieves a view of the topology of the cluster, as seen from the current node.
ClusterNode	getCurrentNode() Retrieves the ClusterNode instance that corresponds to the current node.
<K> Set<K>	getKeysForLocalValues(Map<K,?> map) Retrieve a set of keys for map values that are faulted on the current node out of a clustered map for which partialness is supported.
<K> Set<K>	getKeysForOrphanedValues(Map<K,?> map) Retrieve a set of keys for map values that are not faulted anywhere out of a clustered map for which partialness is supported.
Map<?,Set<ClusterNode>>	getNodesWithObjects(Collection<?> objects) Determine where a collection of clustered objects is faulted.
String	getUniversallyUniqueClientID() Returns a universally unique identifier for the life-time of this client in the cluster.
boolean	isClusterInitialized() Indicates whether the cluster infrastructure was initialized when this info instance was created.
boolean	isNodeJoined() Indicates whether the current node has joined the cluster.
void	removeClusterListener(ClusterListener listener) Removes a cluster events listener.
ClusterNode	waitUntilNodeJoinsCluster() Waits until the current node has successfully joined the cluster.

Method Detail

isClusterInitialized

boolean isClusterInitialized()

Indicates whether the cluster infrastructure was initialized when this info instance was created.

Note that a cluster needs to be initialized for any of the other methods to function. If there's a chance that the code that's using this cluster info instance is using it with an uninitialized cluster infrastructure, the return value of this method should be checked before using the cluster info.

Returns:

true when the cluster was initialized; or false when this was not the case

getUniversallyUniqueClientID

String getUniversallyUniqueClientID()

Returns a universally unique identifier for the life-time of this client in the cluster.

It will be the same for the entire life-time of this cluster client. However once the client is restarted, this identifier will be different. No two identifiers will ever be the same for different life-times or for different clients.

Returns:

the identifier as a string

addClusterListener

void addClusterListener(ClusterListener listener)

Adds a cluster events listener.

If the cluster events listener instance has already been registered before, this method will not register it again.

When the cluster is already joined or the operations have already been enabled, those events will be immediately triggered on the listener when it's registered.

Parameters:

listener - the cluster listener instance that will be registered

removeClusterListener

void removeClusterListener(ClusterListener listener)

Removes a cluster events listener.

If the cluster events listener instance was not registered before, this method will have no effect.

Parameters:

listener - the cluster listener instance that will be unregistered

getClusterTopology

ClusterTopology getClusterTopology()

Retrieves a view of the topology of the cluster, as seen from the current node.

Note that the returned topology instance will be updated internally as nodes joined and leave the cluster. If you want a snapshot of the current nodes in the cluster, you should use the ClusterTopology.getNodes() method.

Returns:

an instance of the cluster topology as seen from the current node

getCurrentNode

ClusterNode getCurrentNode()

Retrieves the ClusterNode instance that corresponds to the current node.

Returns:

the ClusterNode instance that corresponds to the current node

isNodeJoined

boolean isNodeJoined()

Indicates whether the current node has joined the cluster.

Returns:

true if the current node has joined the cluster; false otherwise

areOperationsEnabled

boolean areOperationsEnabled()

Indicates whether operations are enabled on the current node.

Returns:

true if operations are enabled on the current node; false otherwise

waitUntilNodeJoinsCluster

ClusterNode waitUntilNodeJoinsCluster()

Waits until the current node has successfully joined the cluster.

Returns:

the ClusterNode instance that corresponds to the current node

getNodesWithObjects

Map<?,Set<ClusterNode>> getNodesWithObjects(Collection<?> objects)
                                            throws UnclusteredObjectException

Determine where a collection of clustered objects is faulted.

Each object will be a key in the map that is returned, with sets of nodes as values that indicate where the objects are faulted.

Parameters:

objects - the objects that will be checked

Returns:

the map of nodes where the objects are faulted;

this never returns null, so null checks aren't needed

Throws:

UnclusteredObjectException - when any of the objects isn't clustered

getKeysForOrphanedValues

<K> Set<K> getKeysForOrphanedValues(Map<K,?> map)
                                throws UnclusteredObjectException

Retrieve a set of keys for map values that are not faulted anywhere out of a clustered map for which partialness is supported.

Parameters:

map - the map with the values that will be checked

Returns:

the set of keys for the values that are faulted nowhere;

an empty set if the map doesn't support partialness;

this never returns null, so null checks aren't needed

Throws:

UnclusteredObjectException - when the map isn't clustered

getKeysForLocalValues

<K> Set<K> getKeysForLocalValues(Map<K,?> map)
                             throws UnclusteredObjectException

Retrieve a set of keys for map values that are faulted on the current node out of a clustered map for which partialness is supported.

Parameters:

map - the map with the values that will be checked

Returns:

the set of keys for the values that are faulted on the current node;

an empty set if the map doesn't support partialness;

this never returns null, so null checks aren't needed

Throws:

UnclusteredObjectException - when the map isn't clustered