org.apache.qpid.client.protocol

Class AMQProtocolHandler

java.lang.Object

org.apache.qpid.client.protocol.AMQProtocolHandler

All Implemented Interfaces:

ProtocolEngine, TransportActivity, Receiver<ByteBuffer>

public class AMQProtocolHandler
extends Object
implements ProtocolEngine

AMQProtocolHandler is the client side protocol handler for AMQP, it handles all protocol events received from the network by MINA. The primary purpose of AMQProtocolHandler is to translate the generic event model of MINA into the specific event model of AMQP, by revealing the type of the received events (from decoded data), and passing the event on to more specific handlers for the type. In this sense, it channels the richer event model of AMQP, expressed in terms of methods and so on, through the cruder, general purpose event model of MINA, expressed in terms of "message received" and so on.

There is a 1:1 mapping between an AMQProtocolHandler and an AMQConnection. The connection class is exposed to the end user of the AMQP client API, and also implements the JMS Connection API, so provides the public API calls through which an individual connection can be manipulated. This protocol handler talks to the network through MINA, in a behind the scenes role; it is not an exposed part of the client API.

There is a 1:many mapping between an AMQProtocolHandler and a set of AMQSessions. At the MINA level, there is one session per connection. At the AMQP level there can be many channels which are also called sessions in JMS parlance. The AMQSessions are managed through an AMQProtocolSession instance. The protocol session is similar to the MINA per-connection session, except that it can span the lifecycle of multiple MINA sessions in the event of failover. See below for more information about this.

Mina provides a session container that can be used to store/retrieve arbitrary objects as String named attributes. A more convenient, type-safe, container for session data is provided in the form of AMQProtocolSession.

A common way to use MINA is to have a single instance of the event handler, and for MINA to pass in its session object with every event, and for per-connection data to be held in the MINA session (perhaps using a type-safe wrapper as described above). This event handler is different, because dealing with failover complicates things. To the end client of an AMQConnection, a failed over connection is still handled through the same connection instance, but behind the scenes a new transport connection, and MINA session will have been created. The MINA session object cannot be used to track the state of the fail-over process, because it is destroyed and a new one is created, as the old connection is shutdown and a new one created. For this reason, an AMQProtocolHandler is created per AMQConnection and the protocol session data is held outside of the MINA IOSession.

This handler is responsible for setting up the filter chain to filter all events for this handler through. The filter chain is set up as a stack of event handers that perform the following functions (working upwards from the network traffic at the bottom), handing off incoming events to an asynchronous thread pool to do the work, optionally handling secure sockets encoding/decoding, encoding/decoding the AMQP format itself.

TODO Use a single handler instance, by shifting everything to do with the 'protocol session' state, including failover state, into AMQProtocolSession, and tracking that from AMQConnection? The lifecycles of AMQProtocolSesssion and AMQConnection will be the same, so if there is high cohesion between them, they could be merged, although there is sense in keeping the session model separate. Will clarify things by having data held per protocol handler, per protocol session, per network connection, per channel, in separate classes, so that lifecycles of the fields match lifecycles of their containing objects.

Constructor Summary

Constructors

Constructor and Description
AMQProtocolHandler(AMQConnection con) Creates a new protocol handler, associated with the specified client connection instance.

Method Summary

Methods

Modifier and Type	Method and Description
void	blockUntilNotFailingOver()
void	closeConnection(long timeout) Closes the connection.
void	closed() Called when the network connection is closed.
void	closeSession(AMQSession session)
StateWaiter	createWaiter(Set<AMQState> states)
void	exception(Throwable cause) Invoked when any exception is thrown by the NetworkDriver
void	failover(String host, int port)
void	failoverInProgress()
AMQShortString	generateQueueName()
AMQConnection	getConnection()
CountDownLatch	getFailoverLatch()
long	getLastReadTime()
long	getLastWriteTime()
SocketAddress	getLocalAddress()
MethodRegistry	getMethodRegistry()
NetworkConnection	getNetworkConnection()
byte	getProtocolMajorVersion()
byte	getProtocolMinorVersion()
AMQProtocolSession	getProtocolSession()
ProtocolVersion	getProtocolVersion()
long	getReadBytes()
SocketAddress	getRemoteAddress()
protected Sender<ByteBuffer>	getSender()
AMQStateManager	getStateManager()
ProtocolVersion	getSuggestedProtocolVersion()
long	getWrittenBytes()
void	heartbeatBodyReceived()
void	methodBodyReceived(int channelId, AMQBody bodyFrame)
void	notifyFailoverStarting()
void	propagateExceptionToAllWaiters(Exception e) There are two cases where we have other threads potentially blocking for events to be handled by this class.
void	propagateExceptionToFrameListeners(Exception e) This caters for the case where we only need to propagate an exception to the the frame listeners to interupt any protocol level waits.
void	readerIdle()
void	received(ByteBuffer msg)
void	setFailoverLatch(CountDownLatch failoverLatch)
void	setFailoverState(FailoverState failoverState)
void	setHeartbeatListener(HeartbeatListener listener)
void	setMaxFrameSize(long frameMax)
void	setNetworkConnection(NetworkConnection network)
void	setNetworkConnection(NetworkConnection network, Sender<ByteBuffer> sender)
void	setStateManager(AMQStateManager stateManager)
AMQMethodEvent	syncWrite(AMQFrame frame, Class responseClass) More convenient method to write a frame and wait for it's response.
AMQMethodEvent	syncWrite(AMQFrame frame, Class responseClass, long timeout) More convenient method to write a frame and wait for it's response.
AMQMethodEvent	writeCommandFrameAndWaitForReply(AMQFrame frame, BlockingMethodFrameListener listener) Convenience method that writes a frame to the protocol session and waits for a particular response.
AMQMethodEvent	writeCommandFrameAndWaitForReply(AMQFrame frame, BlockingMethodFrameListener listener, long timeout) Convenience method that writes a frame to the protocol session and waits for a particular response.
void	writeFrame(AMQDataBlock frame)
void	writeFrame(AMQDataBlock frame, boolean flush)
void	writerIdle()

Methods inherited from class java.lang.Object

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

Constructor Detail

AMQProtocolHandler

public AMQProtocolHandler(AMQConnection con)

Creates a new protocol handler, associated with the specified client connection instance.

Parameters:

con - The client connection that this is the event handler for.

Method Detail

closed

public void closed()

Called when the network connection is closed. This can happen, either because the client explicitly requested that the connection be closed, in which case nothing is done, or because the connection died. In the case where the connection died, an attempt to failover automatically to a new connection may be started. The failover process will be started, provided that it is the clients policy to allow failover, and provided that a failover has not already been started or failed.

TODO Clarify: presumably exceptionCaught is called when the client is sending during a connection failure and not otherwise? The above comment doesn't make that clear.

Specified by:

closed in interface ProtocolEngine

Specified by:

closed in interface Receiver<ByteBuffer>

readerIdle

public void readerIdle()

Specified by:

readerIdle in interface ProtocolEngine

Specified by:

readerIdle in interface TransportActivity

writerIdle

public void writerIdle()

Specified by:

writerIdle in interface ProtocolEngine

Specified by:

writerIdle in interface TransportActivity

exception

public void exception(Throwable cause)

Invoked when any exception is thrown by the NetworkDriver

Specified by:

exception in interface Receiver<ByteBuffer>

propagateExceptionToAllWaiters

public void propagateExceptionToAllWaiters(Exception e)

There are two cases where we have other threads potentially blocking for events to be handled by this class. These are for the state manager (waiting for a state change) or a frame listener (waiting for a particular type of frame to arrive). When an error occurs we need to notify these waiters so that they can react appropriately. This should be called only when the exception is fatal for the connection.

Parameters:

e - the exception to propagate

See Also:

propagateExceptionToFrameListeners(java.lang.Exception)

propagateExceptionToFrameListeners

public void propagateExceptionToFrameListeners(Exception e)

This caters for the case where we only need to propagate an exception to the the frame listeners to interupt any protocol level waits. This will would normally be used to notify all Frame Listeners that Failover is about to occur and they should stop waiting and relinquish the Failover lock. See FailoverHandler. Once the FailoverHandler has re-established the connection then the listeners will be able to re-attempt their protocol request and so listen again for the correct frame.

Parameters:

e - the exception to propagate

notifyFailoverStarting

public void notifyFailoverStarting()

failoverInProgress

public void failoverInProgress()

received

public void received(ByteBuffer msg)

Specified by:

received in interface Receiver<ByteBuffer>

methodBodyReceived

public void methodBodyReceived(int channelId,
                      AMQBody bodyFrame)
                        throws AMQException

Throws:

AMQException

createWaiter

public StateWaiter createWaiter(Set<AMQState> states)
                         throws AMQException

Throws:

AMQException

writeFrame

public void writeFrame(AMQDataBlock frame)

writeFrame

public void writeFrame(AMQDataBlock frame,
              boolean flush)

writeCommandFrameAndWaitForReply

public AMQMethodEvent writeCommandFrameAndWaitForReply(AMQFrame frame,
                                              BlockingMethodFrameListener listener)
                                                throws AMQException,
                                                       FailoverException

Convenience method that writes a frame to the protocol session and waits for a particular response. Equivalent to calling getProtocolSession().write() then waiting for the response.

Parameters:

frame -

listener - the blocking listener. Note the calling thread will block.

Throws:

AMQException

FailoverException

writeCommandFrameAndWaitForReply

public AMQMethodEvent writeCommandFrameAndWaitForReply(AMQFrame frame,
                                              BlockingMethodFrameListener listener,
                                              long timeout)
                                                throws AMQException,
                                                       FailoverException

Convenience method that writes a frame to the protocol session and waits for a particular response. Equivalent to calling getProtocolSession().write() then waiting for the response.

Parameters:

frame -

listener - the blocking listener. Note the calling thread will block.

Throws:

AMQException

FailoverException

syncWrite

public AMQMethodEvent syncWrite(AMQFrame frame,
                       Class responseClass)
                         throws AMQException,
                                FailoverException

More convenient method to write a frame and wait for it's response.

Throws:

AMQException

FailoverException

syncWrite

public AMQMethodEvent syncWrite(AMQFrame frame,
                       Class responseClass,
                       long timeout)
                         throws AMQException,
                                FailoverException

More convenient method to write a frame and wait for it's response.

Throws:

AMQException

FailoverException

closeSession

public void closeSession(AMQSession session)
                  throws AMQException

Throws:

AMQException

closeConnection

public void closeConnection(long timeout)
                     throws AMQException

Closes the connection.

If a failover exception occurs whilst closing the connection it is ignored, as the connection is closed anyway.

Parameters:

timeout - The timeout to wait for an acknowledgment to the close request.

Throws:

AMQException - If the close fails for any reason.

getReadBytes

public long getReadBytes()

Specified by:

getReadBytes in interface ProtocolEngine

Returns:

the number of bytes read from this protocol session

getWrittenBytes

public long getWrittenBytes()

Specified by:

getWrittenBytes in interface ProtocolEngine

Returns:

the number of bytes written to this protocol session

failover

public void failover(String host,
            int port)

blockUntilNotFailingOver

public void blockUntilNotFailingOver()
                              throws InterruptedException

Throws:

InterruptedException

generateQueueName

public AMQShortString generateQueueName()

getFailoverLatch

public CountDownLatch getFailoverLatch()

setFailoverLatch

public void setFailoverLatch(CountDownLatch failoverLatch)

getConnection

public AMQConnection getConnection()

getStateManager

public AMQStateManager getStateManager()

setStateManager

public void setStateManager(AMQStateManager stateManager)

getProtocolSession

public AMQProtocolSession getProtocolSession()

setFailoverState

public void setFailoverState(FailoverState failoverState)

getProtocolMajorVersion

public byte getProtocolMajorVersion()

getProtocolMinorVersion

public byte getProtocolMinorVersion()

getMethodRegistry

public MethodRegistry getMethodRegistry()

getProtocolVersion

public ProtocolVersion getProtocolVersion()

getRemoteAddress

public SocketAddress getRemoteAddress()

Specified by:

getRemoteAddress in interface ProtocolEngine

getLocalAddress

public SocketAddress getLocalAddress()

Specified by:

getLocalAddress in interface ProtocolEngine

setNetworkConnection

public void setNetworkConnection(NetworkConnection network)

setNetworkConnection

public void setNetworkConnection(NetworkConnection network,
                        Sender<ByteBuffer> sender)

Specified by:

setNetworkConnection in interface ProtocolEngine

getLastReadTime

public long getLastReadTime()

Specified by:

getLastReadTime in interface TransportActivity

getLastWriteTime

public long getLastWriteTime()

Specified by:

getLastWriteTime in interface TransportActivity

getSender

protected Sender<ByteBuffer> getSender()

getNetworkConnection

public NetworkConnection getNetworkConnection()

getSuggestedProtocolVersion

public ProtocolVersion getSuggestedProtocolVersion()

setHeartbeatListener

public void setHeartbeatListener(HeartbeatListener listener)

heartbeatBodyReceived

public void heartbeatBodyReceived()

setMaxFrameSize

public void setMaxFrameSize(long frameMax)