resources/messaging.xml
<?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>