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.registry;
20
21 import java.io.Externalizable;
22 import java.lang.reflect.InvocationHandler;
23 import java.rmi.AccessException;
24 import java.rmi.NotBoundException;
25 import java.rmi.RemoteException;
26 import java.util.Iterator;
27
28 import jgroup.core.IID;
29
30 /**
31 * For obtaining references to remote objects, RMI includes a registry service,
32 * that provides methods for storing and retrieving remote object references.
33 * Each registry object acts independently and maintains a different set
34 * of bindings (name, remote object), thus constituting a single point of
35 * failure. Furthermore, a registry object running on a certain host can be
36 * used to register only remote objects running on the same host; thus, in
37 * order to obtain a stub for a remote object, a client need to be aware of
38 * its location.
39 * <p>
40 * The registry implementation included with Jgroup has several advantages
41 * over the standard Java RMI registry. First, it enables a set of replicated
42 * remote objects to register themselves under the same name. This set
43 * forms a remote object group that can be retrieved as a single entity.
44 * All the Jgroup registry objects running in a distributed system
45 * cooperate in order to maintain a replicated database of bindings and
46 * offer a reliable and high-available repository facility. Clients no
47 * longer need to be aware of the location of a service: they can simply
48 * access the group of registry replicas and obtain a stub for every
49 * service registered in the distributed system. A stub for the registry
50 * group is obtained through the <code>RegistryFactory.getRegistry</code>
51 * methods.
52 * <p>
53 * A distributed system can be designed by including a certain number of registry
54 * replicas running on different hosts and possibly on distinct portions of the
55 * communication network. Client access these replicas through standard
56 * RMI interactions as if they were a single registry, and are guaranteed
57 * that their invocation will successfully terminate, provided that at
58 * least one operational replica is running in their partition.
59 * <p>
60 * During a partitioning, the Jgroup registry presents a partitioned
61 * behavior reflecting the current failure scenario. The registration
62 * of a remote object inside a partition will not affect the registry
63 * replicas not contained in that partition, while a retrieval operation
64 * will not success if the service we are looking for has been registered
65 * in another partition. Nevertheless, the replicas contained in a
66 * partition consistently maintain the same set of bindings and act as
67 * a single entity; moreover, the disappearance of the partitioning
68 * causes the execution of a reconciliation protocol in order to
69 * re-establish a consistent set of bindings among the replicas that
70 * belonged to different partitions. It is important to note that this
71 * behavior is perfectly reasonable for a partitionable distributed
72 * system, since clients asking for remote services are interested only
73 * in servers running in their current partitions.
74 * <p>
75 * The <code> DependableRegistry</code> interface describes the methods
76 * of a dependable registry that can be remotely invoked.
77 * To create a registry that runs in an application, use one of the
78 * <code>RegistryFactory.createRegistry</code> methods. To obtain
79 * a reference to a remote object registry, use one of the
80 * <code>RegistryFactory.getRegistry</code> methods.
81 *
82 * @author Alberto Montresor
83 * @author Hein Meling
84 * @since Jgroup 0.3
85 */
86 public interface DependableRegistry
87 extends LookupRegistry
88 {
89
90 ////////////////////////////////////////////////////////////////////////////////////////////
91 // Constants
92 ////////////////////////////////////////////////////////////////////////////////////////////
93
94 /**
95 * Service name used to register each dependable registry replica in
96 * the local registry.
97 */
98 public static final String DEPENDABLE_REGISTRY_NAME = "DependableRegistry";
99
100
101 ////////////////////////////////////////////////////////////////////////////////////////////
102 // Nested interface
103 ////////////////////////////////////////////////////////////////////////////////////////////
104
105 /**
106 * This interface must be implemented by all types that needs
107 * to be stored in a dependable registry.
108 */
109 public static interface RegistryEntry
110 extends Externalizable
111 {
112
113 /**
114 * Returns the entry type. An <code>DependableRegistry</code>
115 * implementation must check the returned value to see if it can
116 * handle it.
117 *
118 * @return a <code>java.lang.String</code> representing the entry type.
119 */
120 public String getType();
121
122 /**
123 * Returns an invocation handler of the given RegistryEntry type,
124 * for the given serviceName. The handler will include all entries
125 * enumerated from the provided iterator.
126 */
127 public InvocationHandler createInvocationHandler(String serviceName, Iterator entries)
128 throws RemoteException;
129
130 } // END of RegistryEntry
131
132
133 ////////////////////////////////////////////////////////////////////////////////////////////
134 // Methods
135 ////////////////////////////////////////////////////////////////////////////////////////////
136
137 /**
138 * Add a replicated member object to the remote object group associated with
139 * the specified name in the registry.
140 *
141 * @param name
142 * The name associated with the remote object group
143 * @param entry
144 * The RegistryEntry type associated with the member object implementation
145 * @param serverType
146 * The class object of the member object implementation
147 * @return
148 * A <code>IID</code> identifier that can be used to remove a
149 * replicated remote object from the binding set.
150 *
151 * @exception RemoteException Raised when remote operation failed.
152 * @exception AccessException Raised when this operation is not permitted.
153 */
154 public IID bind(String name, RegistryEntry entry, Class serverType)
155 throws RemoteException, AccessException;
156
157 /**
158 * Add a replicated member object to the remote object group associated with
159 * the specified name in the registry.
160 *
161 * @param name
162 * The name associated with the remote object group
163 * @param entry
164 * The RegistryEntry type associated with the member object implementation
165 * @param serverType
166 * The class object of the member object implementation
167 * @param leaseTime
168 * The lease time for the service
169 * @return
170 * A <code>IID</code> identifier that can be used to remove a
171 * replicated remote object from the binding set.
172 *
173 * @exception RemoteException Raised when remote operation failed.
174 * @exception AccessException Raised when this operation is not permitted.
175 */
176 public IID bind(String name, RegistryEntry entry, Class serverType, long leaseTime)
177 throws RemoteException, AccessException;
178
179 /**
180 * Remove a replicated remote object identified by the <code>IID</code>
181 * object obtained when the replica has been registered.
182 *
183 * @param bid the binding identifier obtained when the replica has
184 * been registered
185 *
186 * @exception RemoteException If remote operation failed.
187 * @exception NotBoundException if there is no object with this name in the
188 * registry.
189 * @exception AccessException If this operation is not permitted.
190 */
191 public void unbind(IID bid)
192 throws RemoteException, NotBoundException, AccessException;
193
194 /**
195 * Update the timestamp (lease time) for the server associated with the given
196 * binding identifier (<code>IID</code>). This method is used by the server-side
197 * <code>LeaseLayer</code> and is invoked through the <code>RegistryLayer</code>.
198 *
199 * @param iid
200 * The <code>iid</code> of the server whose lease to refresh.
201 *
202 * @exception RemoteException If remote operation failed.
203 * @exception NotBoundException if there is no object in the registry matching
204 * the given <code>IID</code>.
205 * @exception AccessException If this operation is not permitted.
206 */
207 public void refresh(IID iid)
208 throws RemoteException, AccessException, NotBoundException;
209
210 } // END DependableRegistry