Naming


1   /*
2    * @(#)Naming.java  1.22 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;
8   
9   import java.rmi.registry.*;
10  import java.net.MalformedURLException  ;
11  import java.net.URI  ;
12  import java.net.URISyntaxException  ;
13  
14  /**
15   * The <code>Naming</code> class provides methods for storing and obtaining
16   * references to remote objects in a remote object registry.  Each method of
17   * the <code>Naming</code> class takes as one of its arguments a name that
18   * is a <code>java.lang.String</code> in URL format (without the
19   * scheme component) of the form:
20   *
21   * <PRE>
22   *    //host:port/name
23   * </PRE>
24   * 
25   * <P>where <code>host</code> is the host (remote or local) where the registry
26   * is located, <code>port</code> is the port number on which the registry
27   * accepts calls, and where <code>name</code> is a simple string uninterpreted
28   * by the registry. Both <code>host</code> and <code>port</code> are optional.
29   * If <code>host</code> is omitted, the host defaults to the local host. If
30   * <code>port</code> is omitted, then the port defaults to 1099, the
31   * "well-known" port that RMI's registry, <code>rmiregistry</code>, uses.
32   *
33   * <P><em>Binding</em> a name for a remote object is associating or
34   * registering a name for a remote object that can be used at a later time to
35   * look up that remote object.  A remote object can be associated with a name
36   * using the <code>Naming</code> class's <code>bind</code> or
37   * <code>rebind</code> methods.
38   *
39   * <P>Once a remote object is registered (bound) with the RMI registry on the
40   * local host, callers on a remote (or local) host can lookup the remote
41   * object by name, obtain its reference, and then invoke remote methods on the
42   * object.  A registry may be shared by all servers running on a host or an
43   * individual server process may create and use its own registry if desired
44   * (see <code>java.rmi.registry.LocateRegistry.createRegistry</code> method
45   * for details).
46   *
47   * @version 1.13, 09/05/99
48   * @author  Ann Wollrath
49   * @author  Roger Riggs
50   * @since   JDK1.1
51   * @see     java.rmi.registry.Registry
52   * @see     java.rmi.registry.LocateRegistry
53   * @see     java.rmi.registry.LocateRegistry#createRegistry(int)
54   */
55  public final class Naming {
56      /**
57       * Disallow anyone from creating one of these
58       */
59      private Naming() {}
60  
61      /**
62       * Returns a reference, a stub, for the remote object associated
63       * with the specified <code>name</code>.
64       *
65       * @param name a name in URL format (without the scheme component) 
66       * @return a reference for a remote object
67       * @exception NotBoundException if name is not currently bound
68       * @exception RemoteException if registry could not be contacted
69       * @exception AccessException if this operation is not permitted
70       * @exception MalformedURLException if the name is not an appropriately
71       *  formatted URL
72       * @since JDK1.1
73       */
74      public static Remote   lookup(String   name)
75      throws NotBoundException  ,
76          java.net.MalformedURLException  ,
77          RemoteException  
78      {
79      ParsedNamingURL parsed = parseURL(name);
80      Registry registry = getRegistry(parsed);
81  
82      if (parsed.name == null)
83          return registry;
84      return registry.lookup(parsed.name);
85      }
86  
87      /**
88       * Binds the specified <code>name</code> to a remote object.
89       *
90       * @param name a name in URL format (without the scheme component) 
91       * @param obj a reference for the remote object (usually a stub)
92       * @exception AlreadyBoundException if name is already bound
93       * @exception MalformedURLException if the name is not an appropriately
94       *  formatted URL
95       * @exception RemoteException if registry could not be contacted
96       * @exception AccessException if this operation is not permitted (if
97       * originating from a non-local host, for example)
98       * @since JDK1.1
99       */
100     public static void bind(String   name, Remote   obj)
101     throws AlreadyBoundException  ,
102         java.net.MalformedURLException  ,
103         RemoteException  
104     {
105     ParsedNamingURL parsed = parseURL(name);
106     Registry registry = getRegistry(parsed);
107 
108     if (obj == null)
109         throw new NullPointerException  ("cannot bind to null");
110 
111     registry.bind(parsed.name, obj);
112     }
113 
114     /**
115      * Destroys the binding for the specified name that is associated
116      * with a remote object.
117      *
118      * @param name a name in URL format (without the scheme component) 
119      * @exception NotBoundException if name is not currently bound
120      * @exception MalformedURLException if the name is not an appropriately
121      *  formatted URL
122      * @exception RemoteException if registry could not be contacted
123      * @exception AccessException if this operation is not permitted (if
124      * originating from a non-local host, for example)
125      * @since JDK1.1
126      */
127     public static void unbind(String   name)
128     throws RemoteException  ,
129         NotBoundException  ,
130         java.net.MalformedURLException  
131     {
132     ParsedNamingURL parsed = parseURL(name);
133     Registry registry = getRegistry(parsed);
134 
135     registry.unbind(parsed.name);
136     }
137 
138     /** 
139      * Rebinds the specified name to a new remote object. Any existing
140      * binding for the name is replaced.
141      *
142      * @param name a name in URL format (without the scheme component)
143      * @param obj new remote object to associate with the name
144      * @exception MalformedURLException if the name is not an appropriately
145      *  formatted URL
146      * @exception RemoteException if registry could not be contacted
147      * @exception AccessException if this operation is not permitted (if
148      * originating from a non-local host, for example)
149      * @since JDK1.1
150      */
151     public static void rebind(String   name, Remote   obj)
152     throws RemoteException  , java.net.MalformedURLException  
153     {
154     ParsedNamingURL parsed = parseURL(name);
155     Registry registry = getRegistry(parsed);
156 
157     if (obj == null)
158         throw new NullPointerException  ("cannot bind to null");
159 
160     registry.rebind(parsed.name, obj);
161     }
162 
163     /**
164      * Returns an array of the names bound in the registry.  The names are
165      * URL-formatted (without the scheme component) strings. The array contains
166      * a snapshot of the names present in the registry at the time of the
167      * call.
168      *
169      * @param   name a registry name in URL format (without the scheme
170      *      component)
171      * @return  an array of names (in the appropriate format) bound
172      *      in the registry
173      * @exception MalformedURLException if the name is not an appropriately
174      *  formatted URL
175      * @exception RemoteException if registry could not be contacted.
176      * @since JDK1.1
177      */
178     public static String  [] list(String   name)
179     throws RemoteException  , java.net.MalformedURLException  
180     {
181     ParsedNamingURL parsed = parseURL(name);
182     Registry registry = getRegistry(parsed);
183 
184     String   prefix = "";
185     if (parsed.port > 0 || !parsed.host.equals(""))
186         prefix += "//" + parsed.host;
187     if (parsed.port > 0)
188         prefix += ":" + parsed.port;
189     prefix += "/";
190 
191     String  [] names = registry.list();
192     for (int i = 0; i < names.length; i++) {
193         names[i] = prefix + names[i];
194     }
195     return names;
196     }
197 
198     /**
199      * Returns a registry reference obtained from information in the URL.
200      */
201     private static Registry getRegistry(ParsedNamingURL parsed)
202     throws RemoteException  
203     {
204     return LocateRegistry.getRegistry(parsed.host, parsed.port);
205     }
206 
207     /**
208      * Dissect Naming URL strings to obtain referenced host, port and
209      * object name.
210      *
211      * @return an object which contains each of the above
212      * components.
213      *
214      * @exception MalformedURLException if given url string is malformed
215      */
216     private static ParsedNamingURL parseURL(String   str) 
217     throws MalformedURLException   
218     {
219     try {
220         URI   uri = new URI  (str);
221         if (uri.getFragment() != null) {
222         throw new MalformedURLException  (
223             "invalid character, '#', in URL name: " + str);
224         } else if (uri.getQuery() != null) {
225         throw new MalformedURLException  (
226             "invalid character, '?', in URL name: " + str);
227         } else if (uri.getUserInfo() != null) {
228         throw new MalformedURLException  (
229             "invalid character, '@', in URL host: " + str);
230         }
231         String   scheme = uri.getScheme();
232         if (scheme != null && !scheme.equals("rmi")) {
233         throw new MalformedURLException  ("invalid URL scheme: " + str);
234         }
235 
236         String   name = uri.getPath();
237         if (name != null) {
238         if (name.startsWith("/")) {
239             name = name.substring(1);
240         }
241         if (name.length() == 0) {
242             name = null;
243         }
244         }
245 
246         String   host = uri.getHost();
247         if (host == null) {
248         host = "";
249         if (uri.getPort() == -1) {
250             /* handle URIs with explicit port but no host
251              * (e.g., "//:1098/foo"); although they do not strictly
252              * conform to RFC 2396, Naming's javadoc explicitly allows
253              * them.
254              */
255             String   authority = uri.getAuthority();
256             if (authority != null && authority.startsWith(":")) {
257             authority = "localhost" + authority;
258             uri = new URI  (null, authority, null, null, null);
259             }
260         }
261         }
262         int port = uri.getPort();
263         if (port == -1) {
264         port = Registry.REGISTRY_PORT;
265         }
266         return new ParsedNamingURL(host, port, name);
267 
268     } catch (URISyntaxException   ex) {
269         throw (MalformedURLException  ) new MalformedURLException  (
270         "invalid URL string: " + str).initCause(ex);
271     }
272     }
273 
274     /**
275      * Simple class to enable multiple URL return values.
276      */
277     private static class ParsedNamingURL {
278     String   host;
279     int port;
280     String   name;
281     
282     ParsedNamingURL(String   host, int port, String   name) {
283         this.host = host;
284         this.port = port;
285         this.name = name;
286     }
287     }
288 }
289
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags