FileDocCategorySizeDatePackage
Naming.javaAPI DocJava SE 6 API11134Tue Jun 10 00:25:44 BST 2008java.rmi

Naming

public final class Naming extends Object
The Naming class provides methods for storing and obtaining references to remote objects in a remote object registry. Each method of the Naming class takes as one of its arguments a name that is a java.lang.String in URL format (without the scheme component) of the form:
//host:port/name

where host is the host (remote or local) where the registry is located, port is the port number on which the registry accepts calls, and where name is a simple string uninterpreted by the registry. Both host and port are optional. If host is omitted, the host defaults to the local host. If port is omitted, then the port defaults to 1099, the "well-known" port that RMI's registry, rmiregistry, uses.

Binding 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 Naming class's bind or rebind methods.

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 java.rmi.registry.LocateRegistry.createRegistry method for details).

version
1.13, 09/05/99
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)

Fields Summary
Constructors Summary
private Naming()
Disallow anyone from creating one of these

Methods Summary
public static voidbind(java.lang.String name, java.rmi.Remote obj)
Binds the specified name 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

	ParsedNamingURL parsed = parseURL(name);
	Registry registry = getRegistry(parsed);

	if (obj == null)
	    throw new NullPointerException("cannot bind to null");

	registry.bind(parsed.name, obj);
    
private static java.rmi.registry.RegistrygetRegistry(java.rmi.Naming$ParsedNamingURL parsed)
Returns a registry reference obtained from information in the URL.

	return LocateRegistry.getRegistry(parsed.host, parsed.port);
    
private static java.rmi.Naming$ParsedNamingURLintParseURL(java.lang.String str)

	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);
    
public static java.lang.String[]list(java.lang.String name)
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

	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;
    
public static java.rmi.Remotelookup(java.lang.String name)
Returns a reference, a stub, for the remote object associated with the specified name.

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

	ParsedNamingURL parsed = parseURL(name);
	Registry registry = getRegistry(parsed);

	if (parsed.name == null)
	    return registry;
	return registry.lookup(parsed.name);
    
private static java.rmi.Naming$ParsedNamingURLparseURL(java.lang.String str)
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

	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;
	}
    
public static voidrebind(java.lang.String name, java.rmi.Remote obj)
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

	ParsedNamingURL parsed = parseURL(name);
	Registry registry = getRegistry(parsed);

	if (obj == null)
	    throw new NullPointerException("cannot bind to null");

	registry.rebind(parsed.name, obj);
    
public static voidunbind(java.lang.String name)
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

	ParsedNamingURL parsed = parseURL(name);
	Registry registry = getRegistry(parsed);

	registry.unbind(parsed.name);