com.healthmarketscience.rmiio
Class RemoteWrapper<RemoteType>

java.lang.Object
  com.healthmarketscience.rmiio.RemoteWrapper<RemoteType>

All Implemented Interfaces:

RemoteClient, InvocationHandler

Direct Known Subclasses:

RemoteInputStreamWrapper, RemoteOutputStreamWrapper

public class RemoteWrapper<RemoteType>
extends Object
implements InvocationHandler, RemoteClient

Base class for implementing remote stub wrappers with builtin retry policies. Providers of remote interfaces can generate simple wrappers for use by a remote client which handle the retry functionality under the hood, simplifying client code dramatically. Note that this should only be done for idempotent method calls. See RemoteInputStreamWrapper and RemoteOutputStreamWrapper for example usage.

While subclassing presents an ability to fine tune the wrapper implementation, it may be difficult and/or unnecessary for many interfaces. In that case, a much simpler wrapper can be created using the wrap(java.lang.Class, R, com.healthmarketscience.rmiio.RemoteRetry, org.apache.commons.logging.Log) method, which uses the java Proxy functionality to generate the wrapper implementation at run time. This may be slightly less efficient than a custom implementation since reflection is used for the actual method invocations, but for remote method calls that overhead is probably meaningless.

Author:

James Ahlborn

Field Summary

protected org.apache.commons.logging.Log	_log the log which will be used by the retry facility when making the remote calls
protected RemoteRetry	_retry the retry policy we are using for our remote calls
protected RemoteType	_stub the handle to the remote interface which will do the real work of the remote method calls

Fields inherited from interface com.healthmarketscience.rmiio.RemoteClient

DEFAULT_RETRY

Constructor Summary

RemoteWrapper(RemoteType stub, RemoteRetry retry, org.apache.commons.logging.Log log)

Method Summary

org.apache.commons.logging.Log	getLog()
RemoteRetry	getRemoteRetry()
RemoteType	getStub()
static RemoteWrapper<?>	getWrapper(Object proxy) Gets the wrapper underlying a proxy created by a call to wrap(java.lang.Class, R, com.healthmarketscience.rmiio.RemoteRetry, org.apache.commons.logging.Log).
Object	invoke(Object proxy, Method method, Object[] args)
void	setRemoteRetry(RemoteRetry retry) Sets the client side RemoteRetry policy to use for the underlying remote communication layer.
static <R> R	wrap(Class<R> iface, R stub, RemoteRetry retry, org.apache.commons.logging.Log log) Simple wrapper generator which creates a Proxy for the given remote interface.

Methods inherited from class java.lang.Object

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

Field Detail

_stub

protected final RemoteType _stub

the handle to the remote interface which will do the real work of the remote method calls

_retry

protected RemoteRetry _retry

the retry policy we are using for our remote calls

_log

protected final org.apache.commons.logging.Log _log

the log which will be used by the retry facility when making the remote calls

Constructor Detail

RemoteWrapper

public RemoteWrapper(RemoteType stub,
                     RemoteRetry retry,
                     org.apache.commons.logging.Log log)

Method Detail

wrap

public static <R> R wrap(Class<R> iface,
                         R stub,
                         RemoteRetry retry,
                         org.apache.commons.logging.Log log)

Simple wrapper generator which creates a Proxy for the given remote interface. This proxy will make all the remote calls through the invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object[]) method which makes the actual method calls on the underlying stub within the retry logic.

Parameters:

iface - the remote interface to be implemented

stub - the underlying implementation of the remote interface which will actually make the remote calls

retry - the retry policy to use for the remote calls

log - the log to use during retry handling

Returns:

a proxy for the given interface using the given retry strategy

getWrapper

public static RemoteWrapper<?> getWrapper(Object proxy)

Gets the wrapper underlying a proxy created by a call to wrap(java.lang.Class, R, com.healthmarketscience.rmiio.RemoteRetry, org.apache.commons.logging.Log).

getStub

public RemoteType getStub()

getLog

public org.apache.commons.logging.Log getLog()

getRemoteRetry

public RemoteRetry getRemoteRetry()

setRemoteRetry

public void setRemoteRetry(RemoteRetry retry)

Sets the client side RemoteRetry policy to use for the underlying remote communication layer. For most client side implementations, this method must be called before any other calls on this client object (any calls to this method after one of those methods is called will have no affect).

This may be useful for temporarily changing the retry policy for a specific set of calls (e.g. a startup/discovery sequence may be more forgiving than normal usage).

Note, this method is not thread-safe as this should only be used on a wrapper for which the caller has exclusive ownership (the retry policy will be changed for all users of the wrapper).

Specified by:

setRemoteRetry in interface RemoteClient

Parameters:

retry - the new RemoteRetry policy to use for remote communication. null causes the RemoteClient.DEFAULT_RETRY policy to be used.

invoke

public Object invoke(Object proxy,
                     Method method,
                     Object[] args)
              throws Throwable

Specified by:

invoke in interface InvocationHandler

Throws:

Throwable