[TOC] [Prev] [Next]

Server Interfaces

When implementing a server, the client interfaces are available and extended with those that allow the definition, creation and export of remote objects.

Topics:

The RemoteServer Class

 The RemoteServer class is the common superclass to all server implementations and provides the framework to support a wide range of remote reference semantics. At present the only subclass supported is UnicastRemoteServer.

package java.rmi.server;
abstract class RemoteServer extends RemoteObject {
	static String getClientHost()
		throws ServerNotActiveException;
	static int getClientPort()
		throws ServerNotActiveException;
}
The getClientHost and getClientPort methods allows an active method to determine the host and port that initiated the remote method active in the current thread. The ServerNotActiveException is thrown if no remote method is active on the current thread.

The UnicastRemoteServer Class

The UnicastRemoteServer class provides support for point-to-point active object references using TCP streams. The class implements a remote server object with the following characteristics:

Constructing a new Remote Object

 In a Java virtual machine running as a server, remote objects defined by the developer may be created by the server application. When those remote object classes extend UnicastRemoteServer, two constructors are available to create and export new remote objects. These constructors are invoked from the corresponding constructor of the remote object class. The default constructor creates a new unicast remote object using the default port. The second constructor allows the object to be exported on a specified port.

Exporting an implementation not extended from RemoteObject

The two forms of exportObject are used to export remote objects that are not implemented by extending UnicastRemoteServer. The exportObject method is called with the object to be exported on the default port. The second form is used to export the object on the specified port number. ExportObject returns the stub object clients will use to refer to this object. The object must be exported prior to the first time it is returned to a client; otherwise a StubNotFoundException is thrown.

Either the stub object or the object itself can be passed as arguments in calls or returned to clients. During marshaling, if the remote object is passed, a lookup is performed to find the matching remote stub and that stub is passed or returned instead.

The Unreferenced Interface

interface java.rmi.server.Unreferenced {
	void unreferenced();
}
The java.rmi.Unreferenced interface allows a server object to receive notification that there are no remote references to it. The distributed garbage collection mechanism maintains a set of remote references to each remote object. As long as some client holds a remote reference the RMI runtime keeps a local reference to the remote object. When the set becomes empty the Unreferenced.unreferenced method is invoked. No action is required by the implementation and it is not required to support Unreferenced.

As long as some local reference to the remote object exists it may be passed in remote calls or returned to clients. Doing so will add the client or server it to the referenced set. When those new references no longer exist Unreferenced will be invoked. As such, the Unreferenced method may be called more than once, each time the set is newly emptied. Remote objects are only collected when no more references, either local references or those held by clients, still exist.

The Registry Interface and The LocateRegistry Class

The RMI system uses the Registry interface and the LocateRegistry and RegistryImpl classes 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 RegistryImpl is a remote object that maps names to remote objects. The RegistryImpl class provides an implementation that can be used in a virtual machine with other server classes or stand-alone.

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

Note that the java.rmi.Naming interface uses the Registry interface to provide URL based naming.

The Registry Interface

package java.rmi.registry;
public interface Registry 
	extends Remote
{
	public Remote lookup(String name)
		throws RemoteException, NotBoundException, AccessException;

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

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

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

	public String[] list()
		throws RemoteException, AccessException;
}
The Registry remote interface provides functions for lookup, binding, rebinding, unbinding, and listing the contents of a registry.

The lookup method returns the object bound to the specified name. The remote object has remote interfaces. Clients can cast the remote object to the expected remote interface (note that this cast can fail in the usual ways that casts can fail in the Java language).

The bind method sets the mapping between the name and the remote object. If the name is already bound to an object the AlreadyBoundExcepton is thrown.

The rebind method sets the mapping between the name and the remote object. Any previous binding of the name is discarded.

The unbind method removes the mapping between the name and the remote object. 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. The return value does not reflect any changes made to the contents of the registry after the call.

The LocateRegistry Class

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

	public static Registry getRegistry(int port)
		throws RemoteException;

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

	public static Registry getRegistry(String host, int port)
		throws RemoteException, UnknownHostException;
}
The class LocateRegistry contains static methods that retrieve a registry on the current host, current host at specified port, a specified host or at a particular port on a specified host.

The RegistryImpl Class

The class RegistryImpl is a simple registry class that implements the Registry interface with a simple flat naming syntax. The name and remote object bindings are not remembered across server restarts. This Registry implementation allows bind, unbind, and rebind methods only from clients on the same host as the server.

package java.rmi.registry;

public class RegistryImpl
	extends 	java.rmi.server.UnicastRemoteServer
	implements Registry
{
	public RegistryImpl()
		throws RemoteException;

	public RegistryImpl(int port)
		throws RemoteException;    

	public static void main(String args[]);
}
A RegistryImpl can be created using either the default port or using a specified port. To keep it from being garbage collected it is important to retain a reference to the RegistryImpl.

For stand-alone use the RegistryImpl defines a main method that can be passed a port number. The main method sets the security manager so no remote object can load damaging objects into the process. Then it creates a RegistryImpl on the specified port.

Clients will access the registry with the LocateRegistry class and the Registry interfaces or via the URL based naming interface. In the URL, the hostname is required. The port number is required in the URL if the registry was created using a specific port.

The StubSecurityManager Class

package java.rmi.server;
public class StubSecurityManager extends SecurityManager {
	public StubSecurityManager();
}
The StubSecurityManager can be used when the application does not require specialized security functions but does need the protection it provides. This simple security manger disables all functions except class definition and access so that other classes for remote objects, their arguments and returns can be loaded as needed.

If no security manager has been set, RMI will load stub classes only from the local files as defined by CLASSPATH. This insures that some security manager must be responsible for the actions of loaded stubs and classes as part of an remote method invocation. A security manager is set using System.setSecurityManager.

The StubClassLoader Class

The StubClassLoader class is used by the RMI runtime to load stubs and skeletons. These classes and the way they are used support the safety properties of the Java RMI runtime. The stub class loader always loads locally available classes. Only if the required stubs are not available and a security manager is in force will stubs be loaded from a network source.

The class loader keeps a cache of loaders for individual Uniform Resource Locators (URLs) and the classes that have been loaded from them. When a stub or skeleton has been loaded, any class references that occur as parameters or returns will be loaded from the same host and are subject to the same security restrictions.

Server processes must declare to the RMI runtime the location of the stubs that will be available to its clients. The java.rmi.server.StubClassBase property should be a URL from which stub classes and classes used by stubs will be loaded, using the normal protocols, for example http, ftp, etc...

package java.rmi.server;
public class StubClassLoader extends ClassLoader {
	public Class loadClass(String name)
		throws ClassNotFoundException;
	public static StubClassLoader getClassLoader(URL codebase);
	public static StubClassLoader getLocalLoader()
		throws MalformedURLException;
}
The loadClass method finds or load the specified class by name. If not currently known, the URL is used as the base to locate the class file. The class is loaded, defined, and returned.

The getClassLoader method is used to find or create a class loader for the specified URL.

The getLocalLoader method is used to find or create a class loader that uses the locally defined property java.rmi.server.StubClassBase as the base URL. If the property is not defined getLocalLoader returns null, and stub classes will only be loaded using CLASSPATH.

Stub and Skeleton Compiler

The stub and skeleton compiler is used to compile the appropriate stubs and skeletons for a specific remote object implementation. The compiler is invoked with the package qualified class name of the remote object class. The class must previously have been compiled successfully. The location of the imported classes may be specified either with the CLASSPATH environment variable or with the -classpath command line argument. The compiled class files are placed in the current directory unless the -d argument is specified following the same mechanism for writing class files as javac.

Exceptions

These are the general remote object exceptions that the server is most likely to encounter:


[TOC] [Prev] [Next]

rmi-comments@jse.East.Sun.COM
Copyright © 1996 Sun Microsystems, Inc. All rights reserved.