com.tc.cluster
Interface DsoCluster


public interface DsoCluster

The DsoCluster interface provides access to Terracotta DSO cluster events and meta data.

When Terracotta DSO is active, an instance of this interface will be injected into a field of an instrumented class when that field is annotated with the InjectedDsoInstance annotation or when it's included in the injected-instances section of the Terracotta XML configuration. Field injection will always replace any values that were already assigned to those fields and prevent any other assignments from replacing the value. The injection happens before any constructor logic.

To allow cluster events and meta data to be tested without Terracotta DSO being active, the SimulatedDsoCluster class can be used.

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

See DsoClusterListener for more information about the events themselves.

Since:
3.0.0

Method Summary
 void addClusterListener(DsoClusterListener listener)
          Adds a cluster events listener.
 boolean areOperationsEnabled()
          Indicates whether operations are enabled on the current node.
 DsoClusterTopology getClusterTopology()
          Retrieves a view of the topology of the cluster, as seen from the current node.
 DsoNode getCurrentNode()
          Retrieves the DsoNode instance that corresponds to the current node.
<K> java.util.Set<K>
getKeysForLocalValues(java.util.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> java.util.Set<K>
getKeysForOrphanedValues(java.util.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.
 java.util.Set<DsoNode> getNodesWithObject(java.lang.Object object)
          Determine on which nodes a particular object is faulted.
 java.util.Map<?,java.util.Set<DsoNode>> getNodesWithObjects(java.util.Collection<?> objects)
          Determine where a collection of clustered objects is faulted.
 java.util.Map<?,java.util.Set<DsoNode>> getNodesWithObjects(java.lang.Object... objects)
          Determine where a series of clustered objects is faulted.
 boolean isNodeJoined()
          Indicates whether the current node has joined the cluster.
 void removeClusterListener(DsoClusterListener listener)
          Removes a cluster events listener.
 DsoNode waitUntilNodeJoinsCluster()
          Waits until this node joins the cluster.
 

Method Detail

addClusterListener

void addClusterListener(DsoClusterListener 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(DsoClusterListener 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

DsoClusterTopology 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 DsoClusterTopology.getNodes() method.

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

getCurrentNode

DsoNode getCurrentNode()
Retrieves the DsoNode instance that corresponds to the current node. May return null if this node is not connected to the cluster yet.

Returns:
the DsoNode instance that corresponds to the current node. May return null if this node is not connected to the cluster yet.

waitUntilNodeJoinsCluster

DsoNode waitUntilNodeJoinsCluster()
Waits until this node joins the cluster. This operation can be interrupted.

Returns:
the DsoNode instance that corresponds to the current node. May return null if the thread is interrupted before the current node joins the cluster.

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

getNodesWithObject

java.util.Set<DsoNode> getNodesWithObject(java.lang.Object object)
                                          throws UnclusteredObjectException
Determine on which nodes a particular object is faulted.

Parameters:
object - the object that will be checked
Returns:
the set of nodes where the object is faulted;

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

Throws:
UnclusteredObjectException - when the object isn't clustered

getNodesWithObjects

java.util.Map<?,java.util.Set<DsoNode>> getNodesWithObjects(java.lang.Object... objects)
                                                            throws UnclusteredObjectException
Determine where a series 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

getNodesWithObjects

java.util.Map<?,java.util.Set<DsoNode>> getNodesWithObjects(java.util.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> java.util.Set<K> getKeysForOrphanedValues(java.util.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> java.util.Set<K> getKeysForLocalValues(java.util.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


Copyright © 2010 Terracotta, Inc.. All Rights Reserved.