KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jboss > ha > framework > interfaces > DistributedState


1 /*
2   * JBoss, Home of Professional Open Source
3   * Copyright 2005, JBoss Inc., and individual contributors as indicated
4   * by the @authors tag. See the copyright.txt in the distribution for a
5   * full listing of individual contributors.
6   *
7   * This is free software; you can redistribute it and/or modify it
8   * under the terms of the GNU Lesser General Public License as
9   * published by the Free Software Foundation; either version 2.1 of
10   * the License, or (at your option) any later version.
11   *
12   * This software is distributed in the hope that it will be useful,
13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15   * Lesser General Public License for more details.
16   *
17   * You should have received a copy of the GNU Lesser General Public
18   * License along with this software; if not, write to the Free
19   * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20   * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21   */
22 package org.jboss.ha.framework.interfaces;
23
24 import java.io.Serializable JavaDoc;
25 import java.util.Collection JavaDoc;
26
27 /**
28  * DistributedState is a service on top of HAPartition that provides a
29  * cluster-wide distributed state. The DistributedState (DS) service
30  * provides a <String category, Serializable key, Serializable value> tuple
31  * map. Thus, any service, application, container, ... can request its own DS
32  * "private space" by working* in its own category (a string name).
33  * You work in a category like a Dictionary: you set values by key within a
34  * category. Each time a value is added/modified/removed, the modification
35  * is made cluster-wide, on all other nodes.
36  * Reading values is always made locally (no network access!)
37  * Objects can also subscribe to DS events to be notified when values are
38  * modified/removed/added in a particular category.
39  *
40  * @author <a HREF="mailto:sacha.labourey@cogito-info.ch">Sacha Labourey</a>.
41  * @author Scott.Stark@jboss.org
42  * @version $Revision: 57820 $
43  * @see HAPartition
44  */
45 public interface DistributedState
46 {
47    /**
48     * When a particular key in a category of the DistributedState service gets
49     * modified, all listeners will be notified of DS changes for that category.
50     * @deprecated use the DSListenerEx instead
51     */
52    public interface DSListener
53    {
54       /**
55        * Called whenever a key has been added or modified in the category the called object
56        * has subscribed in.
57        * @param category The category of the modified/added entry
58        * @param key The key that has been added or had its value modified
59        * @param value The new value of the key
60        * @param locallyModified Whether the change was made from this node
61        */
62       public void valueHasChanged (String JavaDoc category, String JavaDoc key,
63          Serializable JavaDoc value, boolean locallyModified);
64       /**
65        * Called whenever a key has been removed from a category the called object had
66        * subscribed in.
67        * @param category The category under which a key has been removed
68        * @param key The key that has been removed
69        * @param previousContent The previous content of the key that has been removed
70        * @param locallyModified Whether the removal was made from this node
71        */
72       public void keyHasBeenRemoved (String JavaDoc category, String JavaDoc key,
73          Serializable JavaDoc previousContent, boolean locallyModified);
74    }
75
76    /** A generalization of the DSListener that supports the Serializable key
77     * type. When a particular key in a category of the DistributedState service
78     * gets modified, all listeners will be notified of DS changes for that
79     * category.
80     */
81    public interface DSListenerEx
82    {
83       /**
84        * Called whenever a key has been added or modified in the category the called object
85        * has subscribed in.
86        * @param category The category of the modified/added entry
87        * @param key The key that has been added or had its value modified
88        * @param value The new value of the key
89        * @param locallyModified Whether the change was made from this node
90        */
91       public void valueHasChanged (String JavaDoc category, Serializable JavaDoc key,
92          Serializable JavaDoc value, boolean locallyModified);
93       /**
94        * Called whenever a key has been removed from a category the called object had
95        * subscribed in.
96        * @param category The category under which a key has been removed
97        * @param key The key that has been removed
98        * @param previousContent The previous content of the key that has been removed
99        * @param locallyModified Whether the removal was made from this node
100        */
101       public void keyHasBeenRemoved (String JavaDoc category, Serializable JavaDoc key,
102          Serializable JavaDoc previousContent, boolean locallyModified);
103    }
104
105    /**
106     * Subscribes to receive {@link DistributedState.DSListenerEx} events
107     * @param category Name of the private-space to watch for
108     * @param subscriber Object that will receive callbacks.
109     */
110    public void registerDSListenerEx (String JavaDoc category, DSListenerEx subscriber);
111    /**
112     * Unsubscribes from {@link DistributedState.DSListenerEx} events
113     * @param category Name of the private-space dictionary currently observed
114     * @param subscriber Object currently observing this category
115     */
116    public void unregisterDSListenerEx (String JavaDoc category, DSListenerEx subscriber);
117
118    /**
119     * Subscribes to receive {@link DistributedState.DSListener} events
120     * @param category Name of the private-space to watch for
121     * @param subscriber Object that will receive callbacks.
122     */
123    public void registerDSListener (String JavaDoc category, DSListener subscriber);
124    /**
125     * Unsubscribes from {@link DistributedState.DSListener} events
126     * @param category Name of the private-space dictionary currently observed
127     * @param subscriber Object currently observing this category
128     */
129    public void unregisterDSListener (String JavaDoc category, DSListener subscriber);
130
131    // State binding methods
132 //
133 /**
134     * Associates a value to a key in a specific category
135     * @param category Name of the private naming-space
136     * @param key Name of the data to set
137     * @param value Value of the data to set
138     * @throws Exception If a network exception occurs
139     */
140    public void set (String JavaDoc category, Serializable JavaDoc key, Serializable JavaDoc value)
141       throws Exception JavaDoc;
142
143    /**
144     * Same as set(String, String) but caller can choose if the call is made
145     * synchronously or asynchronously. By default, calls are asynchronous.
146     * @param category Name of the private naming-space
147     * @param key Name of the data to set
148     * @param value Value of the data to set
149     * @param asynchronousCall True if the call should be asynchronous
150     * @throws Exception If a network exception occurs
151     */
152    public void set (String JavaDoc category, Serializable JavaDoc key, Serializable JavaDoc value,
153       boolean asynchronousCall) throws Exception JavaDoc;
154
155    /**
156     * Read in a value associated to a key in the given category. Read is performed locally.
157     * @param category Name of the private naming-space
158     * @param key The key of the value to read
159     * @return The value of the key in the given category
160     */
161    public Serializable JavaDoc get (String JavaDoc category, Serializable JavaDoc key);
162    
163    /**
164     * Return a list of all categories. Call managed locally: no network access.
165     * @return A collection of String representing the existing categories in the DS service.
166     */
167    public Collection JavaDoc getAllCategories ();
168    
169    /**
170     * Return a list of all keys in a category. Call managed locally: no network access.
171     * @param category The category under which to look for keys
172     * @return A collection of all keys in the give category
173     */
174    public Collection JavaDoc getAllKeys (String JavaDoc category);
175
176    /**
177     * Return a list of all values in a category. Call managed locally: no network access.
178     * @param category The category name under which to look for values
179     * @return A collection of all values in the give category
180     */
181    public Collection JavaDoc getAllValues (String JavaDoc category);
182
183    /**
184     * Remove the key from the ReplicationService in the given category
185     * @param category Name of the category
186     * @param key Key to be removed
187     * @return The value of the removed key
188     * @throws Exception if a network exception occurs while removing the entry.
189     */
190    public Serializable JavaDoc remove (String JavaDoc category, Serializable JavaDoc key) throws Exception JavaDoc;
191    
192    /**
193     * Same as remove(String, String) but caller can choose if the call is made
194     * synchronously or asynchronously. By default, calls are asynchronous.
195     * @param category Name of the category
196     * @param key Key to be removed
197     * @param asynchronousCall True if the call should be asynchronous
198     * @return The value of the removed key
199     * @throws Exception if a network exception occurs while removing the entry.
200     */
201    public Serializable JavaDoc remove (String JavaDoc category, Serializable JavaDoc key,
202       boolean asynchronousCall) throws Exception JavaDoc;
203 }
204
Popular Tags