[TOC] [Prev] [Next]

# Registry Interfaces

The RMI system uses the `java.rmi.registry.Registry` interface and the `java.rmi.registry.LocateRegistry` class to provide a well-known bootstrap service for retrieving and registering objects by simple names. Any server process can support its own registry or a single registry can be used for a host.

A registry is a remote object that maps names to remote objects. A registry can be used in a virtual machine with other server classes or standalone.

The methods of `LocateRegistry` are used to get a registry operating on a particular host or host and port.

### Topics:

- The Registry Interface
- The LocateRegistry Class
- The RegistryHandler Interface

# The Registry Interface

The `java.rmi.registry.Registry` remote interface provides methods for lookup, binding, rebinding, unbinding, and listing the contents of a registry. The `java.rmi.Naming` class uses the `registry` remote interface to provide URL-based naming.

    package java.rmi.registry;

    public interface Registry extends java.rmi.Remote
    {

    	public static final int REGISTRY_PORT = 1099;

    	public java.rmi.Remote lookup(String name)
    		throws java.rmi.RemoteException,
    		java.rmi.NotBoundException, java.rmi.AccessException;

    	public void bind(String name, java.rmi.Remote obj)
    		throws java.rmi.RemoteException,
    		java.rmi.AlreadyBoundException, java.rmi.AccessException;

    	public void rebind(String name, java.rmi.Remote obj)
    		throws java.rmi.RemoteException, java.rmi.AccessException;

    	public void unbind(String name)
    		throws java.rmi.RemoteException,
    		java.rmi.NotBoundException, java.rmi.AccessException;

    	public String[] list()
    		throws java.rmi.RemoteException, java.rmi.AccessException;
    }

The `REGISTRY_PORT` is the default port of the registry.

The `lookup` method returns the remote object bound to the specified name. The remote object implements a set of remote interfaces. Clients can cast the remote object to the expected remote interface. (This cast can fail in the usual ways that casts can fail in the Java language.)

The `bind` method associates the name with the remote object, obj. If the name is already bound to an object the `AlreadyBoundExcepton` is thrown.

The `rebind` method associates the name with the remote object, obj. Any previous binding of the name is discarded.

The `unbind` method removes the binding between the name and the remote object, obj. If the name is not already bound to an object the `NotBoundException` is thrown.

The `list` method returns an array of `Strings` containing a snapshot of the names bound in the registry. The return value contains a snapshot of the contents of the registry.

Clients can access the registry either by using the `LocateRegistry` and `Registry` interfaces or by using the methods of the URL-based `java.rmi.Naming` class. The registry supports `bind`, `unbind`, and `rebind` only from clients on the same host as the server; a lookup can be done from any host.

# The LocateRegistry Class

The class `java.rmi.registry.LocateRegistry` contains static methods that return a reference to a registry on the current host, current host at specified port, a specified host or at a particular port on a specified host. What is returned is the remote stub for the registry with the specified host and port information. No remote operations need be performed to obtain a reference (stub) for any registry on any host.

    package java.rmi.registry;
    public final class LocateRegistry {
    	public static Registry getRegistry()
    		throws java.rmi.RemoteException;

    	public static Registry getRegistry(int port)
    		throws java.rmi.RemoteException;

    	public static Registry getRegistry(String host)
    		throws java.rmi.RemoteException,
    		java.rmi.UnknownHostException;

    	public static Registry getRegistry(String host, int port)
    		throws java.rmi.RemoteException,
    		java.rmi.UnknownHostException;

    	public static Registry createRegistry(int port)
    		throws java.rmi.RemoteException;
    }

The `createRegistry` method creates and exports a registry on the local host on the specified port. The registry implements a simple flat naming syntax that binds the name of a remote object (a string) to a remote object reference. The name and remote object bindings are not remembered across server restarts.

Starting a registry with the `createRegistry` method does not keep the server process alive.

# The RegistryHandler Interface

The interface `RegistryHandler` is used to interface to the private implementation.

    package java.rmi.registry;

    public interface RegistryHandler {

    	Registry registryStub(String host, int port)
    		throws java.rmi.RemoteException,
    		java.rmi.UnknownHostException;

    	Registry registryImpl(int port)
    		throws java.rmi.RemoteException;
    }

The method `registryStub` returns a stub for contacting a remote registry on the specified host and port.

The method `registryImpl` constructs and exports a registry on the specified port. The port must be nonzero.

[TOC] [Prev] [Next]

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