User: slaboure
Date: 01/11/26 06:43:21
Modified: src/main/org/jboss/ha/framework/interfaces
DistributedState.java
Log:
Added javadoc comments. Removed unnecessary exceptions
Revision Changes Path
1.3 +90 -31
jbossmx/src/main/org/jboss/ha/framework/interfaces/DistributedState.java
Index: DistributedState.java
===================================================================
RCS file:
/cvsroot/jboss/jbossmx/src/main/org/jboss/ha/framework/interfaces/DistributedState.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- DistributedState.java 2001/10/10 20:02:05 1.2
+++ DistributedState.java 2001/11/26 14:43:21 1.3
@@ -1,62 +1,121 @@
+/*
+ * JBoss, the OpenSource J2EE webOS
+ *
+ * Distributable under LGPL license.
+ * See terms of license at gnu.org.
+ */
+
package org.jboss.ha.framework.interfaces;
-import java.util.Collection;
-import java.io.Serializable;
+
+import org.jboss.ha.framework.interfaces.DistributedState.DSListener;
-import java.rmi.Remote;
+import java.io.Serializable;
import java.rmi.RemoteException;
+import java.util.Collection;
-/**
+/**
+ * DistributedState is a service on top of HAPartition that provides a cluster-wide
distributed state.
+ * First, the DistributedState (DS) service provides a spliting in categories.
Thus, any
+ * service, application, container, ... can request its own DS "private space" by
working
+ * in its own category (a string name).
+ * Then, it is possible to work in a category like with a Dictionary: you set
values to key.
+ * 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
+ * modified/removed/added in a particular category.
*
- * @author [EMAIL PROTECTED]
- * @version $Revision: 1.2 $
+ * @author <a href="mailto:[EMAIL PROTECTED]">Sacha Labourey</a>.
+ * @version $Revision: 1.3 $
*
* <p><b>Revisions:</b><br>
+ * @see HAPartition
*/
-public interface DistributedState extends Remote
+public interface DistributedState
+ extends java.rmi.Remote
{
/**
- * When a particular key in the DistributedState table gets modified, all
listeners
- * will be notified of replicant changes for that key. Keys are organized in
categories.
+ * When a particular key in a category of the DistributedState service gets
modified,
+ * all listeners will be notified of DS changes for that category.
*/
public interface DSListener
{
- public void valueHasChanged(String category, String key, Serializable value);
+ /**
+ * 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 value The new value of the key
+ */
+ public void valueHasChanged (String category, String key, Serializable value);
+ /**
+ * Called whenever a key has been removed from a category the called object
had
+ * subscribed in.
+ * @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
+ */
public void keyHasBeenRemoved (String category, String key, Serializable
previousContent);
}
-
- public void registerDSListener(String category, DSListener subscriber) throws
RemoteException;
- public void unregisterDSListener(String category, DSListener subscriber) throws
RemoteException;
-
+
+ /**
+ * Subscribes to receive {@link DistributedState.DSListener} events
+ * @param category Name of the private-space to watch for
+ * @param subscriber Object that will receive callbacks
+ */
+ public void registerDSListener (String category, DSListener subscriber);
+ /**
+ * Subscribes from {@link DistributedState.DSListener} events
+ * @param category Name of the private-space dictionary currently observed
+ * @param subscriber object currently observing this category
+ */
+ public void unregisterDSListener (String category, DSListener subscriber);
+
// State binding methods
//
/**
- * remove the entire key from the ReplicationService
+ * Associates a value to a key in a specific category
+ * @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
*/
- public void remove(String category, String key) throws Exception;
-
+ public void set (String category, String key, Serializable value) throws
Exception;
+
/**
- * Associates a value to a key in a specific category
+ * Read in a value associated to a key in the given category. Read is performed
locally.
+ * @param category Name of the private naming-space
+ * @param key The key of the value to read
+ * @return The value of the key in the given category
*/
- public void set(String category, String key, Serializable value) throws
Exception;
-
+ public Serializable get (String category, String key);
+
/**
- * Lookup the replicant attached to this cluster node
+ * Return a list of all categories. Call managed locally: no network access.
+ * @return A collection of String representing the existing categories in the DS
service.
*/
- public Serializable get(String category, String key) throws RemoteException;
-
+ public Collection getAllCategories ();
+
/**
- * Return a list of all categories.
+ * Return a list of all keys in a category. Call managed locally: no network
access.
+ * @param category The category under which to look for keys
+ * @return A collection of all keys in the give category
*/
- public Collection getAllCategories() throws RemoteException;
-
+ public Collection getAllKeys (String category);
+
/**
- * Return a list of all keys in a category.
+ * Return a list of all values in a category. Call managed locally: no network
access.
+ * @param category The category name under which to look for values
+ * @return A collection of all values in the give category
*/
- public Collection getAllKeys(String category) throws RemoteException;
-
+ public Collection getAllValues (String category);
+
/**
- * Return a list of all values in a category.
+ * Remove the key from the ReplicationService in the given category
+ * @param category Name of the category
+ * @param key Key to be removed
+ * @throws Exception if a network exception occurs while removing the entry.
*/
- public Collection getAllValues(String category) throws RemoteException;
+ public void remove (String category, String key) throws Exception;
}
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/jboss-development