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.rmi.AccessException;
22  import java.rmi.NotBoundException;
23  import java.rmi.RemoteException;
24  
25  import jgroup.core.IID;
26  import jgroup.core.JgroupException;
27  import jgroup.core.Layer;
28  
29  /**
30   *  This interface is used by servers to bind and unbind their reference
31   *  with a specified name from the dependable registry.  That is the name
32   *  to server reference bindings setup through this interface will be
33   *  stored in the dependable registry.  This interface is accessed by
34   *  server objects (and layers) through the group manager.
35   *
36   *  @author Hein Meling
37   *  @since Jgroup 2.2
38   */
39  public interface RegistryService
40    extends Layer
41  {
42  
43    /**
44     *  The default lease time used by the dependable registry (milliseconds)
45     *  when clearing out expired leases.  This assumes that the
46     *  <code>LeaseLayer</code> is configured in the application layer stack;
47     *  otherwise lease expiration checks in the dependable registry is disabled.
48     *  Changes to the lease time should be configured in the
49     *  <code>applications.xml</code> configuration file.
50     *
51     *  @see jgroup.relacs.gm.LeaseService#DEFAULT_REFRESH_RATE
52     */
53    public static final int DEFAULT_LEASE_TIME = 60000;
54  
55    /**
56     *  Bind the server associated with the <code>RegistryLayer</code>
57     *  to the object group associated with the name obtained from the
58     *  <code>application.xml</code> file in the dependable registry
59     *  running in the same distributed system as this group manager.
60     *
61     *  @return 
62     *    A binding identifier <code>IID</code> that can be used to
63     *    remove this server binding from the registry.
64     *
65     *  @exception RemoteException
66     *    Raised when the remote operation failed.
67     *  @exception AccessException
68     *    Raised when this operation is not permitted.
69     *  @exception JgroupException
70     *    Raised in the event of a group communication failure.
71     */
72    public IID bind()
73      throws RemoteException, JgroupException;
74  
75    /**
76     *  Bind the given server to the object group associated with the
77     *  name obtained from the <code>application.xml</code> file in the
78     *  dependable registry running in the same distributed system as
79     *  this group manager.
80     *
81     *  @param server
82     *    The server in the object group to associated with the given name.
83     *  @return 
84     *    A binding identifier <code>IID</code> that can be used to
85     *    remove this server binding from the registry.
86     *
87     *  @exception RemoteException
88     *    Raised when the remote operation failed.
89     *  @exception AccessException
90     *    Raised when this operation is not permitted.
91     *  @exception JgroupException
92     *    Raised in the event of a group communication failure.
93     */
94    public IID bind(Object server)
95      throws RemoteException, JgroupException;
96  
97    /**
98     *  Bind the given server to the object group associated with the
99     *  name in the dependable registry running in the same distributed
100    *  system as this group manager.
101    *
102    *  @param name
103    *    The name associated with the object group.
104    *  @param server
105    *    The server in the object group to associated with the given name.
106    *  @return 
107    *    A binding identifier <code>IID</code> that can be used to
108    *    remove this server binding from the registry.
109    *
110    *  @exception RemoteException
111    *    Raised when the remote operation failed.
112    *  @exception AccessException
113    *    Raised when this operation is not permitted.
114    *  @exception JgroupException
115    *    Raised in the event of a group communication failure.
116    */
117   public IID bind(String name, Object server)
118     throws RemoteException, JgroupException;
119 
120   /**
121    *  Bind the given server to the object group associated with the
122    *  specified name in the specified dependable registry.
123    *
124    *  @param name
125    *    The name associated with the object group.
126    *  @param server
127    *    The server in the object group to associated with the given name.
128    *  @param registry
129    *    The dependable registry in which to bind the given server.
130    *  @return 
131    *    A binding identifier <code>IID</code> that can be used to
132    *    remove this server binding from the registry.
133    *
134    *  @exception RemoteException
135    *    Raised when the remote operation failed.
136    *  @exception AccessException
137    *    Raised when this operation is not permitted.
138    *  @exception JgroupException
139    *    Raised in the event of a group communication failure.
140    */
141   public IID bind(String name, Object server, DependableRegistry registry)
142     throws RemoteException, JgroupException;
143 
144   /**
145    *  Unbind the reference associated with the <code>RegistryLayer</code>
146    *  from the dependable registry running in the same distributed system
147    *  as this group manager.
148    *
149    *  @exception RemoteException
150    *    Raised when the remote operation failed.
151    *  @exception NotBoundException
152    *    Raised the given binding identifier was not in the dependable registry.
153    *  @exception AccessException
154    *    Raised when this operation is not permitted.
155    *  @exception JgroupException
156    *    Raised in the event of a group communication failure.
157    */
158   public void unbind()
159     throws RemoteException, NotBoundException, JgroupException;
160 
161   /**
162    *  Unbind the reference associated with the specified binding
163    *  identifier from the dependable registry running in the same
164    *  distributed system as this group manager.
165    *
166    *  @param bindId
167    *    The binding identifier to be removed from the dependable registry.
168    * 
169    *  @exception RemoteException
170    *    Raised when the remote operation failed.
171    *  @exception NotBoundException
172    *    Raised the given binding identifier was not in the dependable registry.
173    *  @exception AccessException
174    *    Raised when this operation is not permitted.
175    *  @exception JgroupException
176    *    Raised in the event of a group communication failure.
177    */
178   public void unbind(IID bindId)
179     throws RemoteException, NotBoundException, JgroupException;
180 
181   /**
182    *  Unbind the reference associated with the specified binding
183    *  identifier from the specified dependable registry.
184    *
185    *  @param bindId
186    *    The binding identifier to be removed from the dependable registry.
187    *  @param registry
188    *    The dependable registry from which to unbind the given binding.
189    *
190    *  @exception RemoteException
191    *    Raised when the remote operation failed.
192    *  @exception NotBoundException
193    *    Raised the given binding identifier was not in the dependable registry.
194    *  @exception AccessException
195    *    Raised when this operation is not permitted.
196    *  @exception JgroupException
197    *    Raised in the event of a group communication failure.
198    */
199   public void unbind(IID bindId, DependableRegistry registry)
200     throws RemoteException, NotBoundException;
201 
202   /**
203    *  Refresh the lease for the local server.
204    * 
205    *  @exception RemoteException
206    *    Raised when the remote operation failed.
207    *  @exception JgroupException
208    *    Raised in the event of a group communication failure.
209    */
210   public void refreshLease()
211     throws RemoteException, JgroupException;
212 
213   /**
214    *  Returns the local invocation identifier bound to the dependable registry.
215    *  This can be used to <code>unbind()</code> the associated server from
216    *  the dependable registry.
217    *
218    *  @return
219    *    The local invocation identifier bound to the depedable registry.
220    *  @throws NullPointerException
221    *    Raised if the replica is not yet bound to the dependable registry.
222    */
223   public IID getIID()
224     throws NullPointerException;
225 
226 } // END RegistryService