[jboss-cvs] JBossAS SVN: r75642 - projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/interfaces.

[jboss-cvs-commits at lists.jboss.org]

Author: bstansberry at jboss.com
Date: 2008-07-10 18:10:57 -0400 (Thu, 10 Jul 2008)
New Revision: 75642

Modified:
   projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/interfaces/ResponseFilter.java
Log:
Javadoc

Modified: projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/interfaces/ResponseFilter.java
===================================================================
--- projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/interfaces/ResponseFilter.java	2008-07-10 21:54:47 UTC (rev 75641)
+++ projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/interfaces/ResponseFilter.java	2008-07-10 22:10:57 UTC (rev 75642)
@@ -22,16 +22,43 @@
 package org.jboss.ha.framework.interfaces;
 
 /**
- * Cluster abstraction of JGroups' RspFilter that allows termination of a group 
- * request based on logic implemented by an implementation of this interface. 
- * The abstraction has be done to avoid first, leaking JGroups classes to 
- * ha-server-api consumers and secondly, avoid direct dependency on JGroups.  
+ * Interface defining when a group request is done, allowing early termination 
+ * of a group request based on logic implemented by the caller. For example,
+ * an RPC could be invoked on all members of a group, but as soon as a single
+ * valid response is received the {@link #needMoreResponses()} method could
+ * return <code>false</code> allowing the call to return without waiting for
+ * other slower-to-arrive responses.
  * 
+ * Based on JGroups' RspFilter concept, but with a separate abstraction. 
+ * The abstraction has be done to avoid leaking JGroups classes to 
+ * ha-server-api consumers and to avoid adding an absolute dependency on JGroups
+ * to HAPartition implementations.
+ * 
+ * @see HAPartition#callMethodOnCluster(String, String, Object[], Class[], boolean, ResponseFilter)
+ * 
  * @author <a href="mailto:galder.zamarreno at jboss.com">Galder Zamarreno</a>
  */
 public interface ResponseFilter
 {
+   /**
+    * Determines whether a response from a given sender should be added to the 
+    * response list of the request
+    * @param response The response (usually a serializable value)
+    * @param sender The sender of response
+    * @return <code>true</code> if we should add the response to the response 
+    * list of returned by 
+    * {@link HAPartition#callMethodOnCluster(String, String, Object[], Class[], boolean, ResponseFilter)
+    * otherwise false. In the latter case, the response will not be included in 
+    * the list returned to the RPC caller.
+    */
    boolean isAcceptable(Object response, ClusterNode sender);
    
+   /**
+    * Right after a call to {@link #isAcceptable(Object, ClusterNode)}, this 
+    * method is called to see whether we are done with the request and can 
+    * unblock the caller.
+    * 
+    * @return <code>true</code> if the request is done, otherwise <code>false</code>alse
+    */
    boolean needMoreResponses();
 }