org.apache.qpid.client.util
Class BlockingWaiter<T>

java.lang.Object
  extended by org.apache.qpid.client.util.BlockingWaiter<T>
Direct Known Subclasses:
BlockingMethodFrameListener, StateWaiter

public abstract class BlockingWaiter<T>
extends Object

BlockingWaiter is a 'rendezvous' which delegates handling of incoming Objects to a listener implemented as a sub-class of this and hands off the process or error to a consumer. The producer of the event does not have to wait for the consumer to take the event, so this differs from a 'rendezvous' in that sense.

BlockingWaiters are used to coordinate when waiting for an an event that expect a response. They are always used in a 'one-shot' manner, that is, to recieve just one response. Usually the caller has to register them as method listeners with an event dispatcher and remember to de-register them (in a finally block) once they have been completed.

The process(T) must return true on any incoming method that it handles. This indicates to this listeners that the object just processed ends the waiting process.

Errors from the producer are rethrown to the consumer.

CRC Card
Responsibilities Collaborations
Accept generic objects as events for processing via process(T).
Delegate handling and undserstanding of the object to a concrete implementation.
Block until process(T) determines that waiting is no longer required
Propagate the most recent exception to the consumer.

Todo:
Interuption is caught but not handled. This could be allowed to fall through. This might actually be usefull for fail-over where a thread is blocking when failure happens, it could be interrupted to abandon or retry when this happens. At the very least, restore the interrupted status flag., If the retrotranslator can handle it, could use a SynchronousQueue to implement this rendezvous. Need to check that SynchronousQueue has a non-blocking put method available.

Field Summary
protected  Object _doneObject
          Holds the incomming Object.
 
Constructor Summary
BlockingWaiter()
           
 
Method Summary
 Object block(long timeout)
          Blocks until an object is received that is handled by process, or the specified timeout has passed.
 void close()
          Close this Waiter so that no more errors are processed.
 void error(Exception e)
          This is a callback, called when an error has occured that should interupt any waiter.
abstract  boolean process(T object)
          Delegates processing of the incomming object to the handler.
 boolean received(T object)
          An Object has been received and should be processed to see if our wait condition has been reached.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

_doneObject

protected Object _doneObject
Holds the incomming Object.

Constructor Detail

BlockingWaiter

public BlockingWaiter()
Method Detail

process

public abstract boolean process(T object)
Delegates processing of the incomming object to the handler.

Parameters:
object - The object to process.
Returns:
true if the waiting is complete, false if waiting should continue.

received

public boolean received(T object)
An Object has been received and should be processed to see if our wait condition has been reached.

Parameters:
object - The object received.
Returns:
true if the waiting is complete, false if waiting should continue.

block

public Object block(long timeout)
             throws org.apache.qpid.AMQException,
                    FailoverException
Blocks until an object is received that is handled by process, or the specified timeout has passed. Once closed any attempt to wait will throw an exception.

Parameters:
timeout - The timeout in milliseconds.
Returns:
The object that resolved the blocking.
Throws:
org.apache.qpid.AMQException
FailoverException

error

public void error(Exception e)
This is a callback, called when an error has occured that should interupt any waiter. It is also called from within this class to avoid code repetition but it should only be called by the MINA threads. Once closed any notification of an exception will be ignored.

Parameters:
e - The exception being propogated.

close

public void close()
Close this Waiter so that no more errors are processed. This is a preventative method to ensure that a second error thread does not get stuck in the error method after the await has returned. This has not happend but in practise but if two errors occur on the Connection at the same time then it is conceiveably possible for the second to get stuck if the first one is processed by a waiter. Once closed any attempt to wait will throw an exception. Any notification of an exception will be ignored.



Licensed to the Apache Software Foundation