001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package org.jboss.ha.framework.interfaces;
023:
024: import java.io.Serializable;
025: import java.util.Collection;
026:
027: /**
028: * DistributedState is a service on top of HAPartition that provides a
029: * cluster-wide distributed state. The DistributedState (DS) service
030: * provides a <String categorgy, Serializable key, Serializable value> tuple
031: * map. Thus, any service, application, container, ... can request its own DS
032: * "private space" by working* in its own category (a string name).
033: * You work in a category like a Dictionary: you set values by key within a
034: * category. Each time a value is added/modified/removed, the modification
035: * is made cluster-wide, on all other nodes.
036: * Reading values is always made locally (no network access!)
037: * Objects can also subscribes to DS events to be notified when some values gets
038: * modified/removed/added in a particular category.
039: *
040: * @author <a href="mailto:sacha.labourey@cogito-info.ch">Sacha Labourey</a>.
041: * @author Scott.Stark@jboss.org
042: * @version $Revision: 57188 $
043: * @see HAPartition
044: */
045: public interface DistributedState {
046: /**
047: * When a particular key in a category of the DistributedState service gets
048: * modified, all listeners will be notified of DS changes for that category.
049: * @deprecated use the DSListenerEx instead
050: */
051: public interface DSListener {
052: /**
053: * Called whenever a key has been added or modified in the category the called object
054: * has subscribed in.
055: * @param category The category of the modified/added entry
056: * @param key The key that has been added or its value modified
057: * @param value The new value of the key
058: */
059: public void valueHasChanged(String category, String key,
060: Serializable value, boolean locallyModified);
061:
062: /**
063: * Called whenever a key has been removed from a category the called object had
064: * subscribed in.
065: * @param category The category under which a key has been removed
066: * @param key The key that has been removed
067: * @param previousContent The previous content of the key that has been removed
068: */
069: public void keyHasBeenRemoved(String category, String key,
070: Serializable previousContent, boolean locallyModified);
071: }
072:
073: /** A generalization of the DSListener that supports the Serializable key
074: * type. When a particular key in a category of the DistributedState service
075: * gets modified, all listeners will be notified of DS changes for that
076: * category.
077: */
078: public interface DSListenerEx {
079: /**
080: * Called whenever a key has been added or modified in the category the called object
081: * has subscribed in.
082: * @param category The category of the modified/added entry
083: * @param key The key that has been added or its value modified
084: * @param value The new value of the key
085: */
086: public void valueHasChanged(String category, Serializable key,
087: Serializable value, boolean locallyModified);
088:
089: /**
090: * Called whenever a key has been removed from a category the called object had
091: * subscribed in.
092: * @param category The category under which a key has been removed
093: * @param key The key that has been removed
094: * @param previousContent The previous content of the key that has been removed
095: */
096: public void keyHasBeenRemoved(String category,
097: Serializable key, Serializable previousContent,
098: boolean locallyModified);
099: }
100:
101: /**
102: * Subscribes to receive {@link DistributedState.DSListenerEx} events
103: * @param category Name of the private-space to watch for
104: * @param subscriber Object that will receive callbacks. This
105: */
106: public void registerDSListenerEx(String category,
107: DSListenerEx subscriber);
108:
109: /**
110: * Subscribes from {@link DistributedState.DSListenerEx} events
111: * @param category Name of the private-space dictionary currently observed
112: * @param subscriber object currently observing this category
113: */
114: public void unregisterDSListenerEx(String category,
115: DSListenerEx subscriber);
116:
117: /**
118: * Subscribes to receive {@link DistributedState.DSListener} events
119: * @param category Name of the private-space to watch for
120: * @param subscriber Object that will receive callbacks. This
121: */
122: public void registerDSListener(String category,
123: DSListener subscriber);
124:
125: /**
126: * Subscribes from {@link DistributedState.DSListener} events
127: * @param category Name of the private-space dictionary currently observed
128: * @param subscriber object currently observing this category
129: */
130: public void unregisterDSListener(String category,
131: DSListener subscriber);
132:
133: // State binding methods
134: //
135: /**
136: * Associates a value to a key in a specific category
137: * @param category Name of the private naming-space
138: * @param key Name of the data to set
139: * @param value Value of the data to set
140: * @throws Exception If a network communication occurs
141: */
142: public void set(String category, Serializable key,
143: Serializable value) throws Exception;
144:
145: /**
146: * Same as set(String, String) but caller can choose if the call is made
147: * synchronously or asynchronously. By default, calls are asynchronous.
148: */
149: public void set(String category, Serializable key,
150: Serializable value, boolean asynchronousCall)
151: throws Exception;
152:
153: /**
154: * Read in a value associated to a key in the given category. Read is performed locally.
155: * @param category Name of the private naming-space
156: * @param key The key of the value to read
157: * @return The value of the key in the given category
158: */
159: public Serializable get(String category, Serializable key);
160:
161: /**
162: * Return a list of all categories. Call managed locally: no network access.
163: * @return A collection of String representing the existing categories in the DS service.
164: */
165: public Collection getAllCategories();
166:
167: /**
168: * Return a list of all keys in a category. Call managed locally: no network access.
169: * @param category The category under which to look for keys
170: * @return A collection of all keys in the give category
171: */
172: public Collection getAllKeys(String category);
173:
174: /**
175: * Return a list of all values in a category. Call managed locally: no network access.
176: * @param category The category name under which to look for values
177: * @return A collection of all values in the give category
178: */
179: public Collection getAllValues(String category);
180:
181: /**
182: * Remove the key from the ReplicationService in the given category
183: * @param category Name of the category
184: * @param key Key to be removed
185: * @throws Exception if a network exception occurs while removing the entry.
186: */
187: public Serializable remove(String category, Serializable key)
188: throws Exception;
189:
190: /**
191: * Same as remove(String, String) but caller can choose if the call is made
192: * synchronously or asynchronously. By default, calls are asynchronous.
193: */
194: public Serializable remove(String category, Serializable key,
195: boolean asynchronousCall) throws Exception;
196: }
|