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 {@link 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 {@link AMQSession}s. 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 {@link AMQSession}s are managed through an {@link AMQProtocolSession} instance. The protocolsession 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 {@link 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.
CRC Card | Responsibilities | Collaborations |
|---|
| Maintain fail-over state. |
| |
@todo Use a single handler instance, by shifting everything to do with the 'protocol session' state, includingfailover 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.