User: slaboure
Date: 01/11/26 04:12:54
Modified: src/main/org/jboss/ha/framework/interfaces HAPartition.java
Log:
Added javadoc comments. Removed unnecessary exceptions
Revision Changes Path
1.6 +120 -15
jbossmx/src/main/org/jboss/ha/framework/interfaces/HAPartition.java
Index: HAPartition.java
===================================================================
RCS file:
/cvsroot/jboss/jbossmx/src/main/org/jboss/ha/framework/interfaces/HAPartition.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- HAPartition.java 2001/11/23 14:37:38 1.5
+++ HAPartition.java 2001/11/26 12:12:54 1.6
@@ -7,29 +7,50 @@
package org.jboss.ha.framework.interfaces;
-import java.util.ArrayList;
-import java.util.Vector;
import java.io.Serializable;
+import java.util.Vector;
+import java.util.ArrayList;
+
+import org.jboss.ha.framework.interfaces.HAPartition.HAMembershipListener;
/**
*
- * @author [EMAIL PROTECTED]
- * @author [EMAIL PROTECTED]
- * @version $Revision: 1.5 $
+ * @author <a href="mailto:[EMAIL PROTECTED]";>Bill Burke</a>.
+ * @author <a href="mailto:[EMAIL PROTECTED]";>Sacha Labourey</a>.
+ * @version $Revision: 1.6 $
*
* <p><b>Revisions:</b><br>
*/
+
public interface HAPartition
{
- // General methods
+ // *******************************
+ // *******************************
+ // Partition information accessors
+ // *******************************
+ // *******************************
//
+ /**
+ * Return the name of the current name in the current partition. The name is
dynamically determined by the partition.
+ * @return The partition name
+ */
public String getNodeName();
+ /**
+ * The name of the partition. Either set when creating the partition (MBEAN
definition) or uses the default name
+ * @return Name of the current partition
+ */
public String getPartitionName();
+ /**
+ * Accessor to the DRM that is linked to this partition.
+ * @return the DRM linked to this partition
+ */
public DistributedReplicantManager getDistributedReplicantManager();
+ /**
+ * Accessor the the DistributedState (DS) that is linked to this partition.
+ * @return the DistributedState service
+ */
public DistributedState getDistributedStateService ();
- public long getCurrentViewId();
- public Vector getCurrentView ();
// ***************************
// ***************************
@@ -37,13 +58,45 @@
// ***************************
// ***************************
//
- public void registerRPCHandler(String objectName, Object handler);
- public void unregisterRPCHandler(String objectName, Object subscriber);
+ /**
+ * The partition receives RPC calls from other nodes in the cluster and
demultiplex
+ * them, according to a service name, to a particular service. Consequently, each
+ * service must first subscribe with a particular service name in the partition.
The subscriber
+ * does not need to implement any specific interface: the call is handled
dynamically through reflection.
+ * @param serviceName Name of the subscribing service (demultiplexing key)
+ * @param handler object to be called when receiving a RPC for its key.
+ */
+ public void registerRPCHandler(String serviceName, Object handler);
+ /**
+ * Unregister the service from the partition
+ * @param serviceName Name of the service key (on which the demultiplexing
occurs)
+ * @param subscriber The target object that unsubscribes
+ */
+ public void unregisterRPCHandler(String serviceName, Object subscriber);
// Called only on all members of this partition on all nodes
//
- public ArrayList callMethodOnCluster(String objectName, String methodName,
Object[] args, boolean excludeSelf) throws Exception;
- public void callAsynchMethodOnCluster (String objName, String methodName,
Object[] args, boolean excludeSelf) throws Exception;
+ /**
+ * Invoke a synchronous RPC call on all nodes of the partition/cluster
+ * @param serviceName Name of the target service name on which calls are
de-multiplexed
+ * @param methodName name of the Java method to be called on remote services
+ * @param args array of Java Object representing the set of parameters to be
given to the remote method
+ * @param excludeSelf indicates if the RPC must also be made on the current node
of the partition or only on remote nodes
+ * @throws Exception Throws if a communication exception occurs
+ * @return an array of answers from remote nodes
+ */
+
+ public ArrayList callMethodOnCluster(String serviceName, String methodName,
Object[] args, boolean excludeSelf) throws Exception;
+ /**
+ * Invoke a asynchronous RPC call on all nodes of the partition/cluster. The
call will return immediately and will not wait
+ * that the nodes answer. Thus no answer is available.
+ * @param serviceName Name of the target service name on which calls are
de-multiplexed
+ * @param methodName name of the Java method to be called on remote services
+ * @param args array of Java Object representing the set of parameters to be
given to the remote method
+ * @param excludeSelf indicates if the RPC must also be made on the current node
of the partition or only on remote nodes
+ * @throws Exception Throws if a communication exception occurs
+ */
+ public void callAsynchMethodOnCluster (String serviceName, String methodName,
Object[] args, boolean excludeSelf) throws Exception;
// *************************
// *************************
@@ -52,14 +105,37 @@
// *************************
//
+ /**
+ * State management is higly important for clustered services. Consequently,
services that wish to manage their state
+ * need to subscribe to state transfer events. When their node start, a state is
pushed from another node to them.
+ * When another node starts, they may be asked to provide such a state to
initialise the newly started node.
+ */
public interface HAPartitionStateTransfer
{
+ /**
+ * Called when a new node need to be initialized. This is called on any
existing node to determine a current state for this service.
+ * @return A serializable representation of the state
+ */
public Serializable getCurrentState ();
+ /**
+ * This callback method is called when a new service starts on a new node:
the state that it should hold is transfered to it through this callback
+ * @param newState The serialized representation of the state of the new
service.
+ */
public void setCurrentState(Serializable newState);
}
- public void subscribeToStateTransferEvents (String objectName,
HAPartition.HAPartitionStateTransfer subscriber);
- public void unsubscribeFromStateTransferEvents (String objectName,
HAPartition.HAPartitionStateTransfer subscriber);
+ /**
+ * Register a service that will participate in state transfer protocol and
receive callbacks
+ * @param serviceName Name of the service that subscribes for state stransfer
events. This name must be identical for all identical services in the cluster.
+ * @param subscriber Object implementing {@link HAPartitionStateTransfer} and
providing or receiving state transfer callbacks
+ */
+ public void subscribeToStateTransferEvents (String serviceName,
HAPartition.HAPartitionStateTransfer subscriber);
+ /**
+ * Unregister a service from state transfer callbacks.
+ * @param serviceName Name of the service that participates in the state
transfer protocol
+ * @param subscriber Service implementing the state transfer callback methods
+ */
+ public void unsubscribeFromStateTransferEvents (String serviceName,
HAPartition.HAPartitionStateTransfer subscriber);
// *************************
// *************************
@@ -67,13 +143,42 @@
// *************************
// *************************
//
+ /**
+ * When a new node joins the cluster or an existing node leaves the cluster (or
simply dies), membership events are raised.
+ *
+ */
public interface HAMembershipListener
{
+ /**
+ * Called when a new partition topology occurs.
+ * @param deadMembers A list of nodes that have died since the previous view
+ * @param newMembers A list of nodes that have joined the partition since the
previous view
+ * @param allMembers A list of nodes that built the current view
+ */
public void membershipChanged(Vector deadMembers, Vector newMembers, Vector
allMembers);
}
+ /**
+ * Subscribes to receive {@link HAMembershipListener} events.
+ * @param listener The membership listener object
+ */
public void registerMembershipListener(HAMembershipListener listener);
+ /**
+ * Unsubscribes from receiving {@link HAMembershipListener} events.
+ * @param listener The listener wishing to unsubscribe
+ */
public void unregisterMembershipListener(HAMembershipListener listener);
-}
+ /**
+ * Each time the partition topology changes, a new view is computed. A view is a
list of members,
+ * the first member being the coordinator of the view. Each view also has a
distinct identifier.
+ * @return The identifier of the current view
+ */
+ public long getCurrentViewId();
+ /**
+ * Return the list of member nodes that built the current view i.e. the current
partition.
+ * @return An array of Strings containing the node names
+ */
+ public Vector getCurrentView ();
+}
\ No newline at end of file
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/jboss-development
