KickJava   Java API By Example, From Geeks To Geeks.

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


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.Vector JavaDoc;
26 import java.util.ArrayList JavaDoc;
27
28 /**
29  *
30  * @author <a HREF="mailto:bill@burkecentral.com">Bill Burke</a>.
31  * @author <a HREF="mailto:sacha.labourey@cogito-info.ch">Sacha Labourey</a>.
32  * @version $Revision: 40382 $
33  *
34  * <p><b>Revisions:</b><br>
35  * <p><b>28.07.2002 - Sacha Labourey:</b>
36  * <ul>
37  * <li> Added network-partition merge callback for listeners</li>
38  * </ul>
39  */

40
41 public interface HAPartition
42 {
43    // *******************************
44
// *******************************
45
// Partition information accessors
46
// *******************************
47
// *******************************
48
//
49
/**
50     * Return the name of this node in the current partition. The name is
51     * dynamically determined by the partition. The name will be the String
52     * returned by <code>getClusterNode().getName()</code>.
53     *
54     * @return The node name
55     *
56     * @see #getClusterNode()
57     */

58    public String JavaDoc getNodeName();
59    /**
60     * The name of the partition. Either set when creating the partition
61     * (MBEAN definition) or uses the default name
62     * @return Name of the current partition
63     */

64    public String JavaDoc getPartitionName();
65
66    /**
67     * Accessor to the DRM that is linked to this partition.
68     * @return the DRM linked to this partition
69     */

70    public DistributedReplicantManager getDistributedReplicantManager();
71    /**
72     * Accessor the the DistributedState (DS) that is linked to this partition.
73     * @return the DistributedState service
74     */

75    public DistributedState getDistributedStateService ();
76
77    // ***************************
78
// ***************************
79
// RPC multicast communication
80
// ***************************
81
// ***************************
82
//
83
/**
84     * The partition receives RPC calls from other nodes in the cluster and demultiplex
85     * them, according to a service name, to a particular service. Consequently, each
86     * service must first subscribe with a particular service name in the partition. The subscriber
87     * does not need to implement any specific interface: the call is handled
88     * dynamically through reflection.
89     * @param serviceName Name of the subscribing service (demultiplexing key)
90     * @param handler object to be called when receiving a RPC for its key.
91     */

92    public void registerRPCHandler(String JavaDoc serviceName, Object JavaDoc handler);
93    /**
94     * Unregister the service from the partition
95     * @param serviceName Name of the service key (on which the demultiplexing occurs)
96     * @param subscriber The target object that unsubscribes
97     */

98    public void unregisterRPCHandler(String JavaDoc serviceName, Object JavaDoc subscriber);
99
100    // Called only on all members of this partition on all nodes
101
//
102
/**
103     * Invoke a synchronous RPC call on all nodes of the partition/cluster
104     * @param serviceName Name of the target service name on which calls are de-multiplexed
105     * @param methodName name of the Java method to be called on remote services
106     * @param args array of Java Object representing the set of parameters to be
107     * given to the remote method
108     * @param types The types of the parameters
109     * @param excludeSelf indicates if the RPC must also be made on the current
110     * node of the partition or only on remote nodes
111     * @throws Exception Throws if a communication exception occurs
112     * @return an array of answers from remote nodes
113     */

114    public ArrayList JavaDoc callMethodOnCluster(String JavaDoc serviceName, String JavaDoc methodName,
115          Object JavaDoc[] args, Class JavaDoc[] types, boolean excludeSelf) throws Exception JavaDoc;
116
117
118    /**
119     *
120     * @param serviceName
121     * @param methodName
122     * @param args
123     * @param excludeSelf
124     * @return
125     * @throws Exception
126     * @deprecated Use {@link #callMethodOnCluster(String, String, Object[], Class[], boolean)} instead
127     */

128    public ArrayList JavaDoc callMethodOnCluster(String JavaDoc serviceName, String JavaDoc methodName,
129          Object JavaDoc[] args, boolean excludeSelf) throws Exception JavaDoc;
130
131    /**
132     * Invoke a asynchronous RPC call on all nodes of the partition/cluster. The
133     * call will return immediately and will not wait that the nodes answer. Thus
134     * no answer is available.
135     * @param serviceName Name of the target service name on which calls are de-multiplexed
136     * @param methodName name of the Java method to be called on remote services
137     * @param args array of Java Object representing the set of parameters to be
138     * given to the remote method
139     * @param types The types of the parameters
140     * @param excludeSelf indicates if the RPC must also be made on the current
141     * node of the partition or only on remote nodes
142     * @throws Exception Throws if a communication exception occurs
143     */

144    public void callAsynchMethodOnCluster (String JavaDoc serviceName, String JavaDoc methodName,
145          Object JavaDoc[] args, Class JavaDoc[] types, boolean excludeSelf) throws Exception JavaDoc;
146
147    /**
148     * Calls method on Cluster coordinator node only. The cluster coordinator node is the first node to join the
149     * cluster or the first node in the current cluster view.
150     * @param serviceName Name of the target service name on which calls are de-multiplexed
151     * @param methodName name of the Java method to be called on remote services
152     * @param args array of Java Object representing the set of parameters to be
153     * given to the remote method
154     * @param types The types of the parameters
155     * node of the partition or only on remote nodes
156     * @param excludeSelf indicates if the RPC will be made on the current node even if the current node
157     * is the coordinator
158     * @throws Exception Throws if a communication exception occurs
159     * @return an array of answers from remote nodes
160     */

161       public ArrayList JavaDoc callMethodOnCoordinatorNode(String JavaDoc serviceName, String JavaDoc methodName,
162              Object JavaDoc[] args, Class JavaDoc[] types, boolean excludeSelf) throws Exception JavaDoc;
163
164    
165    /**
166     *
167     * @param serviceName
168     * @param methodName
169     * @param args
170     * @param excludeSelf
171     * @throws Exception
172     * @deprecated Use {@link #callAsynchMethodOnCluster(String, String, Object[], Class[], boolean)} instead
173     */

174    public void callAsynchMethodOnCluster (String JavaDoc serviceName, String JavaDoc methodName,
175          Object JavaDoc[] args, boolean excludeSelf) throws Exception JavaDoc;
176
177
178    // *************************
179
// *************************
180
// State transfer management
181
// *************************
182
// *************************
183
//
184

185    /**
186     * State management is higly important for clustered services. Consequently, services that wish to manage their state
187     * need to subscribe to state transfer events. When their node start, a state is pushed from another node to them.
188     * When another node starts, they may be asked to provide such a state to initialise the newly started node.
189     */

190    public interface HAPartitionStateTransfer
191    {
192       /**
193        * Called when a new node need to be initialized. This is called on any existing node to determine a current state for this service.
194        * @return A serializable representation of the state
195        */

196       public Serializable JavaDoc getCurrentState ();
197       /**
198        * This callback method is called when a new service starts on a new node: the state that it should hold is transfered to it through this callback
199        * @param newState The serialized representation of the state of the new service.
200        */

201       public void setCurrentState(Serializable JavaDoc newState);
202    }
203    
204    /**
205     * Register a service that will participate in state transfer protocol and receive callbacks
206     * @param serviceName Name of the service that subscribes for state stransfer events. This name must be identical for all identical services in the cluster.
207     * @param subscriber Object implementing {@link HAPartitionStateTransfer} and providing or receiving state transfer callbacks
208     */

209    public void subscribeToStateTransferEvents (String JavaDoc serviceName, HAPartition.HAPartitionStateTransfer subscriber);
210    /**
211     * Unregister a service from state transfer callbacks.
212     * @param serviceName Name of the service that participates in the state transfer protocol
213     * @param subscriber Service implementing the state transfer callback methods
214     */

215    public void unsubscribeFromStateTransferEvents (String JavaDoc serviceName, HAPartition.HAPartitionStateTransfer subscriber);
216
217    // *************************
218
// *************************
219
// Group Membership listeners
220
// *************************
221
// *************************
222
//
223
/**
224     * When a new node joins the cluster or an existing node leaves the cluster
225     * (or simply dies), membership events are raised.
226     *
227     */

228    public interface HAMembershipListener
229    {
230       /** Called when a new partition topology occurs. This callback is made
231        * using the JG protocol handler thread and so you cannot execute new
232        * cluster calls that need this thread. If you need to do that implement
233        * the aynchronous version of the listener interface.
234        *
235        * @param deadMembers A list of nodes that have died since the previous view
236        * @param newMembers A list of nodes that have joined the partition since the previous view
237        * @param allMembers A list of nodes that built the current view
238        */

239       public void membershipChanged(Vector JavaDoc deadMembers, Vector JavaDoc newMembers, Vector JavaDoc allMembers);
240    }
241
242    /** A tagging interface for HAMembershipListener callbacks that will
243     * be performed in a thread seperate from the JG protocl handler thread.
244     * The ordering of view changes is preserved, but listeners are free to
245     * execute cluster calls.
246     */

247    public interface AsynchHAMembershipListener extends HAMembershipListener
248    {
249       // Nothing new
250
}
251
252    public interface HAMembershipExtendedListener extends HAPartition.HAMembershipListener
253    {
254       /** Extends HAMembershipListener to receive a specific callback when a
255        * network-partition merge occurs. The same restriction on interaction
256        * with the JG protocol stack applies.
257        *
258        * @param deadMembers A list of nodes that have died since the previous view
259        * @param newMembers A list of nodes that have joined the partition since the previous view
260        * @param allMembers A list of nodes that built the current view
261        * @param originatingGroups A list of list of nodes that were previously partionned and that are now merged
262        */

263       public void membershipChangedDuringMerge(Vector JavaDoc deadMembers, Vector JavaDoc newMembers,
264             Vector JavaDoc allMembers, Vector JavaDoc originatingGroups);
265    }
266
267    /** A tagging interface for HAMembershipExtendedListener callbacks that will
268     * be performed in a thread seperate from the JG protocl handler thread.
269     * The ordering of view changes is preserved, but listeners are free to
270     * execute cluster calls.
271     */

272    public interface AsynchHAMembershipExtendedListener extends HAMembershipExtendedListener
273    {
274       // Nothing new
275
}
276
277    /**
278     * Subscribes to receive {@link HAMembershipListener} events.
279     * @param listener The membership listener object
280     */

281    public void registerMembershipListener(HAMembershipListener listener);
282    /**
283     * Unsubscribes from receiving {@link HAMembershipListener} events.
284     * @param listener The listener wishing to unsubscribe
285     */

286    public void unregisterMembershipListener(HAMembershipListener listener);
287    /**
288     * Returns whether this partition will synchronously notify any
289     * HAMembershipListeners of membership changes using the calling thread
290     * from the underlying <code>ClusterPartition</code>.
291     *
292     * @return <code>true</code> if registered listeners that don't implement
293     * <code>AsynchHAMembershipExtendedListener</code> or
294     * <code>AsynchHAMembershipListener</code> will be notified
295     * synchronously of membership changes; <code>false</code> if
296     * those listeners will be notified asynchronously. Default
297     * is <code>false</code>.
298     */

299    public boolean getAllowSynchronousMembershipNotifications();
300    /**
301     * Sets whether this partition will synchronously notify any
302     * HAMembershipListeners of membership changes using the calling thread
303     * from the underlying <code>ClusterPartition</code>.
304     *
305     * @param allowSync <code>true</code> if registered listeners that don't
306     * implement <code>AsynchHAMembershipExtendedListener</code> or
307     * <code>AsynchHAMembershipListener</code> should be notified
308     * synchronously of membership changes; <code>false</code> if
309     * those listeners can be notified asynchronously. Default
310     * is <code>false</code>.
311     */

312    public void setAllowSynchronousMembershipNotifications(boolean allowSync);
313
314    /**
315     * Each time the partition topology changes, a new view is computed. A view is a list of members,
316     * the first member being the coordinator of the view. Each view also has a distinct identifier.
317     * @return The identifier of the current view
318     */

319    public long getCurrentViewId();
320    /**
321     * Return the list of member nodes that built the current view i.e. the current partition.
322     * @return An array of Strings containing the node names
323     */

324    public Vector JavaDoc getCurrentView ();
325
326    /**
327     * Return the member nodes that built the current view i.e. the current partition.
328     * @return An array of ClusterNode listing the current members of the partitionn.
329     * This array will be in the same order in all nodes in the cluster that
330     * have received the current view.
331     */

332    public ClusterNode[] getClusterNodes ();
333
334    /**
335     * Return member node for the current cluster node.
336     * @return ClusterNode containing the current node name
337     */

338    public ClusterNode getClusterNode ();
339 }
Popular Tags