1 /*
2 * Copyright (c) 1998-2002 The Jgroup Team.
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License version 2 as
6 * published by the Free Software Foundation.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU Lesser General Public License for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
16 *
17 */
18
19 package jgroup.core.arm;
20
21 import java.rmi.Remote;
22 import java.rmi.RemoteException;
23
24 import jgroup.core.ConfigurationException;
25 import jgroup.core.ExternalGMIListener;
26 import jgroup.relacs.config.AppConfig;
27
28
29 /**
30 * The <code>ReplicationManager</code> interface describes the methods
31 * that a management client can invoke on the replication manager to
32 * create and remove object groups within the distributed system.
33 *
34 * Note that all methods in this interface has no declared invocation
35 * semantics. The invocation semantics depends on the implementation
36 * of this interface, and the <code>ReplicaManagerImpl</code> class
37 * provides one such implementation in which all methods are defined
38 * to have <code>@Multicast</code> invocation semantics. However, in
39 * this implementation of this interface only the <i>leader</i> replica
40 * actually perform the create and remove replica operations on the
41 * execution service, while the <i>follower</i> replicas just keeps
42 * track of the state by updating its own group table.
43 *
44 * The above semantics require the replica distribution scheme to
45 * perform deterministic replica placements.
46 *
47 * The <code>ReplicationManager</code> interface also describe the
48 * methods that ARM components, such as the <code>RecoveryLayer</code>
49 * and <code>ExecDaemon</code> can invoke on the replication manager
50 * to notify it of certain events.
51 *
52 * @author Hein Meling
53 * @since Jgroup 1.2
54 */
55 public interface ReplicationManager
56 extends ExternalGMIListener
57 {
58
59 ////////////////////////////////////////////////////////////////////////////////////////////
60 // Event notification method (notifications for the Replication Manager)
61 ////////////////////////////////////////////////////////////////////////////////////////////
62
63 /**
64 * The <code>notifyEvent</code> method is used by components external
65 * to the replication manager to notify it of important events, such
66 * as the presence of a new host (<code>ExecDaemon</code>) or view
67 * change events from the <code>RecoveryLayer</code>. <p>
68 *
69 * The method takes arbitrary event types as long as they implement
70 * the interface <code>ARMEvent</code>.
71 *
72 * @param event
73 * An event notification for the replication manager.
74 * @exception RemoteException
75 * Raised if the remote operation failed.
76 */
77 public void notifyEvent(ARMEvent event)
78 throws RemoteException, Exception;
79
80
81 ////////////////////////////////////////////////////////////////////////////////////////////
82 // Methods for group management
83 ////////////////////////////////////////////////////////////////////////////////////////////
84
85 /**
86 * Create a group for the specified application, with the
87 * applications required redundancy.
88 *
89 * @param app
90 * The application details required to create a group for it.
91 * @return
92 * The group identifier.
93 * @exception RemoteException
94 * Raised if there was communication problems; only when invoked remotely.
95 * @exception ConfigurationException
96 * Raised if the specified application recovery strategy could not be initialized.
97 * @exception RedundancyException
98 * Raised if the specified redundancy could not be satisfied.
99 * @exception GroupExistsException
100 * Raised if the specified group already exists.
101 */
102 public int createGroup(AppConfig app)
103 throws RemoteException, RedundancyException, GroupExistsException;
104
105
106 /**
107 * Remove the group for the given application.
108 *
109 * @param app
110 * The application group to remove.
111 * @exception RemoteException
112 * Raised if there was communication problems; only when invoked remotely.
113 * @exception UnknownGroupException
114 * Raised if the specified application has no group in the system.
115 */
116 public void removeGroup(AppConfig app)
117 throws RemoteException, UnknownGroupException;
118
119
120 /**
121 * Update the replication policy for the group for the given application.
122 *
123 * @param app
124 * The application group to remove.
125 * @exception RemoteException
126 * Raised if there was communication problems; only when invoked remotely.
127 * @exception UnknownGroupException
128 * Raised if the specified application has no group in the system.
129 */
130 public void updateGroup(AppConfig app)
131 throws RemoteException, UnknownGroupException;
132
133
134 /**
135 * Register to receive notifications for the given group.
136 *
137 * @param callback
138 * The callback server (typically a management client)
139 * @param group
140 * The group for which notifications are desired
141 * @exception RemoteException
142 * Raised if there was communication problems; only when invoked remotely.
143 * @exception UnknownGroupException
144 * Raised if the specified application has no group in the system.
145 */
146 public void subscribe(ManagementCallback callback, int group)
147 throws RemoteException, UnknownGroupException;
148
149
150 /**
151 * Unregister to receive notifications for the given group.
152 *
153 * @param group
154 * The group for which notifications are no longer desired
155 * @exception RemoteException
156 * Raised if there was communication problems; only when invoked remotely.
157 * @exception UnknownGroupException
158 * Raised if the specified application has no group in the system.
159 */
160 public void unsubscribe(int group)
161 throws RemoteException, UnknownGroupException;
162
163
164 ////////////////////////////////////////////////////////////////////////////////////////////
165 // Callback interface for group management
166 ////////////////////////////////////////////////////////////////////////////////////////////
167
168 /**
169 * Callback interface for monitoring installed applications.
170 */
171 public interface ManagementCallback
172 extends Remote
173 {
174
175 /**
176 * Notify the management application that a new view has been
177 * installed.
178 */
179 public void notifyEvent(ARMEvent event)
180 throws RemoteException;
181
182 }
183
184 } // END ReplicationManager