1. /*

  2.  * @(#)Registry.java	1.18 03/12/19

  3.  *

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. package java.rmi.registry;

  8. 

  9. import java.rmi.AccessException;

  10. import java.rmi.AlreadyBoundException;

  11. import java.rmi.NotBoundException;

  12. import java.rmi.Remote;

  13. import java.rmi.RemoteException;

  14. 

  15. /**

  16.  * <code>Registry</code> is a remote interface to a simple remote

  17.  * object registry that provides methods for storing and retrieving

  18.  * remote object references bound with arbitrary string names.  The

  19.  * <code>bind</code>, <code>unbind</code>, and <code>rebind</code>

  20.  * methods are used to alter the name bindings in the registry, and

  21.  * the <code>lookup</code> and <code>list</code> methods are used to

  22.  * query the current name bindings.

  23.  *

  24.  * <p>In its typical usage, a <code>Registry</code> enables RMI client

  25.  * bootstrapping: it provides a simple means for a client to obtain an

  26.  * initial reference to a remote object.  Therefore, a registry's

  27.  * remote object implementation is typically exported with a

  28.  * well-known address, such as with a well-known {@link

  29.  * java.rmi.server.ObjID#REGISTRY_ID ObjID} and TCP port number

  30.  * (default is {@link #REGISTRY_PORT 1099}).

  31.  *

  32.  * <p>The {@link LocateRegistry} class provides a programmatic API for

  33.  * constructing a bootstrap reference to a <code>Registry</code> at a

  34.  * remote address (see the static <code>getRegistry</code> methods)

  35.  * and for creating and exporting a <code>Registry</code> in the

  36.  * current VM on a particular local address (see the static

  37.  * <code>createRegistry</code> methods).

  38.  *

  39.  * <p>A <code>Registry</code> implementation may choose to restrict

  40.  * access to some or all of its methods (for example, methods that

  41.  * mutate the registry's bindings may be restricted to calls

  42.  * originating from the local host).  If a <code>Registry</code>

  43.  * method chooses to deny access for a given invocation, its

  44.  * implementation may throw {@link java.rmi.AccessException}, which

  45.  * (because it extends {@link java.rmi.RemoteException}) will be

  46.  * wrapped in a {@link java.rmi.ServerException} when caught by a

  47.  * remote client.

  48.  *

  49.  * <p>The names used for bindings in a <code>Registry</code> are pure

  50.  * strings, not parsed.  A service which stores its remote reference

  51.  * in a <code>Registry</code> may wish to use a package name as a

  52.  * prefix in the name binding to reduce the likelihood of name

  53.  * collisions in the registry.

  54.  *

  55.  * @author	Ann Wollrath

  56.  * @author	Peter Jones

  57.  * @version	1.18, 03/12/19

  58.  * @since	JDK1.1

  59.  * @see		LocateRegistry

  60.  */

  61. public interface Registry extends Remote {

  62. 

  63.     /** Well known port for registry. */

  64.     public static final int REGISTRY_PORT = 1099;

  65.     

  66.     /**

  67.      * Returns the remote reference bound to the specified

  68.      * <code>name</code> in this registry.

  69.      *

  70.      * @param	name the name for the remote reference to look up

  71.      *

  72.      * @return	a reference to a remote object

  73.      *

  74.      * @throws	NotBoundException if <code>name</code> is not currently bound

  75.      *

  76.      * @throws	RemoteException if remote communication with the

  77.      * registry failed; if exception is a <code>ServerException</code>

  78.      * containing an <code>AccessException</code>, then the registry

  79.      * denies the caller access to perform this operation

  80.      *

  81.      * @throws	AccessException if this registry is local and it denies

  82.      * the caller access to perform this operation

  83.      *

  84.      * @throws	NullPointerException if <code>name</code> is <code>null</code>

  85.      */

  86.     public Remote lookup(String name)

  87. 	throws RemoteException, NotBoundException, AccessException;

  88. 

  89.     /**

  90.      * Binds a remote reference to the specified <code>name</code> in

  91.      * this registry.

  92.      *

  93.      * @param	name the name to associate with the remote reference

  94.      * @param	obj a reference to a remote object (usually a stub)

  95.      *

  96.      * @throws	AlreadyBoundException if <code>name</code> is already bound

  97.      *

  98.      * @throws	RemoteException if remote communication with the

  99.      * registry failed; if exception is a <code>ServerException</code>

  100.      * containing an <code>AccessException</code>, then the registry

  101.      * denies the caller access to perform this operation (if

  102.      * originating from a non-local host, for example)

  103.      *

  104.      * @throws	AccessException if this registry is local and it denies

  105.      * the caller access to perform this operation

  106.      *

  107.      * @throws	NullPointerException if <code>name</code> is

  108.      * <code>null</code>, or if <code>obj</code> is <code>null</code>

  109.      */

  110.     public void bind(String name, Remote obj)

  111. 	throws RemoteException, AlreadyBoundException, AccessException;

  112. 

  113.     /**

  114.      * Removes the binding for the specified <code>name</code> in

  115.      * this registry.

  116.      *

  117.      * @param	name the name of the binding to remove

  118.      *

  119.      * @throws	NotBoundException if <code>name</code> is not currently bound

  120.      *

  121.      * @throws	RemoteException if remote communication with the

  122.      * registry failed; if exception is a <code>ServerException</code>

  123.      * containing an <code>AccessException</code>, then the registry

  124.      * denies the caller access to perform this operation (if

  125.      * originating from a non-local host, for example)

  126.      *

  127.      * @throws	AccessException if this registry is local and it denies

  128.      * the caller access to perform this operation

  129.      *

  130.      * @throws	NullPointerException if <code>name</code> is <code>null</code>

  131.      */

  132.     public void unbind(String name)

  133. 	throws RemoteException, NotBoundException, AccessException;

  134. 

  135.     /**

  136.      * Replaces the binding for the specified <code>name</code> in

  137.      * this registry with the supplied remote reference.  If there is

  138.      * an existing binding for the specified <code>name</code>, it is

  139.      * discarded.

  140.      *

  141.      * @param	name the name to associate with the remote reference

  142.      * @param	obj a reference to a remote object (usually a stub)

  143.      *

  144.      * @throws	RemoteException if remote communication with the

  145.      * registry failed; if exception is a <code>ServerException</code>

  146.      * containing an <code>AccessException</code>, then the registry

  147.      * denies the caller access to perform this operation (if

  148.      * originating from a non-local host, for example)

  149.      *

  150.      * @throws	AccessException if this registry is local and it denies

  151.      * the caller access to perform this operation

  152.      *

  153.      * @throws	NullPointerException if <code>name</code> is

  154.      * <code>null</code>, or if <code>obj</code> is <code>null</code>

  155.      */

  156.     public void rebind(String name, Remote obj)

  157. 	throws RemoteException, AccessException;

  158. 

  159.     /**

  160.      * Returns an array of the names bound in this registry.  The

  161.      * array will contain a snapshot of the names bound in this

  162.      * registry at the time of the given invocation of this method.

  163.      *

  164.      * @return	an array of the names bound in this registry

  165.      *

  166.      * @throws	RemoteException if remote communication with the

  167.      * registry failed; if exception is a <code>ServerException</code>

  168.      * containing an <code>AccessException</code>, then the registry

  169.      * denies the caller access to perform this operation

  170.      *

  171.      * @throws	AccessException if this registry is local and it denies

  172.      * the caller access to perform this operation

  173.      */

  174.     public String[] list() throws RemoteException, AccessException;

  175. }