/* * Copyright (c) 1996, 2005, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation.  Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */package java.rmi; import java.rmi.registry.*;import java.net.MalformedURLException;import java.net.URI;import java.net.URISyntaxException; /** * The <code>Naming</code> class provides methods for storing and obtaining * references to remote objects in a remote object registry.  Each method of * the <code>Naming</code> class takes as one of its arguments a name that * is a <code>java.lang.String</code> in URL format (without the * scheme component) of the form: * * <PRE> *    //host:port/name * </PRE> * * <P>where <code>host</code> is the host (remote or local) where the registry * is located, <code>port</code> is the port number on which the registry * accepts calls, and where <code>name</code> is a simple string uninterpreted * by the registry. Both <code>host</code> and <code>port</code> are optional. * If <code>host</code> is omitted, the host defaults to the local host. If * <code>port</code> is omitted, then the port defaults to 1099, the * "well-known" port that RMI's registry, <code>rmiregistry</code>, uses. * * <P><em>Binding</em> a name for a remote object is associating or * registering a name for a remote object that can be used at a later time to * look up that remote object.  A remote object can be associated with a name * using the <code>Naming</code> class's <code>bind</code> or * <code>rebind</code> methods. * * <P>Once a remote object is registered (bound) with the RMI registry on the * local host, callers on a remote (or local) host can lookup the remote * object by name, obtain its reference, and then invoke remote methods on the * object.  A registry may be shared by all servers running on a host or an * individual server process may create and use its own registry if desired * (see <code>java.rmi.registry.LocateRegistry.createRegistry</code> method * for details). * * @author  Ann Wollrath * @author  Roger Riggs * @since   JDK1.1 * @see     java.rmi.registry.Registry * @see     java.rmi.registry.LocateRegistry * @see     java.rmi.registry.LocateRegistry#createRegistry(int) */public final class Naming {    /**     * Disallow anyone from creating one of these     */    private Naming() {}     /**     * Returns a reference, a stub, for the remote object associated     * with the specified <code>name</code>.     *     * @param name a name in URL format (without the scheme component)     * @return a reference for a remote object     * @exception NotBoundException if name is not currently bound     * @exception RemoteException if registry could not be contacted     * @exception AccessException if this operation is not permitted     * @exception MalformedURLException if the name is not an appropriately     *  formatted URL     * @since JDK1.1     */    public static Remote lookup(String name)        throws NotBoundException,            java.net.MalformedURLException,            RemoteException    {        ParsedNamingURL parsed = parseURL(name);        Registry registry = getRegistry(parsed);         if (parsed.name == null)            return registry;        return registry.lookup(parsed.name);    }     /**     * Binds the specified <code>name</code> to a remote object.     *     * @param name a name in URL format (without the scheme component)     * @param obj a reference for the remote object (usually a stub)     * @exception AlreadyBoundException if name is already bound     * @exception MalformedURLException if the name is not an appropriately     *  formatted URL     * @exception RemoteException if registry could not be contacted     * @exception AccessException if this operation is not permitted (if     * originating from a non-local host, for example)     * @since JDK1.1     */    public static void bind(String name, Remote obj)        throws AlreadyBoundException,            java.net.MalformedURLException,            RemoteException    {        ParsedNamingURL parsed = parseURL(name);        Registry registry = getRegistry(parsed);         if (obj == null)            throw new NullPointerException("cannot bind to null");         registry.bind(parsed.name, obj);    }     /**     * Destroys the binding for the specified name that is associated     * with a remote object.     *     * @param name a name in URL format (without the scheme component)     * @exception NotBoundException if name is not currently bound     * @exception MalformedURLException if the name is not an appropriately     *  formatted URL     * @exception RemoteException if registry could not be contacted     * @exception AccessException if this operation is not permitted (if     * originating from a non-local host, for example)     * @since JDK1.1     */    public static void unbind(String name)        throws RemoteException,            NotBoundException,            java.net.MalformedURLException    {        ParsedNamingURL parsed = parseURL(name);        Registry registry = getRegistry(parsed);         registry.unbind(parsed.name);    }     /**     * Rebinds the specified name to a new remote object. Any existing     * binding for the name is replaced.     *     * @param name a name in URL format (without the scheme component)     * @param obj new remote object to associate with the name     * @exception MalformedURLException if the name is not an appropriately     *  formatted URL     * @exception RemoteException if registry could not be contacted     * @exception AccessException if this operation is not permitted (if     * originating from a non-local host, for example)     * @since JDK1.1     */    public static void rebind(String name, Remote obj)        throws RemoteException, java.net.MalformedURLException    {        ParsedNamingURL parsed = parseURL(name);        Registry registry = getRegistry(parsed);         if (obj == null)            throw new NullPointerException("cannot bind to null");         registry.rebind(parsed.name, obj);    }     /**     * Returns an array of the names bound in the registry.  The names are     * URL-formatted (without the scheme component) strings. The array contains     * a snapshot of the names present in the registry at the time of the     * call.     *     * @param   name a registry name in URL format (without the scheme     *          component)     * @return  an array of names (in the appropriate format) bound     *          in the registry     * @exception MalformedURLException if the name is not an appropriately     *  formatted URL     * @exception RemoteException if registry could not be contacted.     * @since JDK1.1     */    public static String[] list(String name)        throws RemoteException, java.net.MalformedURLException    {        ParsedNamingURL parsed = parseURL(name);        Registry registry = getRegistry(parsed);         String prefix = "";        if (parsed.port > 0 || !parsed.host.equals(""))            prefix += "//" + parsed.host;        if (parsed.port > 0)            prefix += ":" + parsed.port;        prefix += "/";         String[] names = registry.list();        for (int i = 0; i < names.length; i++) {            names[i] = prefix + names[i];        }        return names;    }     /**     * Returns a registry reference obtained from information in the URL.     */    private static Registry getRegistry(ParsedNamingURL parsed)        throws RemoteException    {        return LocateRegistry.getRegistry(parsed.host, parsed.port);    }     /**     * Dissect Naming URL strings to obtain referenced host, port and     * object name.     *     * @return an object which contains each of the above     * components.     *     * @exception MalformedURLException if given url string is malformed     */    private static ParsedNamingURL parseURL(String str)        throws MalformedURLException    {        try {            return intParseURL(str);        } catch (URISyntaxException ex) {            /* With RFC 3986 URI handling, 'rmi://:<port>' and             * '//:<port>' forms will result in a URI syntax exception             * Convert the authority to a localhost:<port> form             */            MalformedURLException mue = new MalformedURLException(                "invalid URL String: " + str);            mue.initCause(ex);            int indexSchemeEnd = str.indexOf(':');            int indexAuthorityBegin = str.indexOf("//:");            if (indexAuthorityBegin < 0) {                throw mue;            }            if ((indexAuthorityBegin == 0) ||                    ((indexSchemeEnd > 0) &&                    (indexAuthorityBegin == indexSchemeEnd + 1))) {                int indexHostBegin = indexAuthorityBegin + 2;                String newStr = str.substring(0, indexHostBegin) +                                "localhost" +                                str.substring(indexHostBegin);                try {                    return intParseURL(newStr);                } catch (URISyntaxException inte) {                    throw mue;                } catch (MalformedURLException inte) {                    throw inte;                }            }            throw mue;        }    }     private static ParsedNamingURL intParseURL(String str)        throws MalformedURLException, URISyntaxException    {        URI uri = new URI(str);        if (uri.isOpaque()) {            throw new MalformedURLException(                "not a hierarchical URL: " + str);        }        if (uri.getFragment() != null) {            throw new MalformedURLException(                "invalid character, '#', in URL name: " + str);        } else if (uri.getQuery() != null) {            throw new MalformedURLException(                "invalid character, '?', in URL name: " + str);        } else if (uri.getUserInfo() != null) {            throw new MalformedURLException(                "invalid character, '@', in URL host: " + str);        }        String scheme = uri.getScheme();        if (scheme != null && !scheme.equals("rmi")) {            throw new MalformedURLException("invalid URL scheme: " + str);        }         String name = uri.getPath();        if (name != null) {            if (name.startsWith("/")) {                name = name.substring(1);            }            if (name.length() == 0) {                name = null;            }        }         String host = uri.getHost();        if (host == null) {            host = "";            try {                /*                 * With 2396 URI handling, forms such as 'rmi://host:bar'                 * or 'rmi://:<port>' are parsed into a registry based                 * authority. We only want to allow server based naming                 * authorities.                 */                uri.parseServerAuthority();            } catch (URISyntaxException use) {                // Check if the authority is of form ':<port>'                String authority = uri.getAuthority();                if (authority != null && authority.startsWith(":")) {                    // Convert the authority to 'localhost:<port>' form                    authority = "localhost" + authority;                    try {                        uri = new URI(null, authority, null, null, null);                        // Make sure it now parses to a valid server based                        // naming authority                        uri.parseServerAuthority();                    } catch (URISyntaxException use2) {                        throw new                            MalformedURLException("invalid authority: " + str);                    }                } else {                    throw new                        MalformedURLException("invalid authority: " + str);                }            }        }        int port = uri.getPort();        if (port == -1) {            port = Registry.REGISTRY_PORT;        }        return new ParsedNamingURL(host, port, name);    }     /**     * Simple class to enable multiple URL return values.     */    private static class ParsedNamingURL {        String host;        int port;        String name;         ParsedNamingURL(String host, int port, String name) {            this.host = host;            this.port = port;            this.name = name;        }    }}