[jboss-cvs] JBossAS SVN: r57820 - trunk/cluster/src/main/org/jboss/ha/framework/interfaces

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

Author: jerrygauth
Date: 2006-10-25 08:50:58 -0400 (Wed, 25 Oct 2006)
New Revision: 57820

Modified:
   trunk/cluster/src/main/org/jboss/ha/framework/interfaces/DistributedState.java
Log:
Cleaned up javadoc for DistributedState interface

Modified: trunk/cluster/src/main/org/jboss/ha/framework/interfaces/DistributedState.java
===================================================================
--- trunk/cluster/src/main/org/jboss/ha/framework/interfaces/DistributedState.java	2006-10-25 12:44:01 UTC (rev 57819)
+++ trunk/cluster/src/main/org/jboss/ha/framework/interfaces/DistributedState.java	2006-10-25 12:50:58 UTC (rev 57820)
@@ -27,14 +27,14 @@
 /**
  * DistributedState is a service on top of HAPartition that provides a
  * cluster-wide distributed state. The DistributedState (DS) service
- * provides a <String categorgy, Serializable key, Serializable value> tuple
+ * provides a <String category, Serializable key, Serializable value> tuple
  * map. Thus, any service, application, container, ... can request its own DS
  * "private space" by working* in its own category (a string name).
  * You work in a category like a Dictionary: you set values by key within a
  * category. Each time a value is added/modified/removed, the modification
  * is made cluster-wide, on all other nodes.
  * Reading values is always made locally (no network access!)
- * Objects can also subscribes to DS events to be notified when some values gets
+ * Objects can also subscribe to DS events to be notified when values are
  * modified/removed/added in a particular category.
  *
  * @author <a href="mailto:sacha.labourey at cogito-info.ch">Sacha Labourey</a>.
@@ -55,8 +55,9 @@
        * Called whenever a key has been added or modified in the category the called object
        * has subscribed in.
        * @param category The category of the modified/added entry
-       * @param key The key that has been added or its value modified
+       * @param key The key that has been added or had its value modified
        * @param value The new value of the key
+       * @param locallyModified Whether the change was made from this node
        */
       public void valueHasChanged (String category, String key,
          Serializable value, boolean locallyModified);
@@ -66,6 +67,7 @@
        * @param category The category under which a key has been removed
        * @param key The key that has been removed
        * @param previousContent The previous content of the key that has been removed
+       * @param locallyModified Whether the removal was made from this node
        */
       public void keyHasBeenRemoved (String category, String key,
          Serializable previousContent, boolean locallyModified);
@@ -82,8 +84,9 @@
        * Called whenever a key has been added or modified in the category the called object
        * has subscribed in.
        * @param category The category of the modified/added entry
-       * @param key The key that has been added or its value modified
+       * @param key The key that has been added or had its value modified
        * @param value The new value of the key
+       * @param locallyModified Whether the change was made from this node
        */
       public void valueHasChanged (String category, Serializable key,
          Serializable value, boolean locallyModified);
@@ -93,6 +96,7 @@
        * @param category The category under which a key has been removed
        * @param key The key that has been removed
        * @param previousContent The previous content of the key that has been removed
+       * @param locallyModified Whether the removal was made from this node
        */
       public void keyHasBeenRemoved (String category, Serializable key,
          Serializable previousContent, boolean locallyModified);
@@ -101,26 +105,26 @@
    /**
     * Subscribes to receive {@link DistributedState.DSListenerEx} events
     * @param category Name of the private-space to watch for
-    * @param subscriber Object that will receive callbacks. This
+    * @param subscriber Object that will receive callbacks.
     */
    public void registerDSListenerEx (String category, DSListenerEx subscriber);
    /**
-    * Subscribes from {@link DistributedState.DSListenerEx} events
+    * Unsubscribes from {@link DistributedState.DSListenerEx} events
     * @param category Name of the private-space dictionary currently observed
-    * @param subscriber object currently observing this category
+    * @param subscriber Object currently observing this category
     */
    public void unregisterDSListenerEx (String category, DSListenerEx subscriber);
 
    /**
     * Subscribes to receive {@link DistributedState.DSListener} events
     * @param category Name of the private-space to watch for
-    * @param subscriber Object that will receive callbacks. This
+    * @param subscriber Object that will receive callbacks.
     */
    public void registerDSListener (String category, DSListener subscriber);
    /**
-    * Subscribes from {@link DistributedState.DSListener} events
+    * Unsubscribes from {@link DistributedState.DSListener} events
     * @param category Name of the private-space dictionary currently observed
-    * @param subscriber object currently observing this category
+    * @param subscriber Object currently observing this category
     */
    public void unregisterDSListener (String category, DSListener subscriber);
 
@@ -131,7 +135,7 @@
     * @param category Name of the private naming-space
     * @param key Name of the data to set
     * @param value Value of the data to set
-    * @throws Exception If a network communication occurs
+    * @throws Exception If a network exception occurs
     */
    public void set (String category, Serializable key, Serializable value)
       throws Exception;
@@ -139,6 +143,11 @@
    /**
     * Same as set(String, String) but caller can choose if the call is made
     * synchronously or asynchronously. By default, calls are asynchronous.
+    * @param category Name of the private naming-space
+    * @param key Name of the data to set
+    * @param value Value of the data to set
+    * @param asynchronousCall True if the call should be asynchronous
+    * @throws Exception If a network exception occurs
     */
    public void set (String category, Serializable key, Serializable value,
       boolean asynchronousCall) throws Exception;
@@ -175,12 +184,19 @@
     * Remove the key from the ReplicationService in the given category
     * @param category Name of the category
     * @param key Key to be removed
+    * @return The value of the removed key
     * @throws Exception if a network exception occurs while removing the entry.
     */
    public Serializable remove (String category, Serializable key) throws Exception;
+   
    /**
     * Same as remove(String, String) but caller can choose if the call is made
     * synchronously or asynchronously. By default, calls are asynchronous.
+    * @param category Name of the category
+    * @param key Key to be removed
+    * @param asynchronousCall True if the call should be asynchronous
+    * @return The value of the removed key
+    * @throws Exception if a network exception occurs while removing the entry.
     */
    public Serializable remove (String category, Serializable key,
       boolean asynchronousCall) throws Exception;