The list( ) method returns all the URLs that are currently bound as an array of strings. The url argument is the URL of the Naming registry to query. Only the protocol, host, and port are used. The file part of the URL is ignored. list( ) throws a MalformedURLException if url is not a valid rmi URL. A RemoteException is thrown if anything else goes wrong, such as the registry’s not being reachable or refusing to supply the requested information.

Example 18.10 is a simple program to list all the names currently bound in a particular registry. It’s sometimes useful when debugging RMI programs. It allows you to determine whether the names you’re using are the names the server expects.

import java.rmi.*;

public class RegistryLister {

  public static void main(String[] args) {
  
    int port = 1099;
    
    if (args.length == 0) {
      System.err.println("Usage: java RegistryLister host port");
      return;
    }
    
    String host = args[0];
    
    if (args.length > 1) {
      try {
        port = Integer.parseInt(args[1]);
        if (port <1 || port > 65535) port = 1099;
      }
      catch (NumberFormatException e) {}
    
    }
  
    String url = "rmi://" + host + ":" + port + "/";
    try {
      String[] remoteObjects = Naming.list(url);
      for (int i = 0; i < remoteObjects.length; i++) {
        System.out.println(remoteObjects[i]); 
      }
    }
    catch (RemoteException e) {
      System.err.println(e);
    }
    catch (java.net.MalformedURLException e) {
      System.err.println(e);
    }
  }
}

Here’s a result from a run against the RMI server I was using to test the examples in this chapter:

% java RegistryLister login.metalab.unc.edu
rmi://login.metalab.unc.edu:1099/fibonacci
rmi://login.metalab.unc.edu:1099/hello

You can see that the format for the strings is full rmi URLs rather than just names.

A client uses the lookup( ) method to retrieve the remote object associated with the file portion of the name; so, given the URL rmi://metalab.unc.edu:2001/myRemoteObject, it would return the object bound to myRemoteObject from metalab.unc.edu on port 2,001.

This method throws a NotBoundException if the name is not recognized by the remote server. A RemoteException is thrown if the remote registry can’t be reached; for instance, because the network is down or because no registry service is running on the specified port. An AccessException is thrown if the server refuses to look up the name for the particular host. Finally, if the URL is not a proper rmi URL, a MalformedURLException is thrown.

A server uses the bind( ) method to link a name like myRemoteObject to a remote object. If the binding is successful, then clients will be able to retrieve the remote object stub from the registry using a URL like rmi://metalab.unc.edu:2001/myRemoteObject.

Many things can go wrong with the binding process. bind( ) throws a MalformedURLException if url is not a valid rmi URL. A RemoteException is thrown if the registry cannot be reached. An AccessException, a subclass of RemoteException, is thrown if the client is not allowed to bind objects in this registry. If the URL is already bound to a local object, bind( ) throws an AlreadyBoundException.

The unbind( ) method removes the object with the given URL from the registry. It is the opposite of the bind( ) method. What bind( ) has bound, unbind( ) releases. unbind( ) throws a NotBoundException if url was not bound to an object in the first place. Otherwise, this method can throw the same exceptions for the same reasons as bind( ).

The rebind( ) method is just like the bind( ) method, except that it binds the URL to the object, even if the URL is already bound. If the URL is already bound to an object, the old binding is lost. Thus, this method does not throw an AlreadyBoundException. It can still throw RemoteException, AccessException, or MalformedURLException, which have the exact same meanings as they do when thrown by bind( ).

RMISecurityManager has a single constructor that takes no arguments. To set the security manager, use the static System.setSecurityManager( ) method. Most often, you create a new SecurityManager directly inside this method. For example:

System.setSecurityManager(new RMISecurityManager(  ));

The getSecurityContext( ) method determines the environment for certain operations. An RMISecurityManager allows more operations by a class loaded from a local host than from a network host. Eventually (though not as of this writing), public key signatures will be used to grant different classes different trust levels.

There are 23 methods that check various operations to see whether they’re allowed. All are public synchronized, and void, except for checkTopLevelWindow( ), which returns a boolean. Each one throws a StubSecurityException if the action is forbidden; if the action is allowed, the method just returns. These methods check only actions perfomed by stubs, not by other classes in the application. Since only one SecurityManager can be installed in an application, you may have to replace this class with a class of your own if you want to check both actions performed by stubs and actions performed by other classes such as applets.

Table 18.1 lists the methods of the RMISecurityManager, what they check for, and the circumstances under which the operation will be allowed for Java 1.1. (Java 1.2 and later uses a completely different setup that doesn’t allow remote stubs to do anything interesting.) It is unlikely that you will need to call these methods yourself. However, knowledge of these methods is required to understand what a stub can and cannot do.

Except for checkPackageAccess( ), these methods have all been removed from the RMISecurityManager class in Java 1.2 This doesn’t break any existing code, however, because RMISecurityManager still inherits them from its SecurityManager superclass.