RmiClientInterceptorUtils (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.remoting.rmi

## Class RmiClientInterceptorUtils

- java.lang.Object
- - org.springframework.remoting.rmi.RmiClientInterceptorUtils

-     public abstract class RmiClientInterceptorUtils
      extends Object

  Factored-out methods for performing invocations within an RMI client. Can handle both RMI and non-RMI service interfaces working on an RMI stub.

  Note: This is an SPI class, not intended to be used by applications.

  Since:
    1.1
  Author:
    Juergen Hoeller

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `RmiClientInterceptorUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Exception` | `convertRmiAccessException(Method method, RemoteException ex, boolean isConnectFailure, String serviceName)` Convert the given RemoteException that happened during remote access to Spring's RemoteAccessException if the method signature does not support RemoteException.
    `static Exception` | `convertRmiAccessException(Method method, RemoteException ex, String serviceName)` Convert the given RemoteException that happened during remote access to Spring's RemoteAccessException if the method signature does not support RemoteException.
    `static Exception` | `convertRmiAccessException(Method method, Throwable ex, String message)` Wrap the given arbitrary exception that happened during remote access in either a RemoteException or a Spring RemoteAccessException (if the method signature does not support RemoteException).
    `static Object` | `doInvoke(MethodInvocation invocation, Remote stub)` Deprecated. as of Spring 2.5, in favor of `invokeRemoteMethod(org.aopalliance.intercept.MethodInvocation, java.lang.Object)`
    `static Object` | `invoke(MethodInvocation invocation, Remote stub, String serviceName)` Deprecated. as of Spring 2.5, in favor of `invokeRemoteMethod(org.aopalliance.intercept.MethodInvocation, java.lang.Object)`
    `static Object` | `invokeRemoteMethod(MethodInvocation invocation, Object stub)` Perform a raw method invocation on the given RMI stub, letting reflection exceptions through as-is.
    `static boolean` | `isConnectFailure(RemoteException ex)` Determine whether the given RMI exception indicates a connect failure.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### RmiClientInterceptorUtils

          public RmiClientInterceptorUtils()

  - ### Method Detail

    - #### invoke

          @Deprecated
          public static Object invoke(MethodInvocation invocation,
                                 Remote stub,
                                 String serviceName)
                               throws Throwable

      Deprecated. as of Spring 2.5, in favor of `invokeRemoteMethod(org.aopalliance.intercept.MethodInvocation, java.lang.Object)`
      Apply the given method invocation to the given RMI stub.

      Delegates to the corresponding method if the RMI stub does not directly implement the invoked method. This typically happens when a non-RMI service interface is used for an RMI service. The methods of such a service interface have to match the RMI stub methods, but they typically don't declare `java.rmi.RemoteException`: A RemoteException thrown by the RMI stub will be automatically converted to Spring's RemoteAccessException.

      Throws:
        `Throwable`

    - #### doInvoke

          @Deprecated
          public static Object doInvoke(MethodInvocation invocation,
                                   Remote stub)
                                 throws InvocationTargetException

      Deprecated. as of Spring 2.5, in favor of `invokeRemoteMethod(org.aopalliance.intercept.MethodInvocation, java.lang.Object)`
      Perform a raw method invocation on the given RMI stub, letting reflection exceptions through as-is.
      Throws:
        `InvocationTargetException`

    - #### invokeRemoteMethod

          public static Object invokeRemoteMethod(MethodInvocation invocation,
                                  Object stub)
                                           throws InvocationTargetException

      Perform a raw method invocation on the given RMI stub, letting reflection exceptions through as-is.
      Parameters:
        `invocation` - the AOP MethodInvocation
        `stub` - the RMI stub
      Returns:
        the invocation result, if any
      Throws:
        `InvocationTargetException` - if thrown by reflection

    - #### convertRmiAccessException

          public static Exception convertRmiAccessException(Method method,
                                            Throwable ex,
                                            String message)

      Wrap the given arbitrary exception that happened during remote access in either a RemoteException or a Spring RemoteAccessException (if the method signature does not support RemoteException).

      Only call this for remote access exceptions, not for exceptions thrown by the target service itself!

      Parameters:
        `method` - the invoked method
        `ex` - the exception that happened, to be used as cause for the RemoteAccessException or RemoteException
        `message` - the message for the RemoteAccessException respectively RemoteException
      Returns:
        the exception to be thrown to the caller

    - #### convertRmiAccessException

          public static Exception convertRmiAccessException(Method method,
                                            RemoteException ex,
                                            String serviceName)

      Convert the given RemoteException that happened during remote access to Spring's RemoteAccessException if the method signature does not support RemoteException. Else, return the original RemoteException.
      Parameters:
        `method` - the invoked method
        `ex` - the RemoteException that happened
        `serviceName` - the name of the service (for debugging purposes)
      Returns:
        the exception to be thrown to the caller

    - #### convertRmiAccessException

          public static Exception convertRmiAccessException(Method method,
                                            RemoteException ex,
                                            boolean isConnectFailure,
                                            String serviceName)

      Convert the given RemoteException that happened during remote access to Spring's RemoteAccessException if the method signature does not support RemoteException. Else, return the original RemoteException.
      Parameters:
        `method` - the invoked method
        `ex` - the RemoteException that happened
        `isConnectFailure` - whether the given exception should be considered a connect failure
        `serviceName` - the name of the service (for debugging purposes)
      Returns:
        the exception to be thrown to the caller

    - #### isConnectFailure

          public static boolean isConnectFailure(RemoteException ex)

      Determine whether the given RMI exception indicates a connect failure.

      Treats RMI's ConnectException, ConnectIOException, UnknownHostException, NoSuchObjectException and StubNotFoundException as connect failure, as well as Oracle's OC4J `com.evermind.server.rmi.RMIConnectionException` (which doesn't derive from from any well-known RMI connect exception).

      Parameters:
        `ex` - the RMI exception to check
      Returns:
        whether the exception should be treated as connect failure
      See Also:
        `ConnectException`, `ConnectIOException`, `UnknownHostException`, `NoSuchObjectException`, `StubNotFoundException`