Sessions are a uniquely identified conversation between a client and the broker. Multiple distinct sessions can share the same connection to the broker. An application process can also have multiple connections open to a broker.
All the interaction with a broker is done by issuing commands on a session. The valid commands are defined by the AMQP specification and include operations for declaring a queue and transferring a message. The broker can also be asked to indicate when it completes commands. This allows clients to confirm successful execution.
To receive messages from the broker, the client subscribes to a queue. The broker will then deliver available messages for that subscription.
Message acquisition and acceptance occurs as a transfer of ownership of a message.
By acquiring a message, a subscriber is given the option to take ownership of that message. A message can be acquired by only one subscriber at any time. While a message is acquired by a subscriber, the broker can not give it to any other. The subscriber can then confirm that it wishes to accept ownership of any acquired message by accepting that message. At this point the broker relinquishes ownership and permanently removes the message from the queue.
A subscriber might choose not to take ownership of an acquired message. In this case, the message is released. This allows the broker to re-deliver the message to any other available subscriber - this can include the subscriber that just released the message.
Acquired messages can also be
rejected. This tells the broker that the message is not valid for further delivery and should be
dead-lettered or discarded. See
Rejected and orphaned messages for more information on rejected messages.
The default acquire mode for a subscription is the pre-acquired mode. In this mode, delivered messages are implicitly acquired by the subscriber that receives them. Alternatively, a subscriber can use the not-acquired mode. This allows the subscriber to request that it is sent messages that are on the queue without acquiring them. Messages can then be acquired explicitly.
In addition to the acquire mode, a subscription can also set an accept mode. In the explicit mode, ownership of a message is transferred to the acquiring subscriber only when the message has been explicitly accepted. Alternatively, if the accept mode is set to none, messages are considered accepted as soon as they are acquired. This mode is less reliable, but is often suitable where message loss on session failure poses no risk to the system.
A subscriber can control the flow of messages from a subscribed queue by allocating credit to the broker for a particular number of messages or a total size of message content. As the broker delivers messages it spends this credit by decrementing the message credit by one and decrementing the size credit by the size of the content of the message. The broker cannot send a message to a subscription for which it does not have sufficient credit.
There are two modes of credit allocation defined by the AMQP specification:
In credit mode, credit must be explicitly re-issued by the subscriber before the broker can recommence sending messages
In window mode, the credit is automatically reissued for received messages. In this mode, the client indicates that a message has been received by informing the broker of the completion of the transfer. Though completion is essentially a form of acknowledgement, it should not be confused with acceptance which is an confirmation of ownership transfer.
In both modes, unlimited credit can be allocated for the message count and the total content size.
