View Javadoc

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