Google Git
Sign in
apache / qpid-site / 255aeca4bd52dc8a8e5d341d49d795b3c3d54f38 / . / misc / amqp / transactions.xml
blob: 1159762160ffddebb3927c4ba05bf07f4c59c1c5 [file] [log] [blame]
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="amqp.xsl"?>
<!--
Copyright Notice
================
(c) Copyright Bank of America, N.A., Barclays Bank PLC, Cisco Systems, Credit Suisse, Deutsche
Boerse, Envoy Technologies Inc., Goldman Sachs, HCL Technologies Ltd, IIT Software GmbH, iMatix
Corporation, INETCO Systems Limited, Informatica Corporation, JPMorgan Chase & Co., Kaazing
Corporation, N.A, Microsoft Corporation, my-Channels, Novell, Progress Software, Red Hat Inc.,
Software AG, Solace Systems Inc., StormMQ Ltd., Tervela Inc., TWIST Process Innovations Ltd,
VMware, Inc., and WS02 Inc.
2006-2011. All rights reserved.
License
=======
Bank of America, N.A., Barclays Bank PLC, Cisco Systems, Credit Suisse, Deutsche Boerse, Goldman
Sachs, HCL Technologies Ltd, IIT Software GmbH, INETCO Systems Limited, Informatica Corporation,
JPMorgan Chase & Co., Kaazing Corporation, N.A, Microsoft Corporation, my-Channels, Novell,
Progress Software, Red Hat Inc., Software AG, Solace Systems Inc., StormMQ Ltd., Tervela Inc.,
TWIST Process Innovations Ltd, VMware, Inc., and WS02 Inc. (collectively, the "Authors") each
hereby grants to you a worldwide, perpetual, royalty-free, nontransferable, nonexclusive license
to (i) copy, display, distribute and implement the Advanced Message Queuing Protocol ("AMQP")
Specification and (ii) the Licensed Claims that are held by the Authors, all for the purpose of
implementing the Advanced Message Queuing Protocol Specification. Your license and any rights
under this Agreement will terminate immediately without notice from any Author if you bring any
claim, suit, demand, or action related to the Advanced Message Queuing Protocol Specification
against any Author. Upon termination, you shall destroy all copies of the Advanced Message Queuing
Protocol Specification in your possession or control.
As used hereunder, "Licensed Claims" means those claims of a patent or patent application,
throughout the world, excluding design patents and design registrations, owned or controlled, or
that can be sublicensed without fee and in compliance with the requirements of this Agreement, by
an Author or its affiliates now or at any future time and which would necessarily be infringed by
implementation of the Advanced Message Queuing Protocol Specification. A claim is necessarily
infringed hereunder only when it is not possible to avoid infringing it because there is no
plausible non-infringing alternative for implementing the required portions of the Advanced
Message Queuing Protocol Specification. Notwithstanding the foregoing, Licensed Claims shall not
include any claims other than as set forth above even if contained in the same patent as Licensed
Claims; or that read solely on any implementations of any portion of the Advanced Message Queuing
Protocol Specification that are not required by the Advanced Message Queuing Protocol
Specification, or that, if licensed, would require a payment of royalties by the licensor to
unaffiliated third parties. Moreover, Licensed Claims shall not include (i) any enabling
technologies that may be necessary to make or use any Licensed Product but are not themselves
expressly set forth in the Advanced Message Queuing Protocol Specification (e.g., semiconductor
manufacturing technology, compiler technology, object oriented technology, networking technology,
operating system technology, and the like); or (ii) the implementation of other published
standards developed elsewhere and merely referred to in the body of the Advanced Message Queuing
Protocol Specification, or (iii) any Licensed Product and any combinations thereof the purpose or
function of which is not required for compliance with the Advanced Message Queuing Protocol
Specification. For purposes of this definition, the Advanced Message Queuing Protocol
Specification shall be deemed to include both architectural and interconnection requirements
essential for interoperability and may also include supporting source code artifacts where such
architectural, interconnection requirements and source code artifacts are expressly identified as
being required or documentation to achieve compliance with the Advanced Message Queuing Protocol
Specification.
As used hereunder, "Licensed Products" means only those specific portions of products (hardware,
software or combinations thereof) that implement and are compliant with all relevant portions of
the Advanced Message Queuing Protocol Specification.
The following disclaimers, which you hereby also acknowledge as to any use you may make of the
Advanced Message Queuing Protocol Specification:
THE ADVANCED MESSAGE QUEUING PROTOCOL SPECIFICATION IS PROVIDED "AS IS," AND THE AUTHORS MAKE NO
REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS
OF THE ADVANCED MESSAGE QUEUING PROTOCOL SPECIFICATION ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE
IMPLEMENTATION OF THE ADVANCED MESSAGE QUEUING PROTOCOL SPECIFICATION WILL NOT INFRINGE ANY THIRD
PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
DAMAGES ARISING OUT OF OR RELATING TO ANY USE, IMPLEMENTATION OR DISTRIBUTION OF THE ADVANCED
MESSAGE QUEUING PROTOCOL SPECIFICATION.
The name and trademarks of the Authors may NOT be used in any manner, including advertising or
publicity pertaining to the Advanced Message Queuing Protocol Specification or its contents
without specific, written prior permission. Title to copyright in the Advanced Message Queuing
Protocol Specification will at all times remain with the Authors.
No other rights are granted by implication, estoppel or otherwise.
Upon termination of your license or rights under this Agreement, you shall destroy all copies of
the Advanced Message Queuing Protocol Specification in your possession or control.
Trademarks
==========
"JPMorgan", "JPMorgan Chase", "Chase", the JPMorgan Chase logo and the Octagon Symbol are
trademarks of JPMorgan Chase & Co.
RED HAT is a registered trademarks of Red Hat, Inc. in the US and other countries.
Other company, product, or service names may be trademarks or service marks of others.
Link to full AMQP specification:
=================================
http://www.amqp.org/confluence/display/AMQP/AMQP+Specification
-->
<!DOCTYPE amqp SYSTEM "amqp.dtd">
<amqp xmlns="http://www.amqp.org/schema/amqp.xsd"
name="transactions" label="working version">
<!-- == Section: transactions ================================================================ -->
<section name="transactions" title="Transactional Messaging">
<doc>
<p>
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.
</p>
<p>
For every transactional interaction, one container acts as the <i>transactional
resource</i>, and the other container acts as the <i>transaction controller</i>.
The <i>transactional resource</i> performs <i>transactional work</i> as requested by
the <i>transaction controller</i>.
</p>
<p>
The <i>transactional controller</i> and <i>transactional resource</i> communicate over a
<i>control link</i> which is established by the <i>transactional controller</i>. The <xref
name="declare"/> and <xref name="discharge"/> messages are sent by the <i>transactional
controller</i> over the <i>control link</i> to allocate and complete transactions
respectively (they do not represent the demarcation of transactional work). No transactional
work is allowed on the <i>control link</i>. Each transactional operation requested is
explicitly identified with the desired transaction-id and therefore may occur on any link
within the controlling Session, or, if permitted by the capabilities of the controller, any
link on the controlling Connection. If the <i>control link</i> is closed while there exist
non-discharged transactions it created, then all such transactions are immediately rolled
back, and attempts to perform further transactional work on them will lead to failure.
</p>
</doc>
</section>
<section name="txn-declare" title="Declaring a Transaction">
<doc>
<p>
The container acting as the transactional resource defines a special target that functions
as a <xref name="coordinator">transaction coordinator</xref>. The <i>transaction
controller</i> establishes a control link to this target. Note that links to the <xref
name="coordinator"/> cannot be resumed.
</p>
<p>
To begin transactional work, the transaction controller must obtain a transaction identifier
from the resource. It does this by sending a message to the <xref name="coordinator"/> whose
body consists of the <xref name="declare"/> type in a single <xref type="type"
name="amqp-value"/> section. Other standard message sections such as the header section
SHOULD be ignored. This message MUST NOT be sent settled as the sender is required to
receive and interpret the outcome of the declare at the receiver. If the coordinator
receives a <xref type="type" name="transfer"/> that has been settled by the sender, it
should <xref type="type" name="detach"/> with an appropriate error.
</p>
<p>
If the declaration is successful, the coordinator responds with a disposition outcome of
<xref name="declared"/> which carries the assigned identifier for the transaction.
</p>
<p>
If the coordinator was unable to perform the <xref name="declare"/> as specified by
the transaction controller, the transaction coordinator MUST convey the error to the
controller as a <xref name="transaction-error"/>. If the <xref name="source"/> for the link
to the <xref name="coordinator"/> supports the <xref name="rejected"/> outcome, then the
message MUST be <xref name="rejected"/> with this outcome carrying the <xref
name="transaction-error"/>. If the <xref name="source"/> does not support the <xref
name="rejected"/> outcome, the <i>transactional resource</i> MUST <xref name="detach"/> the
link to the coordinator, with the <xref name="detach"/> performative carrying the <xref
name="transaction-error"/>.
</p>
<p>
Transaction controllers SHOULD establish a control link that allows the
<xref name="rejected"/> outcome.
</p>
<picture title="Declaring a Transaction"><![CDATA[
Transaction Controller Transactional Resource
===============================================================================
ATTACH(name=txn-ctl, --------->
...,
target=
Coordinator(
capabilities=
"amqp:local-transactions")
)
<--------- ATTACH(name=txn-ctl,
...,
target=
Coordinator(
capabilities=
["amqp:local-transactions",
"amqp:multi-txns-per-ssn"]
)
)
<--------- FLOW(...,handle=1, link-credit=1)
TRANSFER(delivery-id=0, ...) --------->
{ AmqpValue( Declare() ) }
<--------- DISPOSITION(first=0, last=0,
state=Declared(txn-id=0) )
-------------------------------------------------------------------------------
]]>
</picture>
</doc>
</section>
<section name="txn-discharge" title="Discharging a Transaction">
<doc>
<p>
The controller will conclude the transactional work by sending a <xref name="discharge"/>
message (encoded in a single <xref type="type" name="amqp-value"/> section) to the
coordinator. The controller indicates that it wishes to commit or rollback the transactional
work by setting the <i>fail</i> flag on the <xref name="discharge"/> body. As with the <xref
type="type" name="declare"/> message, it is an error if the sender sends the <xref
type="type" name="transfer"/> pre-settled.
</p>
<p>
Should the coordinator be unable to complete the <xref name="discharge"/>, the coordinator
MUST convey the error to the controller as a <xref name="transaction-error"/>. If the <xref
type="type" name="source"/> for the link to the <xref name="coordinator"/> supports the
<xref type="type" name="rejected"/> outcome, then the message MUST be <xref type="type"
name="rejected"/> with this outcome carrying the <xref name="transaction-error"/>. If the
<xref type="type" name="source"/> does not support the <xref type="type" name="rejected"/>
outcome, the <i>transactional resource</i> MUST <xref type="type" name="detach"/> the link
to the coordinator, with the <xref type="type" name="detach"/> performative carrying the
<xref name="transaction-error"/>. Note that the coordinator MUST always be able to complete
a <xref name="discharge"/> where the fail flag is set to true (since coordinator failure
leads to rollback, which is what the controller is asking for).
</p>
<picture title="Discharging a Transaction"><![CDATA[
Transaction Controller Transactional Resource
===============================================================================
TRANSFER(delivery-id=0, ...) --------->
{ AmqpValue( Declare() ) }
<--------- DISPOSITION(first=0, last=0,
state=Declared(txn-id=0) )
:
Transactional Work
:
TRANSFER(delivery-id=57, ...) --------->
{ AmqpValue(
Discharge(txn-id=0,
fail=false)
) }
<--------- DISPOSITION(first=57, last=57,
state=Accepted() )
-------------------------------------------------------------------------------
]]>
</picture>
</doc>
</section>
<section name="txn-work" title="Transactional Work">
<doc>
<p>
Transactional work is described in terms of the message states defined in <xref type="doc"
name="message-state"/>. Transactional work is formally defined to be composed of the
following operations:
</p>
<ul>
<li>
<p><i>posting</i> a message at a target, i.e. making it <i>available</i></p>
</li>
<li>
<p><i>acquiring</i> a message at a source, i.e. transitioning it to <i>acquired</i></p>
</li>
<li>
<p><i>retiring</i> a message at a source, i.e. applying the terminal outcome</p>
</li>
</ul>
<p>
The transactional resource performs these operations when triggered by the transaction
controller:
</p>
<ul>
<li>
<p>
<i>posting</i> messages is initiated by incoming <xref type="type" name="transfer"/>
frames
</p>
</li>
<li>
<p>
<i>acquiring</i> messages is initiated by incoming <xref type="type" name="flow"/>
frames
</p>
</li>
<li>
<p>
<i>retiring</i> messages is initiated by incoming <xref type="type" name="disposition"/>
frames
</p>
</li>
</ul>
<p>
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 <xref name="transactional-state"/> that combines a txn-id
together with one of the terminal delivery states defined in <xref type="section"
name="delivery-state"/> of the messaging specification. The <xref
name="transactional-state"/> is carried by both the <xref type="type" name="transfer"/> and
the <xref type="type" name="disposition"/> frames allowing both the <i>posting</i> and
<i>retiring</i> of messages to be associated with a transaction.
</p>
<p>
The <xref type="type" name="transfer"/>, <xref type="type" name="disposition"/>, and <xref
type="type" name="flow"/> frames may travel in either direction, i.e. both from the
controller to the resource and from the resource to the controller. When these frames travel
from the controller to the resource, any embedded txn-ids are requesting that the resource
assigns transactional work to the indicated transaction. When traveling in the other
direction, from resource to controller, the <xref type="type" name="transfer"/> and <xref
type="type" name="disposition"/> frames indicate work performed, and the txn-ids included
MUST correctly indicate with which (if any) transaction this work is associated. In the case
of the <xref type="type" name="flow"/> frame traveling from resource to controller, the
txn-id does not indicate work that has been performed, but indicates with which transaction
future transfers from that link will be performed.
</p>
</doc>
<doc title="Transactional Posting">
<p>
If the transaction controller wishes to associate an outgoing <xref name="transfer"/> with a
transaction, it must set the state of the transfer with a <xref name="transactional-state"/>
carrying the appropriate transaction identifier. Note that if delivery is split across
several <xref name="transfer"/> frames then all frames MUST be explicitly associated with
the same transaction. It is an error for the controller to attempt to discharge a
transaction against which a partial delivery has been posted. Should this happen, the
control link MUST be terminated with the <xref name="transaction-error"
choice="transaction-rollback"/> error.
</p>
<p>
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.
</p>
<picture title="Transactional Publish"><![CDATA[
Transaction Controller Transactional Resource
===============================================================================
TRANSFER(handle=0, --------->
delivery-id=0, ...)
{ AmqpValue( Declare() ) }
<--------- DISPOSITION(first=0, last=0,
state=Declared(txn-id=0) )
TRANSFER(handle=1, --------->
delivery-id=1,
state=
TransactionalState(
txn-id=0) )
{ ... payload ... }
<--------- DISPOSITION(first=1, last=1,
state=TransactionalState(
txn-id=0,
outcome=Accepted())
)
-------------------------------------------------------------------------------
]]>
</picture>
<p>
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 <xref type="type"
name="disposition"/> performative which covers the posted transfer with the state of the
delivery being a <xref name="transactional-state"/> with the correct transaction identified,
and a terminal outcome. This informs the controller of the outcome that will be in effect at
the point that the transaction is successfully discharged.
</p>
</doc>
<doc title="Transactional Retirement">
<p>
The transaction controller may 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 <i>non discharged</i> transaction than the outcome. If this happens then
the control link MUST be terminated with a <xref name="transaction-error"
choice="transaction-rollback"/> error.
</p>
<p>
To associate an outcome with a transaction the controller sends a <xref type="type"
name="disposition"/> performative which sets the state of the delivery to a <xref
name="transactional-state"/> with the desired transaction identifier and the outcome to be
applied upon a successful discharge.
</p>
<picture title="Transactional Receive"><![CDATA[
Transaction Controller Transactional Resource
===============================================================================
TRANSFER(handle=0, --------->
delivery-id=0, ...)
{ AmqpValue( Declare() ) }
<--------- DISPOSITION(first=0, last=0,
state=Declared(txn-id=0) )
FLOW(handle=2, --------->
link-credit=10)
<--------- TRANSFER(handle=2,
delivery-id=11,
state=null,
{ ... payload ... }
:
:
<--------- TRANSFER(handle=2,
delivery-id=20,
state=null,
{ ... payload ... }
DISPOSITION(first=11, --------->
last=20,
state=TransactionalState(
txn-id=0,
outcome=Accepted())
)
-------------------------------------------------------------------------------
]]>
</picture>
<p>
On a successful <xref name="discharge"/>, the resource will apply the given outcome and may
immediately settle the transfers. In the event of a controller initiated rollback (a <xref
name="discharge"/> where the fail flag is set to true) or a resource initiated rollback (the
<xref name="discharge"/> message being rejected, or the link to the <xref
name="coordinator"/> being detached with an error), the outcome will not be applied, and the
deliveries will still be "live" and will remain acquired by the controller - i.e. the
resource should expect the controller to request a disposition for the delivery (either
transactionally on a new transaction, or non-transactionally).
</p>
</doc>
<doc title="Transactional Acquisition">
<p>
In the case of the <xref type="type" name="flow"/> frame, the transactional work is not
necessarily directly initiated or entirely determined when the <xref type="type"
name="flow"/> frame arrives at the resource, but may in fact occur at some later point and
in ways not necessarily anticipated by the controller. To accommodate this, the resource
associates an additional piece of state with outgoing link endpoints, an optional
<i>txn-id</i> that identifies the transaction with which <i>acquired</i> messages will be
associated. This state is determined by the controller by specifying a <i>txn-id</i> entry
in the <i>properties</i> map of the flow frame. When a transaction is discharged, the
<i>txn-id</i> of any link endpoints will be
cleared.
</p>
<p>
If the link endpoint does not support transactional acquisition, the link MUST be terminated
with a <xref type="type" name="amqp-error" choice="not-implemented"/> error.
</p>
<p>
While the <i>txn-id</i> 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 <i>controller</i> SHOULD ensure there is no
outstanding credit at the sender before it discharges the transaction. The <i>controller</i>
may do this by either setting the drain mode of the sending link endpoint to <i>true</i>
before discharging the transaction, or by reducing the <i>link-credit</i> to zero, and
waiting to hear back that the sender has seen this state change.
</p>
<p>
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
<xref name="transfer"/> frame and at least one, but not all, such frames have been sent)
then the resource MUST interpret this to mean that the fate of the acquisition is fully
decided by the discharge. If the <xref name="discharge"/> indicates the failure of the
transaction the resource MUST abort or complete the sending the remainder of the message
before completing the discharge.
</p>
<picture title="Transactional Acquisition"><![CDATA[
Transaction Controller Transactional Resource
===============================================================================
TRANSFER(handle=0, --------->
delivery-id=0, ...)
{ AmqpValue( Declare() ) }
<--------- DISPOSITION(first=0, last=0,
state=Declared(txn-id=0) )
FLOW(handle=2, --------->
link-credit=10,
drain=true,
properties={
txn-id=0
})
<--------- TRANSFER(handle=2,
delivery-id=11,
state=
TransactionalState(txn-id=0),
{ ... payload ... }
:
:
<--------- TRANSFER(handle=2,
delivery-id=20,
state=
TransactionalState(txn-id=0),
{ ... payload ... }
DISPOSITION(first=11, --------->
last=20,
state=TransactionalState(
txn-id=0,
outcome=Accepted())
)
-------------------------------------------------------------------------------
]]>
</picture>
</doc>
<doc title="Interaction of Settlement with Transactions">
<p>
The Transport layer defines a notion of <i>settlement</i> 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 may be rolled back
does have implications for deliveries which the endpoint has marked as settled (and for
which it therefore can no longer exchange state information using the previously allocated
transport level identifiers).
</p>
<doc title="Transactional Posting">
<dl>
<dt>Delivery Sent Settled By Controller</dt>
<dd><p>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. Should the resource be unable to process the delivery it MUST
NOT allow the successful discharge of the associated transaction. This may 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.
</p>
</dd>
<dt>Delivery Sent Unsettled By Controller; Resource Settles</dt>
<dd><p>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 <xref name="transfer"/> from controller to
resource was associated.
</p>
<p>
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 may 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.
</p>
</dd>
<dt>Delivery Sent Unsettled By Controller; Resource Does Not Settles</dt>
<dd><p>Behavior prior to discharge is the same as the previous case.</p>
<p>
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 no
outcome should be associated with the unsettled deliveries. The controller SHOULD
settle any outstanding unsettled deliveries in a timely fashion after the transaction
has discharged.
</p>
</dd>
</dl>
</doc>
<doc title="Transactional Retirement">
<p>
Here we consider 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 <b>Transactional Acquisition</b> below.
</p>
<dl>
<dt>Delivery Sent Unsettled By Resource; Controller Settles</dt>
<dd><p>Upon a successful discharge the outcome specified by the controller is applied at
the source. Should the controller request 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.
</p>
</dd>
<dt>Delivery Sent Unsettled By Resource; Controller Does Not Settle</dt>
<dd><p>The resource may or may 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.
</p>
<p>
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.
</p>
</dd>
</dl>
</doc>
<doc title="Transactional Acquisition">
<dl>
<dt>Delivery Sent Settled By Resource</dt>
<dd><p>In the event of a successful discharge the outcome applies at the resource,
otherwise the acquisition and outcome are rolled back.
</p>
</dd>
<dt>Delivery Sent Unsettled By Resource; Controller Sends Outcome</dt>
<dd><p>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.
</p>
</dd>
</dl>
</doc>
</doc>
</section>
<section name="coordination" label="types used to interact with a coordinator node">
<type class="composite" name="coordinator" source="list" provides="target"
label="target for communicating with a transaction coordinator">
<doc>
<p>
The coordinator type defines a special target used for establishing a link with a
transaction coordinator.
</p>
</doc>
<descriptor name="amqp:coordinator:list" code="0x00000000:0x00000030"/>
<field name="capabilities" type="symbol" requires="txn-capability" multiple="true"
label="the capabilities supported at the coordinator">
<doc>
<p>
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 <xref name="txn-capability"/>.
</p>
</doc>
</field>
</type>
<type class="composite" name="declare" source="list"
label="message body for declaring a transaction id">
<doc>
<p>
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 <xref name="declared"/> resulting outcome.
</p>
</doc>
<descriptor name="amqp:declare:list" code="0x00000000:0x00000031"/>
<field name="global-id" type="*" requires="global-tx-id" label="global transaction id">
<doc>
<p>
Specifies that the txn-id allocated by this declare MUST be associated work with the
indicated global transaction. If not set, the allocated txn-id will associated work with
a local transaction. This field MUST NOT be set if the Coordinator does not have the
<xref name="txn-capability" choice="distributed-transactions"/> capability. Note that
the specification of distributed transactions within AMQP 1.0 will be provided
separately in Book 6 Distributed Transactions.
</p>
</doc>
</field>
</type>
<type class="composite" name="discharge" source="list"
label="message body for discharging a transaction">
<doc>
<p>
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.
</p>
</doc>
<descriptor name="amqp:discharge:list" code="0x00000000:0x00000032"/>
<field name="txn-id" type="*" requires="txn-id" mandatory="true"
label="identifies the transaction to be discharged"/>
<field name="fail" type="boolean" label="indicates the transaction should be rolled back">
<doc>
<p>
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 Book 6
Distributed Transactions).
</p>
</doc>
</field>
</type>
<type class="restricted" name="transaction-id" source="binary" provides="txn-id">
<doc>
<p>
A transaction-id may be up to 32 octets of binary data.
</p>
</doc>
</type>
<type class="composite" name="declared" source="list" provides="delivery-state, outcome">
<doc>
<p>
Indicates that a transaction identifier has successfully been allocated in response to a
declare message sent to a transaction coordinator.
</p>
</doc>
<descriptor name="amqp:declared:list" code="0x00000000:0x00000033"/>
<field name="txn-id" type="*" requires="txn-id" mandatory="true"
label="the allocated transaction id"/>
</type>
<type class="composite" name="transactional-state" provides="delivery-state" source="list"
label="the state of a transactional message transfer">
<doc>
<p>
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.
</p>
</doc>
<descriptor name="amqp:transactional-state:list" code="0x00000000:0x00000034"/>
<field name="txn-id" type="*" mandatory="true" requires="txn-id"
label="identifies the transaction with which the state is associated"/>
<field name="outcome" type="*" requires="outcome" label="provisional outcome">
<doc>
<p>
This field indicates the provisional outcome to be applied if the transaction commits.
</p>
</doc>
</field>
</type>
<type class="restricted" name="txn-capability" source="symbol" provides="txn-capability"
label="symbols indicating (desired/available) capabilities of a transaction coordinator">
<choice name="local-transactions" value="amqp:local-transactions">
<doc>
<p>
Support local transactions.
</p>
</doc>
</choice>
<choice name="distributed-transactions" value="amqp:distributed-transactions">
<doc>
<p>
Support AMQP Distributed Transactions.
</p>
</doc>
</choice>
<choice name="promotable-transactions" value="amqp:promotable-transactions">
<doc>
<p>
Support AMQP Promotable Transactions.
</p>
</doc>
</choice>
<choice name="multi-txns-per-ssn" value="amqp:multi-txns-per-ssn">
<doc>
<p>
Support multiple active transactions on a single session.
</p>
</doc>
</choice>
<choice name="multi-ssns-per-txn" value="amqp:multi-ssns-per-txn">
<doc>
<p>
Support transactions whose txn-id is used across sessions on one connection.
</p>
</doc>
</choice>
</type>
<type class="restricted" name="transaction-error" source="symbol" provides="error-condition"
label="symbols used to indicate transaction errors">
<choice name="unknown-id" value="amqp:transaction:unknown-id">
<doc>
<p>The specified txn-id does not exist.</p>
</doc>
</choice>
<choice name="transaction-rollback" value="amqp:transaction:rollback">
<doc>
<p>The transaction was rolled back for an unspecified reason.</p>
</doc>
</choice>
<choice name="transaction-timeout" value="amqp:transaction:timeout">
<doc>
<p>The work represented by this transaction took too long.</p>
</doc>
</choice>
</type>
</section>
</amqp>