| <?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="messaging" label="working version"> |
| |
| <section name="introduction" label="introduction to the Messaging layer"> |
| <doc> |
| <p> |
| The messaging layer builds on top of the concepts described in books I and II. The |
| <xref name="transport"/> layer defines a number of extension points suitable for use in a |
| variety of different messaging applications. The messaging layer specifies a standardized |
| use of these to provide interoperable messaging capabilities. This standard covers: |
| </p> |
| |
| <ul> |
| <li> |
| <p>message format</p> |
| |
| <ul> |
| <li> |
| <p>properties for the bare message</p> |
| </li> |
| |
| <li> |
| <p>formats for structured and unstructured sections in the bare message</p> |
| </li> |
| |
| <li> |
| <p>headers and footers for the annotated message</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>delivery states for messages traveling between nodes</p> |
| </li> |
| |
| <li> |
| <p>distribution nodes</p> |
| <ul> |
| <li><p>states for messages stored at a distribution node</p></li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>sources and targets</p> |
| |
| <ul> |
| <li> |
| <p>default disposition of transfers</p> |
| </li> |
| |
| <li> |
| <p>supported outcomes</p> |
| </li> |
| |
| <li> |
| <p>filtering of messages from a node</p> |
| </li> |
| |
| <li> |
| <p>distribution-mode for access to messages stored at a distribution node</p> |
| </li> |
| |
| <li> |
| <p>on-demand node creation</p> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </doc> |
| </section> |
| |
| <section name="message-format" title="Message Format" label="Message format definitions"> |
| |
| <doc> |
| <p> |
| The term message is used with various connotations in the messaging world. The sender may |
| like to think of the message as an immutable payload handed off to the messaging |
| infrastructure for delivery. The receiver often thinks of the message as not only that |
| immutable payload from the sender, but also various annotations supplied by the messaging |
| infrastructure along the way. To avoid confusion we formally define the term <i>bare |
| message</i> to mean the message as supplied by the sender and the term <i>annotated |
| message</i> to mean the message as seen at the receiver. |
| </p> |
| |
| <p> |
| An <i>annotated message</i> consists of the bare message plus sections for annotation at the |
| head and tail of the bare message. There are two classes of annotations: annotations that |
| travel with the message indefinitely, and annotations that are consumed by the next node. |
| </p> |
| |
| <p> |
| The <i>bare message</i> consists of sections standard properties, application-properties, |
| and application-data (the body). |
| </p> |
| |
| <picture><![CDATA[ |
| Bare Message |
| | |
| .---------------------+--------------------. |
| | | |
| +--------+-------------+-------------+------------+--------------+--------------+--------+ |
| | header | delivery- | message- | properties | application- | application- | footer | |
| | | annotations | annotations | | properties | data | | |
| +--------+-------------+-------------+------------+--------------+--------------+--------+ |
| | | |
| '-------------------------------------------+--------------------------------------------' |
| | |
| Annotated Message |
| ]]> |
| </picture> |
| |
| <p> |
| The bare message is immutable within the AMQP network. That is none of the sections can be |
| changed by any node acting as an AMQP intermediary. If a section of the bare message is |
| omitted, one may not be inserted by an intermediary. The exact encoding of sections of the |
| bare message MUST NOT be modified. This preserves message hashes, HMACs and signatures based |
| on the binary encoding of the bare message. |
| </p> |
| |
| <p> |
| The exact structure of a message, together with its encoding, is defined by the message |
| format. This document defines the structure and semantics of message format |
| <xref name="MESSAGE-FORMAT"/>. Altogether a message consists of the following sections: |
| </p> |
| |
| <ul> |
| <li> |
| <p> |
| Zero or one <xref name="header">header sections</xref>. |
| </p> |
| </li> |
| <li> |
| <p> |
| Zero or one <xref name="delivery-annotations">delivery-annotation |
| sections</xref>. |
| </p> |
| </li> |
| <li> |
| <p> |
| Zero or one <xref name="message-annotations">message-annotation sections</xref>. |
| </p> |
| </li> |
| <li> |
| <p> |
| Zero or one <xref name="properties">properties sections</xref>. |
| </p> |
| </li> |
| <li> |
| <p> |
| Zero or one <xref name="application-properties">application-properties |
| sections</xref>. |
| </p> |
| </li> |
| <li> |
| <p> |
| The body consists of either: one or more <xref name="data"/> sections, one or more |
| <xref name="amqp-sequence"/> sections, or a single <xref name="amqp-value"/> section. |
| </p> |
| </li> |
| <li> |
| <p> |
| Zero or one <xref name="footer">footer sections</xref>. |
| </p> |
| </li> |
| </ul> |
| </doc> |
| |
| <type class="composite" name="header" source="list" provides="section" |
| label="transport headers for a Message"> |
| <doc> |
| <p> |
| The header section carries standard delivery details about the transfer of a Message |
| through the AMQP network. If the header section is omitted the receiver MUST assume the |
| appropriate default values for the fields within the <xref name="header"/> unless other |
| target or node specific defaults have otherwise been set. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:header:list" code="0x00000000:0x00000070"/> |
| |
| <field name="durable" type="boolean" label="specify durability requirements"> |
| <doc> |
| <p> |
| Durable Messages MUST NOT be lost even if an intermediary is unexpectedly terminated and |
| restarted. A target which is not capable of fulfilling this guarantee MUST NOT accept |
| messages where the durable header is set to true: if the source allows the <xref |
| name="rejected"/> outcome then the message should be rejected with the <xref type="type" |
| name="amqp-error" choice="precondition-failed"/> error, otherwise the link must be |
| detached by the receiver with the same error. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="priority" type="ubyte" label="relative Message priority"> |
| <doc> |
| <p> |
| This field contains the relative Message priority. Higher numbers indicate higher |
| priority Messages. Messages with higher priorities MAY be delivered before those with |
| lower priorities. |
| </p> |
| |
| <p> |
| An AMQP intermediary implementing distinct priority levels MUST do so in the following |
| manner: |
| </p> |
| |
| <ul> |
| <li> |
| <p> |
| If n distinct priorities are implemented and n is less than 10 -- priorities 0 to |
| (5 - ceiling(n/2)) MUST be treated equivalently and MUST be the lowest effective |
| priority. The priorities (4 + floor(n/2)) and above MUST be treated equivalently |
| and MUST be the highest effective priority. The priorities (5 - ceiling(n/2)) to (4 |
| + floor(n/2)) inclusive MUST be treated as distinct priorities. |
| </p> |
| </li> |
| |
| <li> |
| <p> |
| If n distinct priorities are implemented and n is 10 or greater -- priorities 0 to |
| (n - 1) MUST be distinct, and priorities n and above MUST be equivalent to priority |
| (n - 1). |
| </p> |
| </li> |
| </ul> |
| |
| <p> |
| Thus, for example, if 2 distinct priorities are implemented, then levels 0 to 4 are |
| equivalent, and levels 5 to 9 are equivalent and levels 4 and 5 are distinct. If 3 |
| distinct priorities are implements the 0 to 3 are equivalent, 5 to 9 are equivalent and |
| 3, 4 and 5 are distinct. |
| </p> |
| |
| <p> |
| This scheme ensures that if two priorities are distinct for a server which implements m |
| separate priority levels they are also distinct for a server which implements n |
| different priority levels where n > m. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="ttl" type="milliseconds" label="time to live in ms"> |
| <doc> |
| <p> |
| Duration in milliseconds for which the Message should be considered "live". If this is |
| set then a message expiration time will be computed based on the time of arrival at an |
| intermediary. Messages that live longer than their expiration time will be discarded |
| (or dead lettered). When a message is transmitted by an intermediary that was received |
| with a ttl, the transmitted message's header should contain a ttl that is computed as |
| the difference between the current time and the formerly computed message expiration |
| time, i.e. the reduced ttl, so that messages will eventually die if they end up in a |
| delivery loop. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="first-acquirer" type="boolean" label=""> |
| <doc> |
| <p> |
| If this value is true, then this message has not been acquired by any other Link. If |
| this value is false, then this message may have previously been acquired by another Link |
| or Links. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="delivery-count" type="uint" |
| label="the number of prior unsuccessful delivery attempts"> |
| <doc> |
| <p> |
| The number of unsuccessful previous attempts to deliver this message. If this value is |
| non-zero it may be taken as an indication that the delivery may be a duplicate. On first |
| delivery, the value is zero. It is incremented upon an outcome being settled at the |
| sender, according to rules defined for each outcome. |
| </p> |
| </doc> |
| </field> |
| |
| </type> |
| |
| <type class="restricted" name="delivery-annotations" source="annotations" provides="section"> |
| <doc> |
| <p> |
| The delivery-annotations section is used for delivery-specific non-standard properties at |
| the head of the message. Delivery annotations convey information from the sending peer to |
| the receiving peer. If the recipient does not understand the annotation it cannot be acted |
| upon and its effects (such as any implied propagation) cannot be acted upon. Annotations |
| may be specific to one implementation, or common to multiple implementations. The |
| capabilities negotiated on link <xref name="attach"/> and on the <xref name="source"/> and |
| <xref name="target"/> should be used to establish which annotations a peer supports. A |
| registry of defined annotations and their meanings can be found here: <xref type="extern" |
| name="http://www.amqp.org/specification/1.0/delivery-annotations"/>. |
| </p> |
| |
| <p> |
| If the delivery-annotations section is omitted, it is equivalent to a delivery-annotations |
| section containing an empty map of annotations. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:delivery-annotations:map" code="0x00000000:0x00000071"/> |
| </type> |
| |
| <type class="restricted" name="message-annotations" source="annotations" provides="section"> |
| <doc> |
| <p> |
| The message-annotations section is used for properties of the message which are aimed at |
| the infrastructure and should be propagated across every delivery step. Message |
| annotations convey information about the message. Intermediaries MUST propagate the |
| annotations unless the annotations are explicitly augmented or modified (e.g. by the use |
| of the <xref name="modified"/> outcome). |
| </p> |
| |
| <p> |
| The capabilities negotiated on link <xref name="attach"/> and on the <xref name="source"/> |
| and <xref name="target"/> may be used to establish which annotations a peer understands, |
| however it a network of AMQP intermediaries it may not be possible to know if every |
| intermediary will understand the annotation. Note that for some annotation it may not be |
| necessary for the intermediary to understand their purpose - they may be being used purely |
| as an attribute which can be filtered on. |
| </p> |
| |
| <p> |
| A registry of defined annotations and their meanings can be found here: |
| <xref type="extern" name="http://www.amqp.org/specification/1.0/message-annotations"/>. |
| </p> |
| |
| <p> |
| If the message-annotations section is omitted, it is equivalent to a message-annotations |
| section containing an empty map of annotations. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:message-annotations:map" code="0x00000000:0x00000072"/> |
| </type> |
| |
| <type class="composite" name="properties" source="list" provides="section" |
| label="immutable properties of the Message"> |
| <doc> |
| <p> |
| The properties section is used for a defined set of standard properties of the message. |
| The properties section is part of the bare message and thus must, if retransmitted by an |
| intermediary, remain completely unaltered. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:properties:list" code="0x00000000:0x00000073"/> |
| |
| <field name="message-id" type="*" requires="message-id" |
| label="application Message identifier"> |
| <doc> |
| <p> |
| Message-id is an optional property which uniquely identifies a Message within the |
| Message system. The Message producer is usually responsible for setting the message-id |
| in such a way that it is assured to be globally unique. A broker MAY discard a Message |
| as a duplicate if the value of the message-id matches that of a previously received |
| Message sent to the same Node. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="user-id" type="binary" label="creating user id"> |
| <doc> |
| <p> |
| The identity of the user responsible for producing the Message. The client sets this |
| value, and it MAY be authenticated by intermediaries. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="to" type="*" requires="address" |
| label="the address of the Node the Message is destined for"> |
| <doc> |
| <p> |
| The to field identifies the Node that is the intended destination of the Message. On any |
| given transfer this may not be the Node at the receiving end of the Link. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="subject" type="string" label="the subject of the message"> |
| <doc> |
| <p> |
| A common field for summary information about the Message content and purpose. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="reply-to" type="*" requires="address" label="the Node to send replies to"> |
| <doc> |
| <p>The address of the Node to send replies to.</p> |
| </doc> |
| </field> |
| |
| <field name="correlation-id" type="*" requires="message-id" |
| label="application correlation identifier"> |
| <doc> |
| <p> |
| This is a client-specific id that may be used to mark or identify Messages between |
| clients. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="content-type" type="symbol" label="MIME content type"> |
| <doc> |
| <p> |
| The RFC-2046 MIME type for the Message's application-data section (body). |
| </p> |
| <p> |
| As per RFC-2046 this may contain a charset parameter defining |
| the character encoding used: e.g. 'text/plain; charset="utf-8"'. For clarity, the |
| correct MIME type for a truly opaque binary section is application/octet-stream. |
| </p> |
| <p> |
| When using an application-data section with a section code other than <i>data</i>, |
| content-type, if set, SHOULD be set to a MIME type of message/x-amqp+?, where '?' is |
| either data, map or list. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="content-encoding" type="symbol" label="MIME content type"> |
| <doc> |
| <p> |
| The Content-Encoding property is used as a modifier to the content-type. |
| When present, its value indicates what additional content encodings have been applied |
| to the application-data, and thus what decoding mechanisms must be applied in order to |
| obtain the media-type referenced by the content-type header field. |
| </p> |
| <p> |
| Content-Encoding is primarily used to allow a document to be compressed without |
| losing the identity of its underlying content type. |
| </p> |
| <p> |
| Content Encodings are to be interpreted as per Section 3.5 of RFC 2616. Valid Content |
| Encodings are registered at IANA as "Hypertext Transfer Protocol (HTTP) Parameters" |
| (http://www.iana.org/assignments/http-parameters/http-parameters.xml). |
| </p> |
| <p> |
| Content-Encoding MUST not be set when the application-data section is other than |
| <i>data</i>. |
| </p> |
| <p> |
| Implementations MUST NOT use the <i>identity</i> encoding. Instead, implementations |
| should not set this property. Implementations SHOULD NOT |
| use the <i>compress</i> encoding, except as to remain compatible with messages |
| originally sent with other protocols, e.g. HTTP or SMTP. |
| </p> |
| <p> |
| Implementations SHOULD NOT specify multiple content encoding values except as to |
| be compatible with messages originally sent with other protocols, e.g. HTTP or SMTP. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="absolute-expiry-time" type="timestamp" |
| label="the time when this message is considered expired"> |
| <doc> |
| <p> |
| An absolute time when this message is considered to be expired. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="creation-time" type="timestamp" |
| label="the time when this message was created"> |
| <doc> |
| <p> |
| An absolute time when this message was created. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="group-id" type="string" |
| label="the group this message belongs to"> |
| <doc> |
| <p> |
| Identifies the group the message belongs to. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="group-sequence" type="sequence-no" |
| label="the sequence-no of this message within its group"> |
| <doc> |
| <p> |
| The relative position of this message within its group. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="reply-to-group-id" type="string" |
| label="the group the reply message belongs to"> |
| <doc> |
| <p> |
| This is a client-specific id that is used so that client can send replies to this |
| message to a specific group. |
| </p> |
| </doc> |
| </field> |
| |
| </type> |
| |
| <type class="restricted" name="application-properties" source="map" provides="section"> |
| <doc> |
| <p> |
| The application-properties section is a part of the bare message used for structured |
| application data. Intermediaries may use the data within this structure for the purposes |
| of filtering or routing. |
| </p> |
| |
| <p> |
| The keys of this map are restricted to be of type <xref type="type" name="string"/> (which |
| excludes the possibility of a null key) and the values are restricted to be of simple |
| types only, that is (excluding <xref type="type" name="map"/>, <xref type="type" |
| name="list"/>, and <xref type="type" name="array"/> types). |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:application-properties:map" code="0x00000000:0x00000074"/> |
| </type> |
| |
| <type class="restricted" name="data" source="binary" provides="section"> |
| <doc> |
| <p> |
| A data section contains opaque binary data. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:data:binary" code="0x00000000:0x00000075"/> |
| </type> |
| |
| <type class="restricted" name="amqp-sequence" source="list" provides="section"> |
| <doc> |
| <p> |
| A sequence section contains an arbitrary number of structured data elements. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:amqp-sequence:list" code="0x00000000:0x00000076"/> |
| </type> |
| |
| <type class="restricted" name="amqp-value" source="*" provides="section"> |
| <doc> |
| <p> |
| An amqp-value section contains a single AMQP value. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:amqp-value:*" code="0x00000000:0x00000077"/> |
| </type> |
| |
| <type class="restricted" name="footer" source="annotations" provides="section" |
| label="transport footers for a Message"> |
| <doc> |
| <p> |
| The footer section is used for details about the message or delivery which can only be |
| calculated or evaluated once the whole bare message has been constructed or seen (for |
| example message hashes, HMACs, signatures and encryption details). |
| </p> |
| |
| <p> |
| A registry of defined footers and their meanings can be found here: <xref type="extern" |
| name="http://www.amqp.org/specification/1.0/footer"/>. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:footer:map" code="0x00000000:0x00000078"/> |
| </type> |
| |
| <type class="restricted" name="annotations" source="map"> |
| <doc> |
| <p> |
| The <i>annotations</i> type is a map where the keys are restricted to be of type <xref |
| type="type" name="symbol"/> or of type <xref type="type" name="ulong"/>. All ulong keys, |
| and all symbolic keys except those beginning with "x-" are reserved. On receiving an |
| annotations map containing keys or values which it does not recognize, and for which the |
| key does not begin with the string "x-opt-" an AMQP container MUST detach the link with |
| the not-implemented <xref name="amqp-error"/>. |
| </p> |
| </doc> |
| </type> |
| |
| <type class="restricted" name="message-id-ulong" source="ulong" provides="message-id"/> |
| <type class="restricted" name="message-id-uuid" source="uuid" provides="message-id"/> |
| <type class="restricted" name="message-id-binary" source="binary" provides="message-id"/> |
| <type class="restricted" name="message-id-string" source="string" provides="message-id"/> |
| |
| <type class="restricted" name="address-string" source="string" provides="address" |
| label="address of a Node"/> |
| |
| <definition name="MESSAGE-FORMAT" value="0" |
| label="the format + revision for the messages defined by this document"> |
| <doc> |
| <p> |
| This value goes into the message-format field of the transfer frame when transferring |
| messages of the format defined herein. |
| </p> |
| </doc> |
| </definition> |
| </section> |
| |
| <section name="distribution-nodes" title="Distribution Nodes" |
| label="common interface for nodes that store and distribute messages"> |
| |
| <doc name="message-state" title="Message States"> |
| <p> |
| The Messaging layer defines a set of states for Messages stored at a <i>distribution |
| node</i>. Not all Nodes store Messages for distribution, however these definitions permit |
| some standardized interaction with those nodes that do. The transitions between these states |
| are controlled by the transfer of Messages to/from a distribution node and the resulting |
| terminal delivery state. Note that the state of a Message at one distribution node does not |
| affect the state of the same Message at a separate node. |
| </p> |
| |
| <p> |
| By default a Message will begin in the AVAILABLE state. Prior to initiating an |
| <i>acquiring</i> transfer, the Message will transition to the ACQUIRED state. Once in the |
| ACQUIRED state, a Message is ineligible for <i>acquiring</i> transfers to any other Links. |
| </p> |
| |
| <p> |
| A Message will remain ACQUIRED at the distribution node until the transfer is settled. The |
| delivery state at the receiver determines how the message transitions when the transfer is |
| settled. If the delivery state at the receiver is not yet known, (e.g. the link endpoint is |
| destroyed before recovery occurs) the <i>default-outcome</i> of the source is used. |
| </p> |
| |
| <p> |
| State transitions may also occur spontaneously at the distribution node. For example if a |
| Message with a ttl expires, the effect of expiry may be (depending on specific type and |
| configuration of the distribution node) to move spontaneously from the AVAILABLE state into |
| the ARCHIVED state. In this case any transfers of the message are transitioned to a terminal |
| outcome at the distribution node regardless of receiver state. |
| </p> |
| |
| <picture title="Message State Transitions"><![CDATA[ |
| +------------+ |
| +->| AVAILABLE | |
| | +------------+ |
| | | |
| | | |
| terminal outcome: | | |
| RELEASED/MODIFIED | | TRANSFER (acquiring) |
| | | |
| | | |
| | \|/ |
| | +------------+ |
| +--| ACQUIRED | |
| +------------+ |
| | |
| | |
| | terminal outcome: |
| | ACCEPTED/REJECTED |
| | |
| | |
| \|/ |
| +------------+ |
| | ARCHIVED | |
| +------------+ |
| ]]> |
| </picture> |
| </doc> |
| </section> |
| |
| <section name="delivery-state" title="Delivery State" |
| label="the delivery states defined for messaging"> |
| <doc> |
| <p> |
| The Messaging layer defines a concrete set of delivery states which can be used (via the |
| <xref type="type" name="disposition"/> frame) to indicate the state of the message at the |
| receiver. Delivery states may be either terminal or non-terminal. Once a delivery reaches a |
| terminal delivery-state, the state for that delivery will no longer change. A terminal |
| delivery-state is referred to as an <i>outcome</i>. |
| </p> |
| |
| <p> |
| The following outcomes are formally defined by the messaging layer to indicate the result of |
| processing at the receiver: |
| </p> |
| |
| <ul> |
| <li> |
| <p><xref name="accepted"/>: indicates successful processing at the receiver</p> |
| </li> |
| <li> |
| <p><xref name="rejected"/>: indicates an invalid and unprocessable message</p> |
| </li> |
| <li> |
| <p><xref name="released"/>: indicates that the message was not (and will not be) |
| processed</p> |
| </li> |
| <li> |
| <p><xref name="modified"/>: indicates that the message was modified, but not processed</p> |
| </li> |
| </ul> |
| |
| <p> |
| The following non-terminal delivery-state is formally defined by the messaging layer for use |
| during link recovery to allow the sender to resume the transfer of a large message without |
| retransmitting all the message data: |
| </p> |
| |
| <ul> |
| <li> |
| <p><xref name="received"/>: indicates partial message data seen by the receiver as well as |
| the starting point for a resumed transfer</p> |
| </li> |
| </ul> |
| </doc> |
| |
| <type class="composite" name="received" source="list" provides="delivery-state"> |
| <descriptor name="amqp:received:list" code="0x00000000:0x00000023"/> |
| <doc> |
| <p> |
| At the target the <xref name="received"/> state indicates the furthest point in the |
| payload of the message which the target will not need to have resent if the link is |
| resumed. At the source the <xref name="received"/> state represents the earliest point in |
| the payload which the Sender is able to resume transferring at in the case of link |
| resumption. When resuming a delivery, if this state is set on the first <xref type="type" |
| name="transfer"/> performative it indicates the offset in the payload at which the first |
| resumed delivery is starting. The Sender MUST NOT send the <xref name="received"/> state |
| on <xref type="type" name="transfer"/> or <xref type="type" name="disposition"/> |
| performatives except on the first <xref type="type" name="transfer"/> performative on a |
| resumed delivery. |
| </p> |
| </doc> |
| <field name="section-number" type="uint" mandatory="true"> |
| <doc> |
| <p> |
| When sent by the Sender this indicates the first section of the message (with |
| section-number 0 being the first section) for which data can be resent. Data from |
| sections prior to the given section cannot be retransmitted for this delivery. |
| </p> |
| <p> |
| When sent by the Receiver this indicates the first section of the message for which |
| all data may not yet have been received. |
| </p> |
| </doc> |
| </field> |
| <field name="section-offset" type="ulong" mandatory="true"> |
| <doc> |
| <p> |
| When sent by the Sender this indicates the first byte of the encoded section data of the |
| section given by section-number for which data can be resent (with section-offset 0 |
| being the first byte). Bytes from the same section prior to the given offset section |
| cannot be retransmitted for this delivery. |
| </p> |
| <p> |
| When sent by the Receiver this indicates the first byte of the given section which has |
| not yet been received. Note that if a receiver has received all of section number X |
| (which contains N bytes of data), but none of section number X + 1, then it may indicate |
| this by sending either Received(section-number=X, section-offset=N) or |
| Received(section-number=X+1, section-offset=0). The state Received(section-number=0, |
| section-offset=0) indicates that no message data at all has been transferred. |
| </p> |
| </doc> |
| </field> |
| </type> |
| |
| <type class="composite" name="accepted" source="list" provides="delivery-state, outcome" |
| label="the accepted outcome"> |
| |
| <descriptor name="amqp:accepted:list" code="0x00000000:0x00000024"/> |
| |
| <doc> |
| <p> |
| At the source the accepted state means that the message has been retired from the node, |
| and transfer of payload data will not be able to be resumed if the link becomes suspended. |
| A delivery may become accepted at the source even before all transfer frames have been |
| sent, this does not imply that the remaining transfers for the delivery will not be sent - |
| only the aborted flag on the <xref type="type" name="transfer"/> performative can be used |
| to indicate a premature termination of the transfer. |
| </p> |
| <p> |
| At the target, the accepted outcome is used to indicate that an incoming Message has been |
| successfully processed, and that the receiver of the Message is expecting the sender to |
| transition the delivery to the accepted state at the source. |
| </p> |
| <p> |
| The accepted outcome does not increment the <i>delivery-count</i> in the header of the |
| accepted Message. |
| </p> |
| </doc> |
| </type> |
| |
| <type class="composite" name="rejected" source="list" provides="delivery-state, outcome" |
| label="the rejected outcome"> |
| |
| <descriptor name="amqp:rejected:list" code="0x00000000:0x00000025"/> |
| |
| <doc> |
| <p> |
| At the target, the rejected outcome is used to indicate that an incoming Message is |
| invalid and therefore unprocessable. The rejected outcome when applied to a Message will |
| cause the <i>delivery-count</i> to be incremented in the header of the rejected Message. |
| </p> |
| <p> |
| At the source, the rejected outcome means that the target has informed the source that |
| the message was rejected, and the source has taken the required action. The delivery |
| SHOULD NOT ever spontaneously attain the rejected state at the source. |
| </p> |
| </doc> |
| |
| <field name="error" type="error" label="error that caused the message to be rejected"> |
| <doc> |
| <p> |
| The value supplied in this field will be placed in the delivery-annotations of the |
| rejected Message associated with the symbolic key "rejected". |
| </p> |
| </doc> |
| </field> |
| </type> |
| |
| <type class="composite" name="released" source="list" provides="delivery-state, outcome" |
| label="the released outcome"> |
| |
| <descriptor name="amqp:released:list" code="0x00000000:0x00000026"/> |
| |
| <doc> |
| <p> |
| At the source the released outcome means that the message is no longer acquired by the |
| receiver, and has been made available for (re-)delivery to the same or other targets |
| receiving from the node. The message is unchanged at the node (i.e. the |
| <i>delivery-count</i> of the header of the released Message MUST NOT be incremented). As |
| released is a terminal outcome, transfer of payload data will not be able to be resumed |
| if the link becomes suspended. A delivery may become released at the source even before |
| all transfer frames have been sent, this does not imply that the remaining transfers for |
| the delivery will not be sent. The source MAY spontaneously attain the released outcome |
| for a Message (for example the source may implement some sort of time bound acquisition |
| lock, after which the acquisition of a message at a node is revoked to allow for delivery |
| to an alternative consumer). |
| </p> |
| <p> |
| At the target, the released outcome is used to indicate that a given transfer was not and |
| will not be acted upon. |
| </p> |
| </doc> |
| |
| </type> |
| |
| <type class="composite" name="modified" source="list" provides="delivery-state, outcome" |
| label="the modified outcome"> |
| |
| <descriptor name="amqp:modified:list" code="0x00000000:0x00000027"/> |
| |
| <doc> |
| <p> |
| At the source the modified outcome means that the message is no longer acquired by the |
| receiver, and has been made available for (re-)delivery to the same or other targets |
| receiving from the node. The message has been changed at the node in the ways indicated by |
| the fields of the outcome. As modified is a terminal outcome, transfer of payload data |
| will not be able to be resumed if the link becomes suspended. A delivery may become |
| modified at the source even before all transfer frames have been sent, this does not imply |
| that the remaining transfers for the delivery will not be sent. The source MAY |
| spontaneously attain the modified outcome for a Message (for example the source may |
| implement some sort of time bound acquisition lock, after which the acquisition of a |
| message at a node is revoked to allow for delivery to an alternative consumer with the |
| message modified in some way to denote the previous failed, e.g. with delivery-failed set |
| to true). |
| </p> |
| <p> |
| At the target, the modified outcome is used to indicate that a given transfer was not and |
| will not be acted upon, and that the message should be modified in the specified ways at |
| the node. |
| </p> |
| </doc> |
| |
| |
| <field name="delivery-failed" type="boolean" |
| label="count the transfer as an unsuccessful delivery attempt"> |
| <doc> |
| <p> |
| If the delivery-failed flag is set, any Messages modified MUST have their |
| delivery-count incremented. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="undeliverable-here" type="boolean" label="prevent redelivery"> |
| <doc> |
| <p> |
| If the undeliverable-here is set, then any Messages released MUST NOT be redelivered to |
| the modifying Link Endpoint. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="message-annotations" type="fields" label="message attributes"> |
| <doc> |
| <p> |
| Map containing attributes to combine with the existing <i>message-annotations</i> held |
| in the Message's header section. Where the existing message-annotations of the Message |
| contain an entry with the same key as an entry in this field, the value in this field |
| associated with that key replaces the one in the existing headers; where the existing |
| message-annotations has no such value, the value in this map is added. |
| </p> |
| </doc> |
| </field> |
| </type> |
| |
| <doc name="more-resuming-deliveries" title="Resuming Deliveries Using Delivery States"> |
| <p> |
| In <xref type="doc" name="resuming-deliveries"/> the general scheme for how two endpoints |
| should re-establish state after link resumption was provided. The concrete delivery states |
| defined above allow for a more comprehensive set of examples of link resumption. |
| </p> |
| <picture><![CDATA[ |
| Peer Partner |
| ======================================================================= |
| |
| ATTACH(name=N, handle=1, --+ +-- ATTACH(name=N, handle=2, |
| role=sender, \ / role=receiver, |
| source=X, \ / source=X, |
| target=Y, x target=Y, |
| unsettled= / \ unsettled= |
| { 1 -> null, / \ { 2 -> Received(3,0), |
| 2 -> null, <-+ +-> 3 -> Accepted, |
| 3 -> null, 4 -> null, |
| 4 -> null, 6 -> Received(2,0), |
| 5 -> Received(0,200), 7 -> Received(0,100), |
| 6 -> Received(1,150), 8 -> Accepted, |
| 7 -> Received(0,500), 9 -> null, |
| 8 -> Received(3,5), 11 -> Received(1,2000), |
| 9 -> Received(2,0), 12 -> Accepted, |
| 10 -> Accepted, 13 -> Released, |
| 11 -> Accepted, 14 -> null } |
| 12 -> Accepted, |
| 13 -> Accepted, |
| 14 -> Accepted } |
| |
| ----------------------------------------------------------------------- |
| Key: |
| |
| Received(x,y) means Received(section-number=x, section-offset=y) |
| ]]> |
| </picture> |
| <p> |
| In this example, for delivery-tags 1 to 4 inclusive the sender indicates that it can resume |
| sending from the start of the message. |
| </p> |
| <p> |
| For delivery-tag 1, the receiver has no record of the delivery. To preserve "at least once", |
| or "at most once" delivery guarantees, the sender MUST resend the message, however the |
| delivery is not being resumed (since the receiver does not remember the delivery tag) so |
| transfers MUST NOT have the resume flag set to true. If the sender were to mark the |
| transfers as resumes then they would be ignored at the receiver. |
| </p> |
| <p> |
| For delivery-tag 2, the receiver has retained some of the data making up the message, but |
| not the whole. In order to complete the delivery the sender must resume sending from some |
| point before or at the next position which the receiver is expecting. |
| </p> |
| <picture><![CDATA[ |
| TRANSFER(delivery-id=1, ----------> ** Append message data not ** |
| delivery-tag=2, ** seen previously to delivery ** |
| (1) state=Received(3,0), ** state. ** |
| resume=true) |
| { ** payload ** } |
| |
| |
| (1) state could be |
| a) null, meaning that the transfer is being resumed from the first |
| byte of section number 0 (and the receiver MUST ignore all data |
| up to the first position it has not previously received). |
| b) Received with section number 0, 1 or 2 and an offset, indicating |
| that the payload data on the first frame of the resumed delivery |
| starts at the given point, and that the receiver MUST ignore all |
| data up to the first position it has not previously received. |
| c) Received(3,0) indicating that the resumption will start at the |
| first point which the receiver has not previously received. ]]> </picture> |
| <p> |
| For delivery-tag 3, the receiver indicates that it has processed the delivery to the point |
| where it desires a terminal outcome (in this case <xref name="accepted"/>). In this case |
| the sender will either apply that outcome at the source, or in the rare case that it cannot |
| apply that outcome, indicate the terminal outcome that has been applied. To do this the |
| sender MUST send a resuming transfer to associate delivery-tag 3 with a delivery-id. On this |
| transfer the sender SHOULD set the delivery-state at the source. If this is the same outcome |
| as at the receiver then the sender MAY also send the resuming transfer as settled. |
| </p> |
| <picture><![CDATA[ |
| TRANSFER(delivery-id=2, ----------> ** Processes confirmation that ** |
| delivery-tag=3, ** was accepted, and settles. ** |
| settled=true, |
| more=false, |
| state=Accepted, |
| resume=true) ]]> </picture> |
| <p> |
| For delivery-tag 4, the receiver indicates that it is aware that the delivery had begun, but |
| does not provide any indication that it has retained any data about that delivery except |
| the fact of its existence. To preserve "at least once" or "at most once" delivery |
| guarantees, the sender MUST resend the whole message. Unlike the case with delivery-tag 1 |
| the resent delivery MUST be sent with the resume flag set to true and the delivery-tag set |
| to 4. (While this use of null in the receivers map is valid, it is discouraged. It is |
| recommended that receiver SHOULD NOT retain such an entry in its map, in which case the |
| situation would be as for delivery-tag 1 in this example). |
| </p> |
| <picture><![CDATA[ |
| TRANSFER(delivery-id=3, ----------> ** Processes in the same way ** |
| delivery-tag=4, ** as we be done for a non- ** |
| (1) state=null, ** resumed delivery. ** |
| resume=true) |
| { ** payload ** } |
| |
| |
| (1) Alternatively (and equivalently) state could be |
| Received(section-number=0, section-offset=0) ]]> </picture> |
| <p> |
| For delivery-tags 5 to 9 inclusive the sender indicates that it can resume at some point |
| beyond start of the message data. This is usually indicative of the fact that the receiver |
| had previously confirmed reception of message data to the given point, removing |
| responsibility from the sender to retain the ability to resend that data after resuming |
| the link. The sender MAY still retain the ability to resend the message as a new delivery |
| (i.e. it MAY not have completely discarded the data from which the original delivery was |
| generated). |
| </p> |
| <p> |
| For delivery-tag 5, the receiver has no record of the delivery. To preserve "at least once", |
| or "at most once" delivery guarantees, the sender MUST resend the message, however the |
| delivery is not being resumed (since the receiver does not remember the delivery tag) so |
| transfers MUST NOT have the resume flag set to true. If the sender does not enough data to |
| resend the message, then he sender MAY take some action to indicate that it believes there |
| is a possibility that there has been message loss. |
| </p> |
| <p> |
| For delivery-tag 6, the receiver has retained some of the data making up the message, but |
| not the whole. The first position within the message which the receiver has not received is |
| after the first position at which the sender can resume sending. In order to complete the |
| delivery the sender must resume sending from some point before or at the next position which |
| the receiver is expecting. |
| </p> |
| <picture><![CDATA[ |
| TRANSFER(delivery-id=4, ----------> ** Append message data not ** |
| delivery-tag=6, ** seen previously to delivery ** |
| (1) state=Received(2,0), ** state. ** |
| resume=true) |
| { ** payload ** } |
| |
| |
| (1) state could be any point between Received(1,150) and Received(2,0) |
| inclusive. The receiver MUST ignore all data up to the first |
| position it has not previously received (i.e. section 2 offset 0). ]]> </picture> |
| <p> |
| For delivery-tag 7, the receiver has retained some of the data making up the message, but |
| not the whole. The first position within the message which the receiver has not received is |
| before the first position at which the sender can resume sending. It is thus not possible |
| for the sender to resume sending the message to completion. The only option available to the |
| sender is to abort the transfer and to then (if possible) resend as a new delivery or else |
| to report the possible message loss in some way if it cannot. |
| </p> |
| <picture><![CDATA[ |
| TRANSFER(delivery-id=5, ----------> ** Discard any state relating ** |
| delivery-tag=7, ** to the message delivery. ** |
| resume=true, |
| aborted=true) ]]> </picture> |
| <p> |
| For delivery-tag 8, the receiver indicates that it has processed the delivery to the point |
| where it desires a terminal outcome (in this case <xref name="accepted"/>). This is the |
| same case as for delivery-tag 3. |
| </p> |
| <picture><![CDATA[ |
| TRANSFER(delivery-id=6, ----------> ** Processes confirmation that ** |
| delivery-tag=8, ** was accepted, and settles. ** |
| settled=true, |
| more=false, |
| state=Accepted, |
| resume=true) ]]> </picture> |
| <p> |
| For delivery-tag 9, the receiver indicates that it is aware that the delivery had begun, but |
| does not provide any indication that it has retained any data about that delivery except |
| the fact of its existence. This is the same case as for delivery-tag 7. |
| </p> |
| <picture><![CDATA[ |
| TRANSFER(delivery-id=7, ----------> ** Discard any state relating ** |
| delivery-tag=9, ** to the message delivery. ** |
| resume=true, |
| aborted=true) ]]> </picture> |
| <p> |
| For delivery-tags 10 to 14 inclusive the sender indicates that it has reached a terminal |
| outcome, namely <xref name="accepted"/>. Once the sender has arrived at a terminal outcome |
| it may not change. As such, if a sender is capable of resuming a delivery (even if the only |
| possible outcome of the delivery is a pre-defined terminal outcome such as <xref |
| name="accepted"/>) it MUST NOT use this state as the value of the state in its unsettled map |
| until it is sure that the receiver will not require the resending of the message data. |
| </p> |
| <p> |
| For delivery-tag 10 the receiver has no record of the delivery. However, in contrast to the |
| cases of delivery-tag 1 and delivery-tag 5, since we know that the sender can only have |
| arrived at this state through knowing that the receiver has received the whole message (or |
| that the sender had spontaneously reached a terminal outcome with no possibility of |
| resumption) we have no need to resend the message. |
| </p> |
| <p> |
| For delivery-tag 11 we have to assume that the sender spontaneously attained the terminal |
| outcome (and is unable to resume). In this case the sender can simply abort the delivery |
| as it cannot be resumed. |
| </p> |
| <picture><![CDATA[ |
| TRANSFER(delivery-id=8, ----------> ** Discard any state relating ** |
| delivery-tag=11, ** to the message delivery. ** |
| resume=true, |
| aborted=true) ]]> </picture> |
| <p> |
| For delivery-tag 12 both the sender and receiver have attained the same view of the terminal |
| outcome, but neither has settled. In this case the sender should simply settle the delivery. |
| </p> |
| <picture><![CDATA[ |
| TRANSFER(delivery-id=9, ----------> ** Locally settle the delivery ** |
| delivery-tag=12, |
| settled=true, |
| resume=true) ]]> </picture> |
| <p> |
| For delivery-tag 13 the sender and receiver have both attained terminal outcomes, but the |
| outcomes differ. In this case, since the outcome actually takes effect at the sender, it is |
| the sender's view that is definitive. The sender thus MUST restate this as the terminal |
| outcome, and the receiver should then echo this and settle. |
| </p> |
| <picture><![CDATA[ |
| TRANSFER(delivery-id=10 ----------> ** Update any state affected ** |
| delivery-tag=13, ** by the actual outcome, then ** |
| settled=false, ** settle the delivery ** |
| state=Accepted |
| resume=true) |
| <---------- DISPOSITION(first=10, last=10, |
| state=Accepted, |
| settled=true) ]]> </picture> |
| <p> |
| For delivery-tag 14 the case is essentially the same as for delivery-tag 11, as the null |
| state at the receiver is essentially identical to having the state |
| Received{section-number=0, section-offset=0}. |
| </p> |
| <picture><![CDATA[ |
| TRANSFER(delivery-id=11, ----------> ** Discard any state relating ** |
| delivery-tag=14, ** to the message delivery. ** |
| resume=true, |
| aborted=true) ]]> </picture> |
| |
| </doc> |
| </section> |
| |
| <section name="addressing" title="Sources and Targets" |
| label="concrete sources and targets defined for messaging"> |
| <doc> |
| <p> |
| The messaging layer defines two concrete types (<xref type="type" name="source"/> and |
| <xref type="type" name="target"/>) to be used as the <i>source</i> and <i>target</i> of a |
| link. These types are supplied in the <i>source</i> and <i>target</i> fields of the |
| <xref type="type" name="attach"/> frame when establishing or resuming link. The |
| <xref type="type" name="source"/> is comprised of an address (which the container of the |
| outgoing Link Endpoint will resolve to a Node within that container) coupled with properties |
| which determine: |
| </p> |
| |
| <ul> |
| <li> |
| <p> |
| which messages from the sending Node will be sent on the Link, |
| </p> |
| </li> |
| |
| <li> |
| <p> |
| how sending the message affects the state of that message at the sending Node, |
| </p> |
| </li> |
| |
| <li> |
| <p> |
| the behavior of Messages which have been transferred on the Link, but have not yet |
| reached a terminal state at the receiver, when the source is destroyed. |
| </p> |
| </li> |
| </ul> |
| </doc> |
| |
| <doc title="Filtering Messages"> |
| <p> |
| A source can restrict the messages transferred from a source by specifying a <i>filter</i>. |
| Filters can be thought of as functions which take the message as input and return a boolean |
| value: true if the message will be accepted by the source, false otherwise. A <i>filter</i> |
| MUST NOT change its return value for a Message unless the state or annotations on the |
| Message at the Node change (e.g. through an updated delivery state). |
| </p> |
| </doc> |
| |
| <doc title="Distribution Modes"> |
| <p> |
| The Source defines an optional distribution-mode that informs and/or indicates how |
| distribution nodes are to behave with respect to the Link. The distribution-mode of a Source |
| determines how Messages from a distribution node are distributed among its associated Links. |
| There are two defined distribution-modes: <i>move</i> and <i>copy</i>. When specified, the |
| distribution-mode has two related effects on the behavior of a distribution node with |
| respect to the Link associated with the Source. |
| </p> |
| |
| <p> |
| The <i>move</i> distribution-mode causes messages transferred from the distribution node to |
| transition to the ACQUIRED state prior to transfer over the link, and subsequently to the |
| ARCHIVED state when the transfer is settled with a successful outcome. The <i>copy</i> |
| distribution-mode leaves the state of the Message unchanged at the distribution node. |
| </p> |
| |
| <p> |
| A Source MUST NOT resend a Message which has previously been successfully transferred from |
| the Source, i.e. reached an ACCEPTED delivery state at the receiver. For a |
| <i>move</i> link with a default configuration this is trivially achieved as such an end |
| result will lead to the Message in the ARCHIVED state on the Node, and thus anyway |
| ineligible for transfer. For a <i>copy</i> link, state must be retained at the source to |
| ensure compliance. In practice, for nodes which maintain a strict order on Messages at the |
| node, the state may simply be a record of the most recent Message transferred. |
| </p> |
| </doc> |
| |
| <type class="composite" name="source" provides="source" source="list"> |
| <descriptor name="amqp:source:list" code="0x00000000:0x00000028"/> |
| <doc> |
| <p> |
| For containers which do not implement address resolution (and do not admit spontaneous |
| link attachment from their partners) but are instead only used as producers of messages, |
| it is unnecessary to provide spurious detail on the source. For this purpose it is |
| possible to use a "minimal" source in which all the fields are left unset. |
| </p> |
| </doc> |
| <field name="address" type="*" requires="address" label="the address of the source"> |
| <doc> |
| <p> |
| The address of the source MUST NOT be set when sent on a <xref type="type" |
| name="attach"/> frame sent by the receiving Link Endpoint where the dynamic flag is set |
| to true (that is where the receiver is requesting the sender to create an addressable |
| node). |
| </p> |
| <p> |
| The address of the source MUST be set when sent on a <xref type="type" name="attach"/> |
| frame sent by the sending Link Endpoint where the dynamic flag is set to true (that is |
| where the sender has created an addressable node at the request of the receiver and is |
| now communicating the address of that created node). The generated name of the address |
| SHOULD include the link name and the container-id of the remote container to allow for |
| ease of identification. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="durable" type="terminus-durability" default="none" |
| label="indicates the durability of the terminus"> |
| <doc> |
| <p> |
| Indicates what state of the terminus will be retained durably: the state of durable |
| messages, only existence and configuration of the terminus, or no state at all. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="expiry-policy" type="terminus-expiry-policy" default="session-end" |
| label="the expiry policy of the Source"> |
| <doc> |
| <p> |
| See <xref name="terminus-expiry-policy"/>. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="timeout" type="seconds" default="0" |
| label="duration that an expiring Source will be retained"> |
| <doc> |
| <p> |
| The Source starts expiring as indicated by the expiry-policy. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="dynamic" type="boolean" default="false" |
| label="request dynamic creation of a remote Node"> |
| <doc> |
| <p> |
| When set to true by the receiving Link endpoint, this field constitutes a request for |
| the sending peer to dynamically create a Node at the source. In this case the address |
| field MUST NOT be set. |
| </p> |
| <p> |
| When set to true by the sending Link Endpoint this field indicates creation of a |
| dynamically created Node. In this case the address field will contain the address of the |
| created Node. The generated address SHOULD include the Link name and Session-name or |
| client-id in some recognizable form for ease of traceability. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="dynamic-node-properties" type="node-properties" |
| label="properties of the dynamically created Node"> |
| <doc> |
| <p> |
| If the dynamic field is not set to true this field must be left unset. |
| </p> |
| <p> |
| When set by the receiving Link endpoint, this field contains the desired properties of |
| the Node the receiver wishes to be created. When set by the sending Link endpoint this |
| field contains the actual properties of the dynamically created node. See <xref |
| name="node-properties"/>. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="distribution-mode" type="symbol" requires="distribution-mode" |
| label="the distribution mode of the Link"> |
| <doc> |
| <p> |
| This field MUST be set by the sending end of the Link if the endpoint supports more than |
| one distribution-mode. This field MAY be set by the receiving end of the Link to |
| indicate a preference when a Node supports multiple distribution modes. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="filter" type="filter-set" |
| label="a set of predicates to filter the Messages admitted onto the Link"> |
| <doc> |
| <p> |
| See <xref name="filter-set"/>. The receiving endpoint sets its desired filter, the |
| sending endpoint sets the filter actually in place (including any filters defaulted |
| at the node). The receiving endpoint MUST check that the filter in place meets its |
| needs and take responsibility for detaching if it does not. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="default-outcome" type="*" requires="outcome" |
| label="default outcome for unsettled transfers"> |
| <doc> |
| <p> |
| Indicates the outcome to be used for transfers that have not reached a terminal state at |
| the receiver when the transfer is settled, including when the Source is destroyed. The |
| value MUST be a valid outcome (e.g. <xref name="released"/> or <xref name="rejected"/>). |
| </p> |
| </doc> |
| </field> |
| |
| <field name="outcomes" type="symbol" multiple="true" |
| label="descriptors for the outcomes that can be chosen on this link"> |
| <doc> |
| <p> |
| The values in this field are the symbolic descriptors of the outcomes that can be chosen |
| on this link. This field MAY be empty, indicating that the <i>default-outcome</i> will |
| be assumed for all message transfers (if the default-outcome is not set, and no outcomes |
| are provided, then the <xref name="accepted"/> outcome must be supported by the source). |
| </p> |
| <p> |
| When present, the values MUST be a symbolic descriptor of a valid outcome, e.g. |
| "amqp:accepted:list". |
| </p> |
| </doc> |
| </field> |
| |
| <field name="capabilities" type="symbol" multiple="true" |
| label="the extension capabilities the sender supports/desires"> |
| <doc> |
| <p> |
| See <xref type="extern" |
| name="http://www.amqp.org/specification/1.0/source-capabilities"/>. |
| </p> |
| </doc> |
| </field> |
| </type> |
| |
| <type class="composite" name="target" provides="target" source="list"> |
| |
| <descriptor name="amqp:target:list" code="0x00000000:0x00000029"/> |
| |
| <doc> |
| <p> |
| For containers which do not implement address resolution (and do not admit spontaneous |
| link attachment from their partners) but are instead only used as consumers of messages, |
| it is unnecessary to provide spurious detail on the source. For this purpose it is |
| possible to use a "minimal" target in which all the fields are left unset. |
| </p> |
| </doc> |
| |
| <field name="address" type="*" requires="address" label="The address of the target."> |
| <doc> |
| <p> |
| The address of the target MUST NOT be set when sent on a <xref type="type" |
| name="attach"/> frame sent by the sending Link Endpoint where the dynamic flag is set |
| to true (that is where the sender is requesting the receiver to create an addressable |
| node). |
| </p> |
| <p> |
| The address of the source MUST be set when sent on a <xref type="type" name="attach"/> |
| frame sent by the receiving Link Endpoint where the dynamic flag is set to true (that |
| is where the receiver has created an addressable node at the request of the sender and |
| is now communicating the address of that created node). The generated name of the |
| address SHOULD include the link name and the container-id of the remote container to |
| allow for ease of identification. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="durable" type="terminus-durability" default="none" |
| label="indicates the durability of the terminus"> |
| <doc> |
| <p> |
| Indicates what state of the terminus will be retained durably: the state of durable |
| messages, only existence and configuration of the terminus, or not state at all. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="expiry-policy" type="terminus-expiry-policy" default="session-end" |
| label="the expiry policy of the Target"> |
| <doc> |
| <p> |
| See <xref name="terminus-expiry-policy"/>. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="timeout" type="seconds" default="0" |
| label="duration that an expiring Target will be retained"> |
| <doc> |
| <p> |
| The Target starts expiring as indicated by the expiry-policy. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="dynamic" type="boolean" default="false" |
| label="request dynamic creation of a remote Node"> |
| <doc> |
| <p> |
| When set to true by the sending Link endpoint, this field constitutes a request for |
| the receiving peer to dynamically create a Node at the target. In this case the address |
| field MUST NOT be set. |
| </p> |
| <p> |
| When set to true by the receiving Link Endpoint this field indicates creation of a |
| dynamically created Node. In this case the address field will contain the address of the |
| created Node. The generated address SHOULD include the Link name and Session-name or |
| client-id in some recognizable form for ease of traceability. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="dynamic-node-properties" type="node-properties" |
| label="properties of the dynamically created Node"> |
| <doc> |
| <p> |
| If the dynamic field is not set to true this field must be left unset. |
| </p> |
| <p> |
| When set by the sending Link endpoint, this field contains the desired properties of |
| the Node the sender wishes to be created. When set by the receiving Link endpoint this |
| field contains the actual properties of the dynamically created node. See <xref |
| name="node-properties"/>. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="capabilities" type="symbol" multiple="true" |
| label="the extension capabilities the sender supports/desires"> |
| <doc> |
| <p> |
| See <xref type="extern" |
| name="http://www.amqp.org/specification/1.0/target-capabilities"/>. |
| </p> |
| </doc> |
| </field> |
| </type> |
| |
| <type class="restricted" name="terminus-durability" source="uint" |
| label="durability policy for a Terminus"> |
| <doc> |
| <p> |
| Determines which state of the Terminus is held durably |
| value. |
| </p> |
| </doc> |
| <choice name="none" value="0"> |
| <doc> |
| <p> |
| No Terminus state is retained durably. |
| </p> |
| </doc> |
| </choice> |
| <choice name="configuration" value="1"> |
| <doc> |
| <p> |
| Only the existence and configuration of the Terminus is retained durably. |
| </p> |
| </doc> |
| </choice> |
| <choice name="unsettled-state" value="2"> |
| <doc> |
| <p> |
| In addition to the existence and configuration of the Terminus, the unsettled state for |
| durable messages is retained durably. |
| </p> |
| </doc> |
| </choice> |
| </type> |
| |
| <type class="restricted" name="terminus-expiry-policy" source="symbol" |
| label="expiry policy for a Terminus"> |
| <doc> |
| <p> |
| Determines when the expiry timer of a Terminus starts counting down from the timeout |
| value. If the link is subsequently re-attached before the Terminus is expired, then the |
| count down is aborted. If the conditions for the terminus-expiry-policy are subsequently |
| re-met, the expiry timer restarts from its originally configured timeout value. |
| </p> |
| </doc> |
| <choice name="link-detach" value="link-detach"> |
| <doc> |
| <p> |
| The expiry timer starts when Terminus is detached. |
| </p> |
| </doc> |
| </choice> |
| <choice name="session-end" value="session-end"> |
| <doc> |
| <p>The expiry timer starts when the most recently associated session is ended.</p> |
| </doc> |
| </choice> |
| <choice name="connection-close" value="connection-close"> |
| <doc> |
| <p>The expiry timer starts when most recently associated connection is closed.</p> |
| </doc> |
| </choice> |
| <choice name="never" value="never"> |
| <doc> |
| <p>The Terminus never expires.</p> |
| </doc> |
| </choice> |
| </type> |
| |
| <type class="restricted" name="std-dist-mode" source="symbol" provides="distribution-mode" |
| label="Link distribution policy"> |
| <doc> |
| <p> |
| Policies for distributing Messages when multiple Links are connected to the same Node. |
| </p> |
| </doc> |
| |
| <choice name="move" value="move"> |
| <doc> |
| <p> |
| once successfully transferred over the Link, the Message will no longer be available to |
| other Links from the same Node |
| </p> |
| </doc> |
| </choice> |
| |
| <choice name="copy" value="copy"> |
| <doc> |
| <p> |
| once successfully transferred over the Link, the Message is still available for other |
| Links from the same Node |
| </p> |
| </doc> |
| </choice> |
| </type> |
| |
| <type class="restricted" name="filter-set" source="map"> |
| <doc> |
| <p> |
| A set of named filters. Every key in the map must be of type <xref type="type" |
| name="symbol"/>, every value must be ether <xref type="type" name="null"/> or of a |
| described type which provides the archetype <i>filter</i>. A filter acts as a function on |
| a message which returns a boolean result indicating whether the message may pass through |
| that filter or not. A message will pass through a filter-set if and only if it passes |
| through each of the named filters. If the value for a given key is null, this acts as if |
| there were no such key present (i.e. all messages pass through the null filter). |
| </p> |
| <p> |
| Filter types are a defined extension point. The filter types that a given |
| <xref name="source"/> supports will be indicated by the capabilities of the |
| <xref name="source"/>. Common filter types, along with the capabilities they are |
| associated with are registered here: <xref type="extern" |
| name="http://www.amqp.org/specification/1.0/filters"/>. |
| </p> |
| </doc> |
| </type> |
| |
| <type class="restricted" name="node-properties" source="fields" label="properties of a Node"> |
| <doc> |
| <p> |
| A symbol-keyed map containing properties of a Node - used when requesting creation or |
| reporting the creation of a dynamic Node. |
| </p> |
| <p> |
| The following common properties are defined: |
| </p> |
| <dl> |
| <dt>lifetime-policy</dt> |
| <dd> |
| <p> |
| The lifetime of a dynamically generated node. |
| </p> |
| <p> |
| Definitionally, the lifetime will never be less than the lifetime of the link which |
| caused its creation, however it is possible to extend the lifetime of dynamically |
| created node using a lifetime policy. The value of this entry must be one of the |
| defined <i>lifetime-policies</i>: <xref name="delete-on-close"/>, |
| <xref name="delete-on-no-links"/>, <xref name="delete-on-no-messages"/> or |
| <xref name="delete-on-no-links-or-messages"/>. |
| </p> |
| </dd> |
| <dt>supported-dist-modes</dt> |
| <dd> |
| <p> |
| The distribution modes that the node supports. |
| </p> |
| <p> |
| The value of this entry must be one or more symbols which are valid |
| <i>distribution-mode</i>s. That is the value must be of the same type as would be |
| valid in a field defined as with the following attributes: |
| </p> |
| <p> |
| <i>type="symbol" multiple="true" requires="distribution-mode"</i> |
| </p> |
| </dd> |
| </dl> |
| </doc> |
| </type> |
| |
| <type class="composite" name="delete-on-close" source="list" provides="lifetime-policy" |
| label="lifetime of dynamic Node scoped to lifetime of link which caused creation"> |
| <doc> |
| <p> |
| A Node dynamically created with this lifetime policy will be deleted at the point that |
| the Link which caused its creation ceases to exist. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:delete-on-close:list" code="0x00000000:0x0000002b"/> |
| |
| </type> |
| |
| <type class="composite" name="delete-on-no-links" source="list" provides="lifetime-policy" |
| label="lifetime of dynamic Node scoped to existence of links to the Node"> |
| <doc> |
| <p> |
| A Node dynamically created with this lifetime policy will be deleted at the point that |
| there remain no Links for which the node is either the source or target. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:delete-on-no-links:list" code="0x00000000:0x0000002c"/> |
| |
| </type> |
| |
| <type class="composite" name="delete-on-no-messages" source="list" provides="lifetime-policy" |
| label="lifetime of dynamic Node scoped to existence of messages on the Node"> |
| <doc> |
| <p> |
| A Node dynamically created with this lifetime policy will be deleted at the point that |
| the Link which caused its creation no longer exists and there remain no Messages at the |
| Node. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:delete-on-no-messages:list" code="0x00000000:0x0000002d"/> |
| |
| </type> |
| |
| <type class="composite" name="delete-on-no-links-or-messages" source="list" |
| provides="lifetime-policy" |
| label="lifetime of Node scoped to existence of messages on or links to the Node"> |
| <doc> |
| <p> |
| A Node dynamically created with this lifetime policy will be deleted at the point that |
| the there are no Links which have this Node as their source or target, and there remain |
| no Messages at the Node. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:delete-on-no-links-or-messages:list" code="0x00000000:0x0000002e"/> |
| |
| </type> |
| |
| </section> |
| |
| </amqp> |