FailoverHandler is a continuation that performs the failover procedure on a protocol session. As described in the class level comment for {@link AMQProtocolHandler}, a protocol connection can span many physical transport connections, failing over to a new connection if the transport connection fails. The procedure to establish a new connection is expressed as a continuation, in order that it may be run in a seperate thread to the i/o thread that detected the failure and is used to handle the communication to establish a new connection. The reason this needs to be a separate thread is because this work cannot be done inside the i/o processor thread. The significant task is the connection setup which involves a protocol exchange until a particular state is achieved. This procedure waits until the state is achieved which would prevent the i/o thread doing the work it needs to do to achieve the new state.
The failover procedure does the following:
- Sets the failing over condition to true.
- Creates a {@link FailoverException} and gets the protocol connection handler to propagate this event to allinterested parties.
- Takes the failover mutex on the protocol connection handler.
- Abandons the fail over if any of the interested parties vetoes it. The mutex is released and the condition reset.
- Creates a new {@link AMQStateManager} and re-established the connection through it.
- Informs the AMQConnection if the connection cannot be re-established.
- Recreates all sessions from the old connection to the new.
- Resets the failing over condition and releases the mutex.
CRC Card | Responsibilities | Collaborations |
|---|
| Update fail-over state | {@link AMQProtocolHandler} |
@todo The failover latch and mutex are used like a lock and condition. If the retrotranlator supports lock/conditionthen could change over to using them. 1.4 support still needed.
@todo If the condition is set to null on a vetoes fail-over and there are already other threads waiting on thecondition, they will never be released. It might be an idea to reset the condition in a finally block.
@todo Creates a {@link AMQDisconnectedException} and passes it to the AMQConnection. No need to use anexception-as-argument here, could just as easily call a specific method for this purpose on AMQConnection.
@todo Creates a {@link FailoverException} and propagates it to the MethodHandlers. No need to use anexception-as-argument here, could just as easily call a specific method for this purpose on {@link org.apache.qpid.protocol.AMQMethodListener}.