Transactional messaging allows for the coordinated outcome of otherwise independent transfers. This extends to an arbitrary number of transfers spread across any number of distinct links in either direction.
For every transactional interaction, one container acts as the transactional resource, and the other container acts as the transaction controller. The transactional resource performs transactional work as requested by the transaction controller.
The transactional controller and transactional resource communicate over a
control link which is established by the transactional controller. The
The container acting as the transactional resource defines a special target that functions
as a
To begin transactional work, the transaction controller needs to obtain a transaction
identifier from the resource. It does this by sending a message to the
If the declaration is successful, the coordinator responds with a disposition outcome of
If the coordinator was unable to perform the
Transaction controllers SHOULD establish a control link that allows the
The controller will conclude the transactional work by sending a
If the coordinator is unable to complete the
Transactional work is described in terms of the message states defined in
posting a message at a target, i.e., making it available
acquiring a message at a source, i.e., transitioning it to acquired
retiring a message at a source, i.e., applying the terminal outcome
The transactional resource performs these operations when triggered by the transaction controller:
posting messages is initiated by incoming
acquiring messages is initiated by incoming
retiring messages is initiated by incoming
In each case, it is the responsibility of the transaction controller to identify the
transaction with which the requested work is to be associated. This is done with the
transactional delivery state
The
If the transaction controller wishes to associate an outgoing
The effect of transactional posting is that the message does not become available at the destination node within the transactional resource until after the transaction has been successfully discharged.
On receiving a non-settled delivery associated with a live transaction, the transactional
resource MUST inform the controller of the presumptive terminal outcome before it can
successfully discharge the transaction. That is, the resource MUST send a
The transaction controller might wish to associate the outcome of a delivery with a
transaction. The delivery itself need not be associated with the same transaction as the
outcome, or indeed with any transaction at all. However, the delivery MUST NOT be associated
with a different non-discharged transaction than the outcome. If this happens then the
control link MUST be terminated with a
To associate an outcome with a transaction the controller sends a
On a successful
In the case of the
If the link endpoint does not support transactional acquisition, the link MUST be terminated
with a
While the txn-id is cleared when the transaction is discharged, this does not affect the level of outstanding credit. To prevent the sending link endpoint from acquiring outside of any transaction, the controller SHOULD ensure there is no outstanding credit at the sender before it discharges the transaction. The controller can do this by either setting the drain mode of the sending link endpoint to true before discharging the transaction, or by reducing the link-credit to zero, and waiting to hear back that the sender has seen this state change.
If a transaction is discharged at a point where a message has been transactionally acquired,
but has not been fully sent (i.e., the delivery of the message will require more than one
The transport layer defines a notion of settlement which refers to the point at which the association of a delivery-tag to a delivery attempt is forgotten. Transactions do not in themselves change this notion, however the fact that transactional work can be rolled back does have implications for deliveries which the endpoint has marked as settled (and for which it can therefore no longer exchange state information using the previously allocated transport level identifiers).
The delivered message will not be made available at the node until the transaction has been successfully discharged. If the transaction is rolled back then the delivery is not made available. If the resource is unable to process the delivery it MUST NOT allow the successful discharge of the associated transaction. This can be communicated by immediately destroying the controlling link on which the transaction was declared, or by rejecting any attempt to discharge the transaction where the fail flag is not set to true.
The resource MUST determine the outcome of the delivery before committing the
transaction, and this MUST be communicated to the controller before the acceptance of
a successful discharge. The outcome communicated by the resource MUST be associated
with the same transaction with which the
If the transaction is rolled back then the delivery is not made available at the target. If the resource can no longer apply the outcome that it originally indicated would be the result of a successful discharge then it MUST NOT allow the successful discharge of the associated transaction. This can be communicated by immediately destroying the controlling link on which the transaction was declared, or by rejecting any attempt to discharge the transaction where the fail flag is not set to true.
Behavior prior to discharge is the same as the previous case.
After a successful discharge, the state of unsettled deliveries at the resource MUST reflect the outcome that was applied. If the discharge was unsuccessful then an outcome SHOULD NOT be associated with the unsettled deliveries. The controller SHOULD settle any outstanding unsettled deliveries in a timely fashion after the transaction has discharged.
This section considers the cases where the resource has sent messages to the controller in
a non-transactional fashion. For the cases where the resource sends the messages
transactionally, see
Upon a successful discharge the outcome specified by the controller is applied at the source. If the controller requests a rollback or the discharge attempt be unsuccessful, then the outcome is not applied. At this point the controller can no longer influence the state of the delivery as it is settled, and the resource MUST apply the default outcome.
The resource might or might not settle the delivery before the transaction is discharged. If the resource settles the delivery before the discharge then the behavior after discharge is the same as the case above.
Upon a successful discharge the outcome is applied. Otherwise the state reverts to that which occurred before the controller sent its (transactional) disposition. The controller is free to update the state using subsequent transactional or non-transactional updates.
In the event of a successful discharge the outcome applies at the resource, otherwise the acquisition and outcome are rolled back.
An outcome sent by the controller before the transaction has discharged MUST be associated with the same transaction. In the even of a successful discharge the outcome is applied at the source, otherwise both the acquisition and outcome are rolled back.
The coordinator type defines a special target used for establishing a link with a transaction coordinator.
When sent by the transaction controller (the sending endpoint), indicates the desired
capabilities of the coordinator. When sent by the resource (the receiving endpoint),
defined the actual capabilities of the coordinator. Note that it is the responsibility
of the transaction controller to verify that the capabilities of the controller meet its
requirements. See
The declare type defines the message body sent to the coordinator to declare a
transaction. The txn-id allocated for this transaction is chosen by the transaction
controller and identified in the
Specifies that the txn-id allocated by this declare MUST be associated with the
indicated global transaction. If not set, the allocated txn-id will be associated with a
local transaction. This field MUST NOT be set if the coordinator does not have the
The discharge type defines the message body sent to the coordinator to indicate that the txn-id is no longer in use. If the transaction is not associated with a global-id, then this also indicates the disposition of the local transaction.
If set, this flag indicates that the work associated with this transaction has failed, and the controller wishes the transaction to be rolled back. If the transaction is associated with a global-id this will render the global transaction rollback-only. If the transaction is a local transaction, then this flag controls whether the transaction is committed or aborted when it is discharged. (Note that the specification for distributed transactions within AMQP 1.0 will be provided separately in Part 6 Distributed Transactions).
A transaction-id can be up to 32 octets of binary data.
Indicates that a transaction identifier has successfully been allocated in response to a declare message sent to a transaction coordinator.
The transactional-state type defines a delivery-state that is used to associate a delivery with a transaction as well as to indicate which outcome is to be applied if the transaction commits.
This field indicates the provisional outcome to be applied if the transaction commits.
Support local transactions.
Support AMQP Distributed Transactions.
Support AMQP Promotable Transactions.
Support multiple active transactions on a single session.
Support transactions whose txn-id is used across sessions on one connection.
The specified txn-id does not exist.
The transaction was rolled back for an unspecified reason.
The work represented by this transaction took too long.