KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > rmi > registry > Registry


1 /*
2  * @(#)Registry.java 1.18 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7 package java.rmi.registry;
8
9 import java.rmi.AccessException JavaDoc;
10 import java.rmi.AlreadyBoundException JavaDoc;
11 import java.rmi.NotBoundException JavaDoc;
12 import java.rmi.Remote JavaDoc;
13 import java.rmi.RemoteException JavaDoc;
14
15 /**
16  * <code>Registry</code> is a remote interface to a simple remote
17  * object registry that provides methods for storing and retrieving
18  * remote object references bound with arbitrary string names. The
19  * <code>bind</code>, <code>unbind</code>, and <code>rebind</code>
20  * methods are used to alter the name bindings in the registry, and
21  * the <code>lookup</code> and <code>list</code> methods are used to
22  * query the current name bindings.
23  *
24  * <p>In its typical usage, a <code>Registry</code> enables RMI client
25  * bootstrapping: it provides a simple means for a client to obtain an
26  * initial reference to a remote object. Therefore, a registry's
27  * remote object implementation is typically exported with a
28  * well-known address, such as with a well-known {@link
29  * java.rmi.server.ObjID#REGISTRY_ID ObjID} and TCP port number
30  * (default is {@link #REGISTRY_PORT 1099}).
31  *
32  * <p>The {@link LocateRegistry} class provides a programmatic API for
33  * constructing a bootstrap reference to a <code>Registry</code> at a
34  * remote address (see the static <code>getRegistry</code> methods)
35  * and for creating and exporting a <code>Registry</code> in the
36  * current VM on a particular local address (see the static
37  * <code>createRegistry</code> methods).
38  *
39  * <p>A <code>Registry</code> implementation may choose to restrict
40  * access to some or all of its methods (for example, methods that
41  * mutate the registry's bindings may be restricted to calls
42  * originating from the local host). If a <code>Registry</code>
43  * method chooses to deny access for a given invocation, its
44  * implementation may throw {@link java.rmi.AccessException}, which
45  * (because it extends {@link java.rmi.RemoteException}) will be
46  * wrapped in a {@link java.rmi.ServerException} when caught by a
47  * remote client.
48  *
49  * <p>The names used for bindings in a <code>Registry</code> are pure
50  * strings, not parsed. A service which stores its remote reference
51  * in a <code>Registry</code> may wish to use a package name as a
52  * prefix in the name binding to reduce the likelihood of name
53  * collisions in the registry.
54  *
55  * @author Ann Wollrath
56  * @author Peter Jones
57  * @version 1.18, 03/12/19
58  * @since JDK1.1
59  * @see LocateRegistry
60  */

61 public interface Registry extends Remote JavaDoc {
62
63     /** Well known port for registry. */
64     public static final int REGISTRY_PORT = 1099;
65     
66     /**
67      * Returns the remote reference bound to the specified
68      * <code>name</code> in this registry.
69      *
70      * @param name the name for the remote reference to look up
71      *
72      * @return a reference to a remote object
73      *
74      * @throws NotBoundException if <code>name</code> is not currently bound
75      *
76      * @throws RemoteException if remote communication with the
77      * registry failed; if exception is a <code>ServerException</code>
78      * containing an <code>AccessException</code>, then the registry
79      * denies the caller access to perform this operation
80      *
81      * @throws AccessException if this registry is local and it denies
82      * the caller access to perform this operation
83      *
84      * @throws NullPointerException if <code>name</code> is <code>null</code>
85      */

86     public Remote JavaDoc lookup(String JavaDoc name)
87     throws RemoteException JavaDoc, NotBoundException JavaDoc, AccessException JavaDoc;
88
89     /**
90      * Binds a remote reference to the specified <code>name</code> in
91      * this registry.
92      *
93      * @param name the name to associate with the remote reference
94      * @param obj a reference to a remote object (usually a stub)
95      *
96      * @throws AlreadyBoundException if <code>name</code> is already bound
97      *
98      * @throws RemoteException if remote communication with the
99      * registry failed; if exception is a <code>ServerException</code>
100      * containing an <code>AccessException</code>, then the registry
101      * denies the caller access to perform this operation (if
102      * originating from a non-local host, for example)
103      *
104      * @throws AccessException if this registry is local and it denies
105      * the caller access to perform this operation
106      *
107      * @throws NullPointerException if <code>name</code> is
108      * <code>null</code>, or if <code>obj</code> is <code>null</code>
109      */

110     public void bind(String JavaDoc name, Remote JavaDoc obj)
111     throws RemoteException JavaDoc, AlreadyBoundException JavaDoc, AccessException JavaDoc;
112
113     /**
114      * Removes the binding for the specified <code>name</code> in
115      * this registry.
116      *
117      * @param name the name of the binding to remove
118      *
119      * @throws NotBoundException if <code>name</code> is not currently bound
120      *
121      * @throws RemoteException if remote communication with the
122      * registry failed; if exception is a <code>ServerException</code>
123      * containing an <code>AccessException</code>, then the registry
124      * denies the caller access to perform this operation (if
125      * originating from a non-local host, for example)
126      *
127      * @throws AccessException if this registry is local and it denies
128      * the caller access to perform this operation
129      *
130      * @throws NullPointerException if <code>name</code> is <code>null</code>
131      */

132     public void unbind(String JavaDoc name)
133     throws RemoteException JavaDoc, NotBoundException JavaDoc, AccessException JavaDoc;
134
135     /**
136      * Replaces the binding for the specified <code>name</code> in
137      * this registry with the supplied remote reference. If there is
138      * an existing binding for the specified <code>name</code>, it is
139      * discarded.
140      *
141      * @param name the name to associate with the remote reference
142      * @param obj a reference to a remote object (usually a stub)
143      *
144      * @throws RemoteException if remote communication with the
145      * registry failed; if exception is a <code>ServerException</code>
146      * containing an <code>AccessException</code>, then the registry
147      * denies the caller access to perform this operation (if
148      * originating from a non-local host, for example)
149      *
150      * @throws AccessException if this registry is local and it denies
151      * the caller access to perform this operation
152      *
153      * @throws NullPointerException if <code>name</code> is
154      * <code>null</code>, or if <code>obj</code> is <code>null</code>
155      */

156     public void rebind(String JavaDoc name, Remote JavaDoc obj)
157     throws RemoteException JavaDoc, AccessException JavaDoc;
158
159     /**
160      * Returns an array of the names bound in this registry. The
161      * array will contain a snapshot of the names bound in this
162      * registry at the time of the given invocation of this method.
163      *
164      * @return an array of the names bound in this registry
165      *
166      * @throws RemoteException if remote communication with the
167      * registry failed; if exception is a <code>ServerException</code>
168      * containing an <code>AccessException</code>, then the registry
169      * denies the caller access to perform this operation
170      *
171      * @throws AccessException if this registry is local and it denies
172      * the caller access to perform this operation
173      */

174     public String JavaDoc[] list() throws RemoteException JavaDoc, AccessException JavaDoc;
175 }
176
Popular Tags