| <?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> |