org.apache.qpid.client.failover
Class FailoverRetrySupport<T,E extends Exception>

java.lang.Object
  extended by org.apache.qpid.client.failover.FailoverRetrySupport<T,E>
All Implemented Interfaces:
FailoverSupport<T,E>

public class FailoverRetrySupport<T,E extends Exception>
extends Object
implements FailoverSupport<T,E>

FailoverRetrySupport is a continuation that wraps another continuation, delaying its execution until it is notified that a blocking condition has been met, and executing the continuation within a mutex. If the continuation fails, due to the original condition being broken, whilst the continuation is waiting for a reponse to a synchronous request, FailoverRetrySupport automatcally rechecks the condition and re-acquires the mutex and re-runs the continution. This automatic retrying is continued until the continuation succeeds, or throws an exception (different to FailoverException, which is used to signal the failure of the original condition).

The blocking condition used is that the connection is not currently failing over, and the mutex used is the connection failover mutex, which guards against the fail-over process being run during fail-over vulnerable methods. These are used like a lock and condition variable.

The wrapped operation may throw a FailoverException, this is an exception that can be raised by a BlockingMethodFrameListener, in response to it being notified that a fail-over wants to start whilst it was waiting. Methods that are vulnerable to fail-over are those that are synchronous, where a failure will prevent them from getting the reply they are waiting for and asynchronous methods that should not be attempted when a fail-over is in progress.

Wrapping a synchronous method in a FailoverRetrySupport will have the effect that the operation will not be started during fail-over, but be delayed until any current fail-over has completed. Should a fail-over process want to start whilst waiting for the synchrnous reply, the FailoverRetrySupport will detect this and rety the operation until it succeeds. Synchronous methods are usually coordinated with a BlockingMethodFrameListener which is notified when a fail-over process wants to start and throws a FailoverException in response to this.

Wrapping an asynchronous method in a FailoverRetrySupport will have the effect that the operation will not be started during fail-over, but be delayed until any current fail-over has completed.

CRC Card
Responsibilities Collaborations
Provide a continuation synchronized on a fail-over lock and condition.
Automatically retry the continuation accross fail-overs until it succeeds, or raises an exception.

Todo:
Another continuation. Could use an interface Continuation (as described in other todos, for example, see Job). Then have a wrapping continuation (this), which blocks on an arbitrary Condition or Latch (specified in constructor call), that this blocks on before calling the wrapped Continuation. Must work on Java 1.4, so check retrotranslator works on Lock/Condition or latch first. Argument and return type to match wrapped condition as type parameters. Rename to AsyncConditionalContinuation or something like that., InterruptedException not handled well.

Field Summary
(package private)  AMQConnection connection
          The connection on which the fail-over protected operation is to be performed.
(package private)  FailoverProtectedOperation<T,E> operation
          The protected operation that is to be retried in the event of fail-over.
 
Constructor Summary
FailoverRetrySupport(FailoverProtectedOperation<T,E> operation, AMQConnection con)
          Creates an automatic retrying fail-over handler for the specified operation.
 
Method Summary
 T execute()
          Delays a continuation until the "not failing over" condition is met on the specified connection.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

operation

FailoverProtectedOperation<T,E extends Exception> operation
The protected operation that is to be retried in the event of fail-over.


connection

AMQConnection connection
The connection on which the fail-over protected operation is to be performed.

Constructor Detail

FailoverRetrySupport

public FailoverRetrySupport(FailoverProtectedOperation<T,E> operation,
                            AMQConnection con)
Creates an automatic retrying fail-over handler for the specified operation.

Parameters:
operation - The fail-over protected operation to wrap in this handler.
Method Detail

execute

public T execute()
          throws E extends Exception
Delays a continuation until the "not failing over" condition is met on the specified connection. Repeats until the operation throws AMQException or succeeds without being interrupted by fail-over.

Specified by:
execute in interface FailoverSupport<T,E extends Exception>
Returns:
The result of executing the continuation.
Throws:
E - Any underlying exception is allowed to fall through.
E extends Exception


Licensed to the Apache Software Foundation