[TOC] [Prev] [Next]

# Client Interfaces

When writing an applet or an application that uses remote objects, the programmer needs to be aware of the RMI system's client visible interfaces.

### Topics:

- The Remote Interface
- The RemoteException Class
- The Naming Class

# The Remote Interface

    package java.rmi;
    public interface Remote {}

The `java.rmi.Remote` interface serves to identify all remote objects, all remote objects must directly or indirectly implement this interface. Note that all remote interfaces must be declared `public`.

# The RemoteException Class

All remote exceptions are subclasses of `java.rmi.RemoteException`. This allows interfaces to handle all types of remote exceptions and to distinguish local exceptions, and exceptions specific to the method, from exceptions thrown by the underlying distributed object mechanisms.

    package java.rmi;
    public class RemoteException extends java.io.IOException
    {
    	// The actual exception or error that occurred.
    	public Throwable detail;

    	// Create a remote exception.
    	public RemoteException();

    	// Create a remote exception with the specified string.
    	public RemoteException(String s);

    	// Create remote exception with specified string and exception.
    	public RemoteException(String s, Throwable ex);

    	// Produce message, including message from any nested exception.
    	public String getMessage();
    }

A `RemoteException` can be constructed with a nested exception (a `Throwable`). Typically, the nested exception, ex, specified as a parameter in the third form of the constructor, is the underlying I/O exception that occurred during an RMI call.

# The Naming Class

The `java.rmi.Naming` class allows remote objects to be retrieved and defined using the familiar Uniform Resource Locator (URL) syntax. The URL consists of protocol, host, port, and name fields. The `Registry` service on the specified host and port is used to perform the specified operation. The protocol should be specified as `rmi`, as in `rmi://java.sun.com:2001/root`.

    package java.rmi;
    public final class Naming {
    	public static Remote lookup(String url)
    		throws NotBoundException, java.net.MalformedURLException,
    		UnknownHostException, RemoteException;

    	public static void bind(String url, Remote obj)
    		throws AlreadyBoundException,
    		java.net.MalformedURLException, UnknownHostException,
    		RemoteException;

    	public static void rebind(String url, Remote obj)
    		throws RemoteException, java.net.MalformedURLException,
    		UnknownHostException;

    	public static void unbind(String url)
    		throws RemoteException, NotBoundException,
    		java.net.MalformedURLException, UnknownHostException;

    	public static String[] list(String url)
    		throws RemoteException, java.net.MalformedURLException,
    		UnknownHostException;
    }

The `lookup` method returns the remote object associated with the file portion of the name; so in the preceding example it would return the object named `root`. 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 `Strings` 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.

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.

[TOC] [Prev] [Next]

Copyright © 1996, 1997 Sun Microsystems, Inc. All rights reserved.