org.jboss.ha.framework.interfaces
Interface DistributedReplicantManager


public interface DistributedReplicantManager

DistributedReplicantManager is a service on top of HAPartition that provides a cluster-wide distributed state which is node-specific. The DistributedReplicantManager (DRM) service provides a <String key, Serializable replicant> tuple map. Each node in the cluster stores its own data for a given key. This data is replicated so that reading values for a key is always performed locally.

Typical usages for DistributedReplicantManager are:

  1. To serve as a distributed registry for remote service endpoints for clustered services. In this usage, the Serializable replicants that services store in the DRM are information (e.g. RMI stubs, JBoss Remoting InvokerLocator instances, HTTP URLs etc) that remote clients would need to contact the clustered service. This usage of DRM drives the smart clustered proxy implementations used by JBoss AS.
  2. To simply serve as a distributed registry showing on what cluster nodes particular services are deployed. Here the Serializable replicants that services store in the DRM are usually just simple placeholder strings; the presence of the tuple itself is what indicates the service is available on a particular node. This usage of DRM drives JBoss AS services like HASingleton.

Version:
$Revision: 74879 $

Revisions:

2001/10/31: marcf

  1. DRM is no longer remote

2002/08/23: Sacha Labourey

  1. added isMasterReplica
Author:
Bill Burke., Sacha Labourey., Brian Stansberry, Galder Zamarreno

Nested Class Summary
static interface DistributedReplicantManager.ReplicantListener
          When a particular key in the DistributedReplicantManager table gets modified, all listeners will be notified of replicant changes for that key.
 
Method Summary
 void add(String key, Serializable replicant)
          Add a replicant, which will be associated with this cluster node in the registry.
 Collection getAllServices()
          Return a list of all services that have at least one replicant.
 int getReplicantsViewId(String key)
          Returns an id corresponding to the current view of this set of replicants.
 boolean isMasterReplica(String key)
          Indicates if the current node is the master replica for this given key; i.e.
 Serializable lookupLocalReplicant(String key)
          Lookup the replicant associated with this cluster node and the given key
 List lookupReplicants(String key)
          Return a list of all replicants for the given key.
 List lookupReplicantsNodeNames(String key)
          Deprecated. Replaced by lookupReplicantsNodes(String) that returns a List of ClusterNode. Call ClusterNode.getName() on List entries to get same behavior.
 List<ClusterNode> lookupReplicantsNodes(String key)
          Return a list of the ClusterNode objects for all nodes that have registered a replicant for the given key.
 void registerListener(String key, DistributedReplicantManager.ReplicantListener subscriber)
          Subscribe a new listener for replicant changes
 void remove(String key)
          Remove this cluster node's replicant for the given key from the registry
 void unregisterListener(String key, DistributedReplicantManager.ReplicantListener subscriber)
          Unsubscribe a listener that had subscribed for replicant changes
 

Method Detail

registerListener

void registerListener(String key,
                      DistributedReplicantManager.ReplicantListener subscriber)
Subscribe a new listener for replicant changes

Parameters:
key - Name of the replicant, must be identical cluster-wide for all related replicants
subscriber - The subscribing DistributedReplicantManager.ReplicantListener

unregisterListener

void unregisterListener(String key,
                        DistributedReplicantManager.ReplicantListener subscriber)
Unsubscribe a listener that had subscribed for replicant changes

Parameters:
key - Name of the replicant, must be identical cluster-wide for all identical replicants
subscriber - The unsubscribing DistributedReplicantManager.ReplicantListener

add

void add(String key,
         Serializable replicant)
         throws Exception
Add a replicant, which will be associated with this cluster node in the registry.

Parameters:
key - Replicant name. All related replicas around the cluster must use the same key name.
replicant - Local data of the replicant, that is, any serializable data
Throws:
Exception - Thrown if a cluster communication problem occurs

remove

void remove(String key)
            throws Exception
Remove this cluster node's replicant for the given key from the registry

Parameters:
key - Name of the replicant
Throws:
Exception - Thrown if a cluster communication problem occurs

lookupLocalReplicant

Serializable lookupLocalReplicant(String key)
Lookup the replicant associated with this cluster node and the given key

Parameters:
key - The name of the replicant
Returns:
The local replicant for the given key name

lookupReplicants

List lookupReplicants(String key)
Return a list of all replicants for the given key.

Parameters:
key - The replicant name
Returns:
A list of serialized replicants available around the cluster for the given key. This list will be in the same order in all nodes in the cluster.

lookupReplicantsNodeNames

@Deprecated
List lookupReplicantsNodeNames(String key)
Deprecated. Replaced by lookupReplicantsNodes(String) that returns a List of ClusterNode. Call ClusterNode.getName() on List entries to get same behavior.

Return a list of the names of all nodes that have registered a replicant for the given key.

Parameters:
key - The replicant name
Returns:
A list of the node names of cluster nodes that have made available a replicant for the given key. This list will be in the same order in all nodes in the cluster.

lookupReplicantsNodes

List<ClusterNode> lookupReplicantsNodes(String key)
Return a list of the ClusterNode objects for all nodes that have registered a replicant for the given key.

Parameters:
key - The replicant name
Returns:
A list of the ClusterNode instances that have made available a replicant for the given key. This list will be in the same order in all nodes in the cluster.

getAllServices

Collection getAllServices()
Return a list of all services that have at least one replicant.

Returns:
A Collection of service names; i.e. the keys passed to add(String, Serializable)

getReplicantsViewId

int getReplicantsViewId(String key)
Returns an id corresponding to the current view of this set of replicants. The id is a hash of the list of nodes that have registered a replicant for the key.

Parameters:
key - The replicant name
Returns:
A view id (doesn't grow sequentially)

isMasterReplica

boolean isMasterReplica(String key)
Indicates if the current node is the master replica for this given key; i.e. whether the current node would be the first element in the list returned from a call to lookupReplicantsNodes(key).

Parameters:
key - The replicant name
Returns:
True if this node is the master


Copyright © 2009 JBoss, a division of Red Hat, Inc.. All Rights Reserved.