weblogic.rmi.spi (Java API Reference for Oracle WebLogic Server)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Oracle Fusion Middleware
Java API Reference for Oracle WebLogic Server
12c (12.1.2)

Part Number E27170-01

PREV PACKAGE NEXT PACKAGE

FRAMES NO FRAMES

Package weblogic.rmi.spi

This package defines a Service Provider Interface (SPI) for RMI.

See:
Description

Interface Summary
Channel	Channel is used by the RMI runtime to represent the addressing information required to reach a process that hosts a remote object.
HostID	HostID is used by the RMI runtime to represent the process that hosts a remote object.

Package weblogic.rmi.spi Description

This package defines a Service Provider Interface (SPI) for RMI. The SPI is generally implemented by a protocol specific layer upon which RMI calls will be transported.

An Abstract Model for RMI

When a client makes RMI request it must identify the server to communicate with, the object on the server to invoke on and the method on the object to invoke. Once the target has been identified, an OutboundRequest must be constructed, arguments marshaled to the request and the request invoked. Once invoked an InboundResponse is returned from which a return value or exception is unmarshaled. As well as arguments, a request or response may carry out-of-band information such as transaction context or security principle.

Exception Semantics

The following explains the exceptions semantics to which RMI service providers and the runtime must conform.

All exceptions thrown by the RMI runtime or the underlying service provider durning the invocation of an RMI method conform to these semantics in a uniform way in order to ensure the proper handling of messages in the context of cluster aware, transactions and security. These semantics are all derived from the Java 1.3 RMI API docs and the Java 2 RMI Specification. It is essential that any RMI implementation (service provider) conform with this specification not only to provide clarity in error reporting but also to ensure that fail-over code operates correctly.

java.rmi.UnknownHostException Indicates that the caller was unable to connect to the server because it was unable to resolve the name of the server to an IP address. The caller can retry and still maintain at-most-once- semantics.

java.rmi.ConnectException Indicates that the caller was unable to connect to the server because the server did not accept the connection. The caller can and still maintain at-most-once semantics.

java.rmi.ConnectIOException Indicates that the call did not reach the server due to an IOException. The caller can retry and still maintain at-most-once semantics.

java.rmi.MarshalException Indicates that an Exception occurred either while marshalling the arguments for a remote call on the client or marshalling the return value of a remote call on the server. The RMI spec does not distinguish between these two case so the caller cannot retry and reliably maintain at-most-semantics.

java.rmi.NoSuchObjectException Indicates that the remote object on which the call was made is no longer available. The client can retry and maintain at-most-once semantics.

java.rmi.StubNotFoundException Indicates that the system was unable to find a stub for a remote object that was being passed as a parameter or returned as a result. This will be wrapped in a marshal exception if it occurs during a call.

java.rmi.UnmarshalException Indicates that an Exception occurred while unmarshalling parameters on the server side or unmarshalling the return value on the client side. The RMI spec does not distinguish between these two cases, so the caller cannot retry and reliably preserve at-most-once semantics. See proposed exceptions below.

java.rmi.ServerException Indicates that the implementation of remote method threw a RemoteException. The detail field of the ServerException is set to the exception that was raised. The RMI spec prohibits a Remote class implementation from explicitly throwing a RemoteException. RemoteExceptions are only to be thrown by the RMI runtime. But an object may throw a RemoteException as the result of calling another remote object. In this case, it is wrapped by a ServerException to clearly distinguish it from an Exception that occurred during the initial remote call. The EJB specification introduces two additional RemoteExceptions that can be thrown by the EJB container (javax.transaction.RollBackException). These are EJB contianer exceptions rather than RMI runtime This raises a problem with the EJB container which can may throw javax.transaction.RolledBackException (which is an extension of RemoteException. If the RMI runtime wraps any RemoteException thrown by the remote method in ServerException, it will end up wrapping RolledBackException, but this is incorrect. We must ensure that any RemoteException thrown by the EJB container (and not the EJB implementation itself) is not wrapped in a ServerException.

/** * Invoking a method on an object that is no longer exported should result in * a NoSuchObjectException. */

/** * ??? Invoking a method that results in an java.lang.Error on the server * should result in a ServerError with the detail field set to the original * Error. */

/** * Invoking a remote method that results in the server-side implementation * throwing a RemoteExeption should result is a ServerException containing * the original remote exception in its detail. */

/** * Attempting to export an rmi object for which no stub can be found * should result in a StubNotFoundException. This can occur either as * a result of explicitly exporting an object (UnicastRemoteObject.export), * as a result of a remote method call returning a remote object, or as * a result of passing a remote object as a parameter in a remote method. */

/** * Invoking a remote method on an object with an unrecognized * host should result in an UnknownHostException. This may occur if * an RMI reference refers to a server by a DNS name that cannot be * resolved. */

/** * Invoking a remote method with parameters that can't be deserialized * should result in an UnmarshalException. */

/** * Invoking a remote method that returns an value that can't be deserialized * should result in an UnmarshalException. */