Chapter 13. The java.rmi Package

The java.rmi package is the main RMI package; it contains the principle objects used in RMI clients and servers. Figure 13-1 shows the class hierarchy for this package.

The Remote interface and the Naming class define and locate RMI objects over the network. The RMISecurityManager class provides additional security semantics required for RMI interactions. The MarshalledObject class is used during remote method calls for certain method arguments. In addition, this core package contains a number of basic RMI exception types used during remote object lookups and remote method calls.

Figure 13-1. The java.rmi package

AccessException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

This subclass of RemoteException is thrown when you attempt to perform an improper operation on a Naming or Registry object. A registry allows only local requests to bind, rebind, or unbind objects, so an attempt to call one of these methods on a remote registry results in an AccessException being thrown.

public class AccessException extends RemoteException {
//	Public Constructors
	public AccessException (String s);
	public AccessException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->AccessException

Thrown By: java.rmi.registry.Registry.{bind(), list(), lookup(), rebind(), unbind()}

AlreadyBoundException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

An exception that's thrown when an attempt is made to bind an object to a name that is already bound.

public class AlreadyBoundException extends Exception {
//	Public Constructors
	public AlreadyBoundException ();
	public AlreadyBoundException (String s);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->AlreadyBoundException

Thrown By: Naming.bind(), java.rmi.registry.Registry.bind()

ConnectException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

A RemoteException that's thrown when a remote host refuses to connect during a remote method call.

public class ConnectException extends RemoteException {
//	Public Constructors
	public ConnectException (String s);
	public ConnectException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->ConnectException

ConnectIOException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

A RemoteException that's thrown if there is an I/O error while attempting to make a remote method call.

public class ConnectIOException extends RemoteException {
//	Public Constructors
	public ConnectIOException (String s);
	public ConnectIOException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->ConnectIOException

MarshalException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

A RemoteException that's thrown if an I/O error occurs while attempting to marshal any part of a remote method call (header data or method arguments).

public class MarshalException extends RemoteException {
//	Public Constructors
	public MarshalException (String s);
	public MarshalException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->MarshalException

MarshalledObject

Java 1.2

java.rmi

serializable

A MarshalledObject represents an object that has been serialized and marshalled according to the RMI specification. If the original object was a remote object reference, the MarshalledObject contains a serialized stub for the object. Otherwise, the object is serialized and tagged with a codebase URL that can be used on the receiving end to find the class definition for the object, if needed.

The MarshalledObject constructor allows you to serialize an existing object into marshalled form. The get() method returns a copy of the serialized object it contains. You can also compare the equality of the serialized objects of two MarshalledObject objects.

MarshalledObject objects are used primarily by the RMI activation API, to allow for the passing of initialization parameters for activated objects in a standard way, for example.

public final class MarshalledObject implements Serializable {
//	Public Constructors
	public MarshalledObject (Object obj) throws IOException;
//	Public Instance Methods
	public Object get () throws IOException, ClassNotFoundException;
//	Public methods overriding Object
	public boolean equals (Object obj);
	public int hashCode ();
}

Hierarchy: Object-->MarshalledObject(Serializable)

Passed To: java.rmi.activation.Activatable.{Activatable(), exportObject()}, java.rmi.activation.ActivationDesc.ActivationDesc(), java.rmi.activation.ActivationGroup.activeObject(), java.rmi.activation.ActivationGroupDesc.ActivationGroupDesc(), java.rmi.activation.ActivationMonitor.activeObject()

Returned By: java.rmi.activation.ActivationDesc.getData(), java.rmi.activation.ActivationGroup.newInstance(), java.rmi.activation.ActivationGroup_Stub.newInstance(), java.rmi.activation.ActivationGroupDesc.getData(), java.rmi.activation.ActivationInstantiator.newInstance(), java.rmi.activation.Activator.activate()

Naming

Java 1.1

java.rmi

PJ1.1(opt)

This is the primary application interface to the naming service within the RMI registry. You can get references to remote objects with the lookup() method. To bind local object implementations to names within the local registry, use the bind() and rebind() methods. Locally bound objects can be removed from the name registry using unbind(). To obtain all of the names for objects currently stored in the registry, use the list() method.

Each name argument to the methods on the Naming interface takes the form of a URL (e.g., rmi://remoteHost:port/objName). If you are referencing a local object and the object is exported to the default registry port, the URL can simply take the form of the object's name in the local registry, (e.g., objName). This is possible because the rmi: protocol is assumed if it isn't present in the URL and the default host is the local host.

Note that while the lookup() method can reference any remote RMI registry, the bind(), rebind(), and unbind() methods can only be called on the local registry. Attempting to call these methods against a remote registry results in an AccessException being thrown.

public final class Naming {
//	No Constructor
//	Public Class Methods
	public static void bind (String name, Remote obj) throws AlreadyBoundException, java.net.MalformedURLException, RemoteException;
	public static String[ ] list (String name) throws RemoteException, java.net.MalformedURLException;
	public static Remote lookup (String name) throws NotBoundException, java.net.MalformedURLException, RemoteException;
	public static void rebind (String name, Remote obj) throws RemoteException, java.net.MalformedURLException;
	public static void unbind (String name) throws RemoteException, NotBoundException, java.net.MalformedURLException;
}

NoSuchObjectException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

This subclass of RemoteException is thrown when you attempt to invoke a method on a remote object that is no longer available.

public class NoSuchObjectException extends RemoteException {
//	Public Constructors
	public NoSuchObjectException (String s);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->NoSuchObjectException

Thrown By: java.rmi.activation.Activatable.unexportObject(), java.rmi.server.RemoteObject.toStub(), java.rmi.server.UnicastRemoteObject.unexportObject()

NotBoundException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

An exception that is thrown by a Naming instance when a lookup is attempted using a name with no object bound to it.

public class NotBoundException extends Exception {
//	Public Constructors
	public NotBoundException ();
	public NotBoundException (String s);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->NotBoundException

Thrown By: Naming.{lookup(), unbind()}, java.rmi.registry.Registry.{lookup(), unbind()}

Remote

Java 1.1

java.rmi

remote PJ1.1(opt)

Every remote object must implement the Remote interface. In addition, any methods you want to be remotely callable must be defined within an interface that extends the Remote interface. This is a place-holder interface that identifies all remote objects, but doesn't define any methods of its own.

public abstract interface Remote {
}

Implementations: java.rmi.activation.ActivationGroup_Stub, java.rmi.activation.ActivationInstantiator, java.rmi.activation.ActivationMonitor, java.rmi.activation.ActivationSystem, java.rmi.activation.Activator, java.rmi.dgc.DGC, java.rmi.registry.Registry, java.rmi.server.RemoteObject, javax.ejb.EJBHome, javax.ejb.EJBObject

Passed To: Naming.{bind(), rebind()}, java.rmi.activation.Activatable.{exportObject(), unexportObject()}, java.rmi.activation.ActivationGroup.activeObject(), java.rmi.registry.Registry.{bind(), rebind()}, java.rmi.server.RemoteObject.toStub(), java.rmi.server.RemoteRef.invoke(), java.rmi.server.ServerRef.exportObject(), java.rmi.server.Skeleton.dispatch(), java.rmi.server.UnicastRemoteObject.{exportObject(), unexportObject()}

Returned By: Naming.lookup(), java.rmi.activation.Activatable.{exportObject(), register()}, java.rmi.activation.ActivationID.activate(), java.rmi.registry.Registry.lookup(), java.rmi.server.RemoteObject.toStub(), java.rmi.server.UnicastRemoteObject.exportObject()

RemoteException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

This subclass of IOException is thrown when an error occurs during any remote object operation. The RemoteException includes a Throwable data member that represents the nested exception that caused the RemoteException to be thrown. For example, if an exception occurs on the server while executing a remote method, the client receives a RemoteException (in the form of a ServerException, one of its subclasses) with its Throwable data member initialized to the server-side exception that caused the client-side RemoteException to be delivered.

public class RemoteException extends IOException {
//	Public Constructors
	public RemoteException ();
	public RemoteException (String s);
	public RemoteException (String s, Throwable ex);
//	Public methods overriding Throwable
	public String getMessage ();	default:null
1.2	public void printStackTrace ();
1.2	public void printStackTrace (PrintStream ps);
1.2	public void printStackTrace (PrintWriter pw);
//	Public Instance Fields
	public Throwable detail ;
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException

Subclasses: AccessException, java.rmi.ConnectException, ConnectIOException, MarshalException, NoSuchObjectException, ServerError, ServerException, ServerRuntimeException, StubNotFoundException, UnexpectedException, java.rmi.UnknownHostException, UnmarshalException, java.rmi.activation.ActivateFailedException, java.rmi.server.ExportException, java.rmi.server.SkeletonMismatchException, java.rmi.server.SkeletonNotFoundException, javax.transaction.InvalidTransactionException, javax.transaction.TransactionRequiredException, javax.transaction.TransactionRolledbackException

Thrown By: Too many methods to list.

RMISecurityException

Java 1.1; Deprecated in Java 1.2

java.rmi

serializable unchecked PJ1.1(opt)

A SecurityException thrown by the RMISecurityManager when a security violation is detected during a remote operation.

public class RMISecurityException extends SecurityException {
//	Public Constructors
#	public RMISecurityException (String name);
#	public RMISecurityException (String name, String arg);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->RuntimeException-->SecurityException-->RMISecurityException

RMISecurityManager class

Java 1.1

java.rmi

PJ1.1(opt)

The RMISecurityManager enforces the security policy for classes that are loaded as stubs for remote objects, by overriding all relevant access-check methods from the SecurityManager. By default, stub objects are only allowed to perform class definition and class access operations. If you don't set the local security manager as RMISecurityManager (using the System.setSecurityManager() method), stub classes are only loadable from the local filesystem. Applets engaging in RMI calls do not need to use the RMISecurityManager, since the security manager provided by the browser does the necessary access control on loading remote classes, etc.

You don't normally need to interact with the RMISecurityManager directly within your application code, except to set it as the system security manager before starting your RMI code.

public class RMISecurityManager extends SecurityManager {
//	Public Constructors
	public RMISecurityManager ();
}

Hierarchy: Object-->SecurityManager-->RMISecurityManager

ServerError class

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

A nonrecoverable error that occurs while a server is executing a remote method. The nested Throwable data member (inherited from RemoteException) contains the server-side exception that generated the error.

public class ServerError extends RemoteException {
//	Public Constructors
	public ServerError (String s, Error err);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->ServerError

ServerException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

This exception is thrown if a RemoteException is thrown while the server object is executing a remote method.

public class ServerException extends RemoteException {
//	Public Constructors
	public ServerException (String s);
	public ServerException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->ServerException

ServerRuntimeException

Java 1.1; Deprecated in Java 1.2

java.rmi

serializable checked PJ1.1(opt)

An exception that occurs if a RuntimeException is thrown while a server object is executing a remote method. The nested Throwable data member (inherited from RemoteException) contains the server-side runtime exception that generated the exception.

public class ServerRuntimeException extends RemoteException {
//	Public Constructors
#	public ServerRuntimeException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->ServerRuntimeException

StubNotFoundException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

This exception can occur either when an object is being exported to participate in remote RMI calls or during a remote method call. During export on the server, this exception is thrown if the stub class for the object cannot be found or used for some reason (e.g., the stub class isn't in the CLASSPATH of the server process or the stub class can't be instantiated). During a remote method call, the client can receive this exception if the remote object hasn't been exported completely or correctly.

public class StubNotFoundException extends RemoteException {
//	Public Constructors
	public StubNotFoundException (String s);
	public StubNotFoundException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->StubNotFoundException

UnexpectedException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

An UnexpectedException is thrown if an exception that isn't specified on a remote method's signature is encountered during the return from a remote method call. The unexpected exception can occur on the server or on the client. The nested Throwable object (inherited from RemoteException) contains the actual exception that occurred.

public class UnexpectedException extends RemoteException {
//	Public Constructors
	public UnexpectedException (String s);
	public UnexpectedException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->UnexpectedException

UnknownHostException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

This RemoteException is thrown if the host specified during a Naming lookup cannot be found.

public class UnknownHostException extends RemoteException {
//	Public Constructors
	public UnknownHostException (String s);
	public UnknownHostException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->UnknownHostException

Thrown By: java.rmi.registry.RegistryHandler.registryStub()

UnmarshalException

Java 1.1

java.rmi

serializable checked PJ1.1(opt)

This RemoteException is thrown if an error occurs while unmarshalling the return value from a remote method call. The source of the error could be an I/O error while sending the header or the value of the return from the server to the client, or the fact that the class of the return object is not found.

public class UnmarshalException extends RemoteException {
//	Public Constructors
	public UnmarshalException (String s);
	public UnmarshalException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->UnmarshalException