Book Home Java Enterprise in a Nutshell Search this book

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

Figure 13-1. The java.rmi package

AccessExceptionJava 1.1
java.rmiserializable 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()}

AlreadyBoundExceptionJava 1.1
java.rmiserializable 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()

ConnectExceptionJava 1.1
java.rmiserializable 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

ConnectIOExceptionJava 1.1
java.rmiserializable 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

MarshalExceptionJava 1.1
java.rmiserializable 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

MarshalledObjectJava 1.2
java.rmiserializable

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()

NamingJava 1.1
java.rmiPJ1.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;
}
NoSuchObjectExceptionJava 1.1
java.rmiserializable 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()

NotBoundExceptionJava 1.1
java.rmiserializable 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()}

RemoteJava 1.1
java.rmiremote 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()

RemoteExceptionJava 1.1
java.rmiserializable 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.2public void printStackTrace ();
1.2public void printStackTrace (PrintStream ps);
1.2public 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.

RMISecurityExceptionJava 1.1; Deprecated in Java 1.2
java.rmiserializable 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 classJava 1.1
java.rmiPJ1.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 classJava 1.1
java.rmiserializable 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

ServerExceptionJava 1.1
java.rmiserializable 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

ServerRuntimeExceptionJava 1.1; Deprecated in Java 1.2
java.rmiserializable 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

StubNotFoundExceptionJava 1.1
java.rmiserializable 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

UnexpectedExceptionJava 1.1
java.rmiserializable 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

UnknownHostExceptionJava 1.1
java.rmiserializable 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()

UnmarshalExceptionJava 1.1
java.rmiserializable 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



Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.