[jboss-cvs] JBossAS SVN: r69398 - in projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework: server and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Jan 28 15:53:59 EST 2008
Author: bstansberry at jboss.com
Date: 2008-01-28 15:53:59 -0500 (Mon, 28 Jan 2008)
New Revision: 69398
Modified:
projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/interfaces/DistributedReplicantManager.java
projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/server/HATarget.java
Log:
[JBAS-5183] Provide info as to whether topology changes are due to a merge
Javadoc fixes
Move some HATarget methods to protected from public
Modified: projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/interfaces/DistributedReplicantManager.java
===================================================================
--- projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/interfaces/DistributedReplicantManager.java 2008-01-28 20:06:26 UTC (rev 69397)
+++ projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/interfaces/DistributedReplicantManager.java 2008-01-28 20:53:59 UTC (rev 69398)
@@ -21,21 +21,37 @@
*/
package org.jboss.ha.framework.interfaces;
-import org.jboss.ha.framework.interfaces.DistributedReplicantManager.ReplicantListener;
import java.io.Serializable;
import java.util.List;
import java.util.Collection;
/**
*
- * DistributedReplicantManager is a service on top of HAPartition that provides a
+ * DistributedReplicantManager is a service on top of {@link 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.
+ * <p>
+ * Typical usages for DistributedReplicantManager are:
+ * <ol>
+ * <li>To serve as a distributed registry for remote service endpoints for
+ * clustered services. In this usage, the Serializable <code>replicants</code>
+ * that services store in the DRM are information (e.g. RMI stubs, JBoss Remoting
+ * <code>InvokerLocator</code> 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.</li>
+ * <li>To simply serve as a distributed registry showing on what cluster
+ * nodes particular services are deployed. Here the Serializable
+ * <code>replicants</code> 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.</li>
+ * </ol>
*
* @author <a href="mailto:bill at burkecentral.com">Bill Burke</a>.
* @author <a href="mailto:sacha.labourey at cogito-info.ch">Sacha Labourey</a>.
+ * @author <a href="mailto:brian.stansberry at jboss.com">Brian Stansberry</a>
* @author <a href="mailto:galder.zamarreno at jboss.com">Galder Zamarreno</a>
* @version $Revision$
*
@@ -65,18 +81,20 @@
* cluster nodes on which the current viewId is
* in effect
* @param newReplicantsViewId The new replicant view id corresponding to this change
+ * @param merge Is the change due to a merge (i.e. the healing of a
+ * cluster split)?
*/
- public void replicantsChanged(String key, List newReplicants, int newReplicantsViewId);
+ public void replicantsChanged(String key, List newReplicants, int newReplicantsViewId, boolean merge);
}
/**
- * Subscribe a new listener {@link ReplicantListener} for replicant changes
- * @param key Name of the replicant, must be identical cluster-wide for all identical replicants
+ * Subscribe a new {@link ReplicantListener listener } for replicant changes
+ * @param key Name of the replicant, must be identical cluster-wide for all related replicants
* @param subscriber The subscribing {@link ReplicantListener}
*/
public void registerListener(String key, ReplicantListener subscriber);
/**
- * Unsubscribe a listener {@link ReplicantListener} that had subscribed for replicant changes
+ * Unsubscribe a {@link ReplicantListener listener} that had subscribed for replicant changes
* @param key Name of the replicant, must be identical cluster-wide for all identical replicants
* @param subscriber The unsubscribing {@link ReplicantListener}
*/
@@ -86,29 +104,29 @@
//
/**
- * Add a replicant, it will be attached to this cluster node
- * @param key Replicant name. All replicas around the cluster must use the same key name.
+ * Add a replicant, which will be associated with this cluster node in the registry.
+ * @param key Replicant name. All related replicas around the cluster must use the same key name.
* @param replicant Local data of the replicant, that is, any serializable data
* @throws Exception Thrown if a cluster communication problem occurs
*/
public void add(String key, Serializable replicant) throws Exception;
/**
- * Remove the entire key from the ReplicationService
+ * Remove this cluster node's replicant for the given key from the registry
* @param key Name of the replicant
* @throws Exception Thrown if a cluster communication problem occurs
*/
public void remove(String key) throws Exception;
/**
- * Lookup the replicant attached to this cluster node
+ * Lookup the replicant associated with this cluster node and the given key
* @param key The name of the replicant
* @return The local replicant for the given key name
*/
public Serializable lookupLocalReplicant(String key);
/**
- * Return a list of all replicants.
+ * Return a list of all replicants for the given key.
* @param key The replicant name
* @return A list of serialized replicants available around the cluster
* for the given key. This list will be in the same order in all
@@ -117,7 +135,8 @@
public List lookupReplicants(String key);
/**
- * Return a list of all replicants node names.
+ * Return a list of the names of all nodes that have registered a replicant
+ * for the given key.
* @param key The replicant name
* @return 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
@@ -125,14 +144,15 @@
* @deprecated Replaced by {@link #lookupReplicantsNodes(String)} that
* returns a List of ClusterNode. Call
* {@link ClusterNode#getName()} on List entries to get same
- * behaivour.
+ * behavior.
*/
@Deprecated public List lookupReplicantsNodeNames(String key);
/**
- * Return a list of all replicants nodes.
+ * Return a list of the {@link ClusterNode} objects for all nodes that have
+ * registered a replicant for the given key.
* @param key The replicant name
- * @return A list of the ClusterNode instances that have made available
+ * @return A list of the {@link 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.
*/
@@ -140,19 +160,26 @@
/**
* Return a list of all services that have at least one replicant.
- * @return A collection of service names (String)
+ * @return A <code>Collection<String></code> of service names; i.e. the
+ * <code>key</code>s passed to {@link #add(String, Serializable)}
*/
public Collection getAllServices ();
/**
* 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.
+ *
* @param key The replicant name
* @return A view id (doesn't grow sequentially)
*/
public int getReplicantsViewId(String key);
/**
- * Indicates if the current node is the master replica for this given 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 <code>lookupReplicantsNodes(key)</code>.
+ *
* @param key The replicant name
* @return True if this node is the master
*/
Modified: projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/server/HATarget.java
===================================================================
--- projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/server/HATarget.java 2008-01-28 20:06:26 UTC (rev 69397)
+++ projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/server/HATarget.java 2008-01-28 20:53:59 UTC (rev 69398)
@@ -31,9 +31,12 @@
import java.io.Serializable;
/**
- * This class is a holder and manager of replicants.
- * It manages lists of replicated objects and changes the list as the HAPartition
- * notifies it.
+ * Control point representing a clustered service. Works with the
+ * {@link DistributedReplicantManager} to makes available a
+ * {@link #getReplicants() list of replicants} (objects used to identify remote
+ * service endpoints around the cluster) for the service. Guards access to the
+ * service via the {@link #invocationsAllowed()} and
+ * {@link #setInvocationsAuthorization(int)} methods.
*
* @author bill at burkecentral.com
* @version $Revision$
@@ -47,8 +50,21 @@
public class HATarget
implements ReplicantListener
{
+ /**
+ * Argument to {@link #setInvocationsAuthorization(int)} that indicates
+ * {@link #invocationsAllowed()} should return <code>false</code>.
+ */
public static final int DISABLE_INVOCATIONS = 0;
+ /**
+ * Argument to {@link #setInvocationsAuthorization(int)} that indicates
+ * calls to {@link #invocationsAllowed()} should block until a different
+ * value is passed to {@link #setInvocationsAuthorization(int)}.
+ */
public static final int MAKE_INVOCATIONS_WAIT = 1;
+ /**
+ * Argument to {@link #setInvocationsAuthorization(int)} that indicates
+ * {@link #invocationsAllowed()} should return <code>true</code>.
+ */
public static final int ENABLE_INVOCATIONS = 2;
protected String replicantName;
@@ -60,6 +76,17 @@
protected int allowInvocationsStatus = 0;
protected CountDownLatch latch = null;
+ /**
+ * Creates a new HATarget.
+ *
+ * @param partition the {@link HAPartition} for the service's cluster
+ * @param replicantName the name of the service
+ * @param target the service's {@link #getReplicants() replicant}
+ * @param allowInvocations <code>true</code> if {@link #invocationsAllowed()}
+ * should return <code>true</code> immediately;
+ * <code>false</code> if not
+ * @throws Exception
+ */
public HATarget(HAPartition partition,
String replicantName,
Serializable target,
@@ -72,11 +99,6 @@
setInvocationsAuthorization (allowInvocations);
updateHAPartition(partition);
}
-
- public void init() throws Exception
- {
- this.log = Logger.getLogger(this.getClass());
- }
public String toString()
{
@@ -91,11 +113,21 @@
return buffer.toString();
}
+ /**
+ * Gets the current
+ * {@link DistributedReplicantManager#getReplicantsViewId(String) view id}
+ * for the clustered service.
+ */
public long getCurrentViewId()
{
return (long)clusterViewId;
}
+ /**
+ * Removes the local node from the distributed registry of nodes providing
+ * the service and causes {@link #invocationsAllowed()} to return
+ * <code>false</code>.
+ */
public void destroy()
{
try
@@ -112,9 +144,17 @@
}
}
- // After this call, the HATarget can still be queried for view change, etc. but
- // the local node is no more part of the cluster: temporary state
- //
+ /**
+ * Removes the local node from the distributed registry of nodes providing
+ * the service. After this call, the HATarget can still be queried for
+ * view change, etc. but the local node's instance of the service is no
+ * longer registered with the cluster.
+ * <p>
+ * <strong>NOTE:</strong> Calling this method does not cause
+ * {@link #invocationsAllowed()} to return <code>false</code>. Use
+ * {@link #destroy()} unless your application needs to separately control
+ * the two aspects of shutting down a clustered service.
+ */
public void disable()
{
try
@@ -131,21 +171,24 @@
}
}
+ /**
+ * Gets the replicants for the clustered service. A <code>replicant</code>
+ * is a service-specific object, typically something that represents a
+ * remote service endpoint for the service on a particular cluster node.
+ * Examples include an RMI stub, a JBoss Remoting <code>InvokerLocator</code>
+ * or an HTTP URL.
+ */
public ArrayList getReplicants()
{
return replicants;
}
-
- public void updateHAPartition(HAPartition partition) throws Exception
- {
- cleanExistenceInCurrentHAPartition();
-
- this.partition = partition;
- DistributedReplicantManager drm = partition.getDistributedReplicantManager();
- drm.registerListener(this.replicantName, this);
- drm.add(this.replicantName, this.target);
- }
+ /**
+ * Sets the behavior expected from {@link #invocationsAllowed()}.
+ *
+ * @param status {@link #ENABLE_INVOCATIONS}, {@link #DISABLE_INVOCATIONS}
+ * or {@link #MAKE_INVOCATIONS_WAIT}
+ */
public synchronized void setInvocationsAuthorization (int status)
{
if (this.allowInvocationsStatus == status)
@@ -174,6 +217,17 @@
}
}
+ /**
+ * Returns whether invocations on the target service are currently allowed
+ * on this node. Will block if {@link #setInvocationsAuthorization(int)} has
+ * been set to {@link #MAKE_INVOCATIONS_WAIT}.
+ *
+ * @return <code>true</code>e if it is valid to make invocations on the
+ * service, <code>false</code> otherwise
+ * @throws InterruptedException if the current thread is interrupted while
+ * blocking waiting for {@link #MAKE_INVOCATIONS_WAIT}
+ *
+ */
public boolean invocationsAllowed () throws InterruptedException
{
if (this.allowInvocationsStatus == ENABLE_INVOCATIONS)
@@ -199,15 +253,6 @@
return false;
}
- protected void releaseCurrentLatch ()
- {
- if (latch != null)
- {
- latch.countDown();
- latch = null;
- }
- }
-
public HAPartition getAssociatedPartition ()
{
return this.partition;
@@ -215,12 +260,11 @@
// DistributedReplicantManager.ReplicantListener implementation ------------
- public void replicantsChanged(String key, List newReplicants, int newReplicantsViewId)
+ public void replicantsChanged(String key, List newReplicants, int newReplicantsViewId, boolean merge)
{
- if (log.isDebugEnabled())
- log.debug("replicantsChanged '" + replicantName +
- "' to " + (newReplicants==null? "0 (null)" : Integer.toString (newReplicants.size() ) ) +
- " (intra-view id: " + newReplicantsViewId + ")");
+ log.debug("replicantsChanged '" + replicantName +
+ "' to " + (newReplicants==null? "0 (null)" : Integer.toString (newReplicants.size() ) ) +
+ " (intra-view id: " + newReplicantsViewId + ")");
synchronized(replicants)
{
@@ -235,6 +279,37 @@
}
+ /**
+ * Allows subclasses to perform initialization work.
+ *
+ * @throws Exception
+ * @deprecated this will be removed in the next major release
+ */
+ @Deprecated protected void init() throws Exception
+ {
+ this.log = Logger.getLogger(this.getClass());
+ }
+
+ /**
+ * Associates this target with the given partition, registering
+ * with the partition's {@link DistributedReplicantManager}.
+ *
+ * @param partition the partition
+ * @throws Exception
+ */
+ protected void updateHAPartition(HAPartition partition) throws Exception
+ {
+ cleanExistenceInCurrentHAPartition();
+
+ this.partition = partition;
+ DistributedReplicantManager drm = partition.getDistributedReplicantManager();
+ drm.registerListener(this.replicantName, this);
+ drm.add(this.replicantName, this.target);
+ }
+
+ /**
+ * Unregister's with the partition's {@link DistributedReplicantManager}.
+ */
protected void cleanExistenceInCurrentHAPartition()
{
if (this.partition != null)
@@ -251,4 +326,16 @@
}
}
}
+
+ /**
+ * Releases any latch blocking threads in {@link #invocationsAllowed()}.
+ */
+ protected void releaseCurrentLatch ()
+ {
+ if (latch != null)
+ {
+ latch.countDown();
+ latch = null;
+ }
+ }
}
More information about the jboss-cvs-commits
mailing list