home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / rmi / Naming.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  8.5 KB  |  259 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Naming.java    1.10 98/07/12
  3.  *
  4.  * Copyright 1996-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.rmi;
  15.  
  16. import java.rmi.registry.*;
  17. import java.net.URL;
  18. import java.net.MalformedURLException;
  19.  
  20. /**
  21.  * The <code>Naming</code> class provides methods for storing and obtaining
  22.  * references to remote objects in the remote object registry. The
  23.  * <code>Naming</code> class's methods take, as one of their arguments, a name
  24.  * that is URL formatted <code>java.lang.String</code> of the form:
  25.  *
  26.  * <PRE>
  27.  *    //host:port/name
  28.  * </PRE>
  29.  * 
  30.  * <P>where <code>host</code> is the host (remote or local) where the registry
  31.  * is located, <code>port</code> is the port number on which the registry
  32.  * accepts calls, and where <code>name</code> is a simple string uninterpreted
  33.  * by the registry. Both <code>host</code> and <code>port</code> are optional.
  34.  * If <code>host</code> is omitted, the host defaults to the local host. If
  35.  * <code>port</code> is omitted, then the port defaults to 1099, the
  36.  * "well-known" port that RMI's registry, <code>rmiregistry</code>, uses.
  37.  *
  38.  * <P><em>Binding</em> a name for a remote object is associating or
  39.  * registering a name for a remote object that can be used at a later time to
  40.  * look up that remote object.  A remote object can be associated with a name
  41.  * using the <code>Naming</code> class's <code>bind</code> or
  42.  * <code>rebind</code> methods.
  43.  *
  44.  * <P>Once a remote object is registered (bound) with the RMI registry on the
  45.  * local host, callers on a remote (or local) host can lookup the remote
  46.  * object by name, obtain its reference, and then invoke remote methods on the
  47.  * object.  A registry may be shared by all servers running on a host or an
  48.  * individual server process may create and use its own registry if desired
  49.  * (see <code>java.rmi.registry.LocateRegistry.createRegistry</code> method
  50.  * for details).
  51.  *
  52.  * @version 1.10, 07/12/98
  53.  * @author  Ann Wollrath
  54.  * @author  Roger Riggs
  55.  * @since   JDK1.1
  56.  * @see     java.rmi.registry.Registry
  57.  * @see     java.rmi.registry.LocateRegistry
  58.  * @see     java.rmi.registry.LocateRegistry#createRegistry(int)
  59.  */
  60. public final class Naming {
  61.     /**
  62.      * Disallow anyone from creating one of these
  63.      */
  64.     private Naming() {}
  65.  
  66.     /**
  67.      * Returns a reference, a stub, for the remote object associated
  68.      * with the specified <code>name</code>.
  69.      *
  70.      * @param name a URL-formatted name for the remote object
  71.      * @return a reference for a remote object
  72.      * @exception NotBoundException if name is not currently bound
  73.      * @exception RemoteException if registry could not be contacted
  74.      * @exception AccessException if this operation is not permitted (if
  75.      * originating from a non-local host, for example)
  76.      * @since JDK1.1
  77.      */
  78.     public static Remote lookup(String name)
  79.     throws NotBoundException,
  80.         java.net.MalformedURLException,
  81.         RemoteException
  82.     {
  83.     URL url = cleanURL(name);
  84.     Registry registry = getRegistry(url);
  85.  
  86.     String file = getName(url);
  87.     if (file == null)
  88.         return registry;
  89.     return registry.lookup(file);
  90.     }
  91.  
  92.     /**
  93.      * Binds the specified <code>name</code> to a remote object.
  94.      *
  95.      * @param name a URL-formatted name for the remote object
  96.      * @param obj a reference for the remote object (usually a stub)
  97.      * @exception AlreadyBoundException if name is already bound
  98.      * @exception MalformedURLException if the name is not an appropriately
  99.      *  formatted URL
  100.      * @exception RemoteException if registry could not be contacted
  101.      * @exception AccessException if this operation is not permitted (if
  102.      * originating from a non-local host, for example)
  103.      * @since JDK1.1
  104.      */
  105.     public static void bind(String name, Remote obj)
  106.     throws AlreadyBoundException,
  107.         java.net.MalformedURLException,
  108.         RemoteException
  109.     {
  110.     URL url = cleanURL(name);
  111.     Registry registry = getRegistry(url);
  112.  
  113.     if (obj == null)
  114.         throw new NullPointerException("cannot bind to null");
  115.  
  116.     registry.bind(getName(url), obj);
  117.     }
  118.  
  119.     /**
  120.      * Destroys the binding for the specified name that is associated
  121.      * with a remote object.
  122.      *
  123.      * @param name a URL-formatted name associated with a remote object
  124.      * @exception NotBoundException if name is not currently bound
  125.      * @exception MalformedURLException if the name is not an appropriately
  126.      *  formatted URL
  127.      * @exception RemoteException if registry could not be contacted
  128.      * @exception AccessException if this operation is not permitted (if
  129.      * originating from a non-local host, for example)
  130.      * @since JDK1.1
  131.      */
  132.     public static void unbind(String name)
  133.     throws RemoteException,
  134.         NotBoundException,
  135.         java.net.MalformedURLException
  136.     {
  137.     URL url = cleanURL(name);
  138.     Registry registry = getRegistry(url);
  139.  
  140.     registry.unbind(getName(url));
  141.     }
  142.  
  143.     /** 
  144.      * Rebinds the specified name to a new remote object. Any existing
  145.      * binding for the name is replaced.
  146.      *
  147.      * @param name a URL-formatted name associated with the remote object
  148.      * @param obj new remote object to associate with the name
  149.      * @exception MalformedURLException if the name is not an appropriately
  150.      *  formatted URL
  151.      * @exception RemoteException if registry could not be contacted
  152.      * @exception AccessException if this operation is not permitted (if
  153.      * originating from a non-local host, for example)
  154.      * @since JDK1.1
  155.      */
  156.     public static void rebind(String name, Remote obj)
  157.     throws RemoteException, java.net.MalformedURLException
  158.     {
  159.     URL url = cleanURL(name);
  160.     Registry registry = getRegistry(url);
  161.  
  162.     if (obj == null)
  163.         throw new NullPointerException("cannot bind to null");
  164.  
  165.     registry.rebind(getName(url), obj);
  166.     }
  167.  
  168.     /**
  169.      * Returns an array of the names bound in the registry.  The names are
  170.      * URL-formatted strings. The array contains a snapshot of the names
  171.      * present in the registry at the time of the call.
  172.      *
  173.      * @param name a URL-formatted name that specifies the remote registry
  174.      * @return an array of names (in the appropriate URL format) bound
  175.      *  in the registry
  176.      * @exception MalformedURLException if the name is not an appropriately
  177.      *  formatted URL
  178.      * @exception RemoteException if registry could not be contacted.
  179.      * @since JDK1.1
  180.      */
  181.     public static String[] list(String name)
  182.     throws RemoteException, java.net.MalformedURLException
  183.     {
  184.     URL url = cleanURL(name);
  185.     Registry registry = getRegistry(url);
  186.  
  187.     String host = url.getHost();
  188.     int port = url.getPort();
  189.  
  190.     String prefix = "rmi:";
  191.      if (port > 0 || !host.equals(""))
  192.         prefix += "//" + host;
  193.     if (port > 0)
  194.         prefix += ":" + port;
  195.     prefix += "/";
  196.  
  197.     String[] names = registry.list();
  198.     for (int i = 0; i < names.length; i++) {
  199.         names[i] = prefix + names[i];
  200.     }
  201.     return names;
  202.     }
  203.  
  204.     /**
  205.      * Returns a registry reference obtained from information in the URL.
  206.      */
  207.     private static Registry getRegistry(URL url)
  208.     throws RemoteException
  209.     {
  210.     String host = url.getHost();
  211.     int port = url.getPort();
  212.  
  213.     return LocateRegistry.getRegistry(host, port);
  214.     }
  215.  
  216.     /**
  217.      * Extracts only the name portion from the specified URL.
  218.      */
  219.     private static String getName(URL url)
  220.     {
  221.     String name = url.getFile();
  222.     if (name == null || name.equals("/"))
  223.         return null;
  224.     return name.substring(1);
  225.     }
  226.  
  227.     /**
  228.      * Creates an HTTP URL from the specified "name" URL to be used in
  229.      * obtaining a registry reference. It checks for and removes the
  230.      * "rmi:" protocol if it was specified as part of the "name".
  231.      *
  232.      * @exception MalformedURLException if hostname in url contains '#' or
  233.      *            if incorrect protocol specified
  234.      */
  235.     private static URL cleanURL(String name)
  236.     throws java.net.MalformedURLException
  237.     {
  238.     URL url = new URL("http:");
  239.  
  240.     // Anchors (i.e. '#') are meaningless in rmi URLs - disallow them
  241.     if (name.indexOf('#') >= 0) {
  242.         throw new MalformedURLException
  243.         ("Invalid character, '#', in URL: " + name);
  244.     }
  245.  
  246.     // remove the approved protocol
  247.     if (name.startsWith("rmi:"))
  248.         name = name.substring(4);
  249.  
  250.     // No protocol must remain
  251.     int colon = name.indexOf(':');
  252.     if (colon >= 0 && colon < name.indexOf('/') )
  253.         throw new java.net.MalformedURLException("No protocol needed");
  254.  
  255.     url = new URL(url, name);
  256.     return url;
  257.     }
  258. }
  259.