4.3 The Naming Class

The java.rmi.Naming class provides methods for storing and obtaining references to remote objects in the remote object registry. The Naming class's methods take, as one of their arguments, a name that is URL formatted java.lang.String 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).

package java.rmi;
public final class Naming {
	public static Remote lookup(String url)
		throws NotBoundException, java.net.MalformedURLException,
		RemoteException;
	public static void bind(String url, Remote obj)
		throws AlreadyBoundException,
		java.net.MalformedURLException, RemoteException;	
	public static void rebind(String url, Remote obj)
		throws RemoteException, java.net.MalformedURLException;
	public static void unbind(String url)
		throws RemoteException, NotBoundException,
		java.net.MalformedURLException;
	public static String[] list(String url)
		throws RemoteException, java.net.MalformedURLException;
}

The lookup method returns the remote object associated with the file portion of the name. The NotBoundException is thrown if the name has not been bound to an object.

The bind method binds the specified name to the remote object. It throws the AlreadyBoundException if the name is already bound to an object.

The rebind method always binds the name to the object even if the name is already bound. The old binding is lost.

The unbind method removes the binding between the name and the remote object. It will throw the NotBoundException if there was no binding.

The list method returns an array of String objects containing a snapshot of the URLs bound in the registry. Only the host and port information of the URL is needed to contact a registry for the list of its contents; thus, the "file" part of the URL is ignored.

---

Note - The java.rmi.AccessException may also be thrown as a result of any of these methods. The AccessException indicates that the caller does not have permission to execute the specific operation. For example, only clients that are local to the host on which the registry runs are permitted to execute the operations, bind, rebind, and unbind. A lookup operation, however can be invoked from any non-local client.

---