Google Git
Sign in
apache / qpid / 7e34266b9a23f4536415bfbc3f161b84615b6550 / . / RC9 / qpid / specs / amqp.0-10-preview.xml
blob: 5af956e75d14fa2df8a70726eb6068d182776c5f [file] [log] [blame]
<?xml version="1.0"?>
<!--
EDITORS: (PH) Pieter Hintjens <ph@imatix.com>
(KvdR) Kim van der Riet <kim.vdriet@redhat.com>
These editors have been assigned by the AMQP working group. Please do not edit/commit this file
without consulting with one of the above editors.
========================================================
TODOs
- see TODO comments in the text
-->
<!--
Copyright Notice
================
(c) Copyright JPMorgan Chase Bank & Co., Cisco Systems, Inc., Envoy Technologies Inc., iMatix
Corporation, IONA\ufffd Technologies, Red Hat, Inc., TWIST Process Innovations, and 29West Inc.
2006. All rights reserved.
License
=======
JPMorgan Chase Bank & Co., Cisco Systems, Inc., Envoy Technologies Inc., iMatix Corporation, IONA
Technologies, Red Hat, Inc., TWIST Process Innovations, and 29West 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 Messaging Queue
Protocol ("AMQP") Specification and (ii) the Licensed Claims that are held by the Authors, all for
the purpose of implementing the Advanced Messaging Queue 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 Messaging Queue Protocol
Specification against any Author. Upon termination, you shall destroy all copies of the Advanced
Messaging Queue 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 Messaging Queue 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
Messaging Queue 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 Messaging Queue
Protocol Specification that are not required by the Advanced Messaging Queue 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 Messaging Queue 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 Messaging Queue
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 Messaging Queue Protocol
Specification. For purposes of this definition, the Advanced Messaging Queue 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 Messaging Queue 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 Messaging Queue Protocol Specification.
The following disclaimers, which you hereby also acknowledge as to any use you may make of the
Advanced Messaging Queue Protocol Specification:
THE ADVANCED MESSAGING QUEUE 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 MESSAGING QUEUE PROTOCOL SPECIFICATION ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE
IMPLEMENTATION OF THE ADVANCED MESSAGING QUEUE 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
MESSAGING QUEUE PROTOCOL SPECIFICATION.
The name and trademarks of the Authors may NOT be used in any manner, including advertising or
publicity pertaining to the Advanced Messaging Queue Protocol Specification or its contents
without specific, written prior permission. Title to copyright in the Advanced Messaging Queue
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 Messaging Queue 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.
IMATIX and the iMatix logo are trademarks of iMatix Corporation sprl.
IONA, IONA Technologies, and the IONA logos are trademarks of IONA Technologies PLC and/or its
subsidiaries.
LINUX is a trademark of Linus Torvalds. RED HAT and JBOSS are registered trademarks of Red Hat,
Inc. in the US and other countries.
Java, all Java-based trademarks and OpenOffice.org are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.
Links to full AMQP specification:
=================================
http://www.envoytech.org/spec/amq/
http://www.iona.com/opensource/amqp/
http://www.redhat.com/solutions/specifications/amqp/
http://www.twiststandards.org/tiki-index.php?page=AMQ
http://www.imatix.com/amqp
-->
<!--
XML Notes
=========
We use entities to indicate repetition; attributes to indicate properties.
We use the "name" attribute as an identifier, usually within the context of the surrounding
entities.
We use hyphens (minus char '-') to seperate words in names.
We do not enforce any particular validation mechanism but we support all mechanisms. The protocol
definition conforms to a formal grammar that is published seperately in several technologies.
-->
<!--
<!DOCTYPE amqp SYSTEM "amqp.dtd">
-->
<amqp xmlns="http://www.amqp.org/schema/amqp.xsd"
major="99" minor="0" port="5672" comment="AMQ Protocol (Working version)">
<!--
======================================================
== CONSTANTS
======================================================
-->
<!-- Frame types -->
<constant name="frame-method" value="1" />
<constant name="frame-header" value="2" />
<constant name="frame-body" value="3" />
<constant name="frame-trace" value="7" />
<constant name="frame-heartbeat" value="8" />
<!-- Protocol constants -->
<constant name="frame-min-size" value="4096" />
<constant name="frame-end" value="206" />
<!-- Reply codes -->
<constant name="reply-success" value="200">
<doc>
Indicates that the method completed successfully. This reply code is reserved for future use -
the current protocol design does not use positive confirmation and reply codes are sent only
in case of an error.
</doc>
</constant>
<constant name="not-delivered" value="310" class="soft-error">
<doc>
The client asked for a specific message that is no longer available. The message was delivered
to another client, or was purged from the queue for some other reason.
</doc>
</constant>
<constant name="content-too-large" value="311" class="soft-error">
<doc>
The client attempted to transfer content larger than the server could accept at the present
time. The client may retry at a later time.
</doc>
</constant>
<constant name="no-route" value="312" class="soft-error">
<doc>
When the exchange cannot route the result of a .Publish, most likely due to an invalid routing
key. Only when the mandatory flag is set.
</doc>
</constant>
<constant name="no-consumers" value="313" class="soft-error">
<doc>
When the exchange cannot deliver to a consumer when the immediate flag is set. As a result of
pending data on the queue or the absence of any consumers of the queue.
</doc>
</constant>
<constant name="connection-forced" value="320" class="hard-error">
<doc>
An operator intervened to close the connection for some reason. The client may retry at some
later date.
</doc>
</constant>
<constant name="invalid-path" value="402" class="hard-error">
<doc>
The client tried to work with an unknown virtual host.
</doc>
</constant>
<constant name="access-refused" value="403" class="soft-error">
<doc>
The client attempted to work with a server entity to which it has no access due to security
settings.
</doc>
</constant>
<constant name="not-found" value="404" class="soft-error">
<doc>
The client attempted to work with a server entity that does not exist.
</doc>
</constant>
<constant name="resource-locked" value="405" class="soft-error">
<doc>
The client attempted to work with a server entity to which it has no access because another
client is working with it.
</doc>
</constant>
<constant name="precondition-failed" value="406" class="soft-error">
<doc>
The client requested a method that was not allowed because some precondition failed.
</doc>
</constant>
<constant name="session-busy" value="407" class="soft-error">
<doc>
A session.resume was attempted for a session already attached to another channel.
</doc>
</constant>
<constant name="frame-error" value="501" class="hard-error">
<doc>
The client sent a malformed frame that the server could not decode. This strongly implies a
programming error in the client.
</doc>
</constant>
<constant name="syntax-error" value="502" class="hard-error">
<doc>
The client sent a frame that contained illegal values for one or more fields. This strongly
implies a programming error in the client.
</doc>
</constant>
<constant name="command-invalid" value="503" class="hard-error">
<doc>
The client sent an invalid sequence of frames, attempting to perform an operation that was
considered invalid by the server. This usually implies a programming error in the client.
</doc>
</constant>
<!-- TODO: Should this be renamed to "session-error" since class channel has been replaced by
class session? -->
<constant name="channel-error" value="504" class="hard-error">
<doc>
The client attempted to work with a channel that had not been correctly opened. This most
likely indicates a fault in the client layer.
</doc>
</constant>
<constant name="resource-error" value="506" class="hard-error">
<doc>
The server could not complete the method because it lacked sufficient resources. This may be
due to the client creating too many of some type of entity.
</doc>
</constant>
<constant name="not-allowed" value="530" class="hard-error">
<doc>
The client tried to work with some entity in a manner that is prohibited by the server, due to
security settings or by some other criteria.
</doc>
</constant>
<constant name="not-implemented" value="540" class="hard-error">
<doc>
The client tried to use functionality that is not implemented in the server.
</doc>
</constant>
<constant name="internal-error" value="541" class="hard-error">
<doc>
The server could not complete the method because of an internal error. The server may require
intervention by an operator in order to resume normal operations.
</doc>
</constant>
<constant name="invalid-argument" value="542" class="hard-error">
<doc>
An invalid or illegal argument was passed to a method, and the operation could not proceed.
</doc>
</constant>
<constant name="channel-busy" value="543" class="hard-error">
<doc>
A session.open was sent on a channel that was already attached to a session.
</doc>
</constant>
<!-- XA constants -->
<constant name="xa-ok" value="0">
<doc>
XA return code: Normal execution completion (no error).
</doc>
</constant>
<constant name="xa-rbrollback" value="1">
<doc>
XA return code: The rollback was caused for an unspecified reason.
</doc>
</constant>
<constant name="xa-rbtimeout" value="2">
<doc>
XA return code: A transaction branch took too long.
</doc>
</constant>
<constant name="xa-heurhaz" value="3">
<doc>
XA return code: The transaction branch may have been heuristically completed.
</doc>
</constant>
<constant name="xa-heurcom" value="4">
<doc>
XA return code: The transaction branch has been heuristically committed.
</doc>
</constant>
<constant name="xa-heurrb" value="5">
<doc>
XA return code: The transaction branch has been heuristically rolled back.
</doc>
</constant>
<constant name="xa-heurmix" value="6">
<doc>
XA return code: The transaction branch has been heuristically committed and rolled back.
</doc>
</constant>
<constant name="xa-rdonly" value="7">
<doc>
XA return code: The transaction branch was read-only and has been committed.
</doc>
</constant>
<!--
================================
== Field Table type constants ==
================================
-->
<!--
0x00 - 0x0f: Fixed width, 1 octet
-->
<constant name="field-table-octet" value="0x00" width="1" datatype="binary"
class="field-table-type">
<doc>
Octet of unspecified encoding
</doc>
</constant>
<constant name="field-table-signed-byte" value="0x01" width="1" datatype="signed-integer"
class="field-table-type">
<doc>
8-bit signed integral value (-128 - 127)
</doc>
</constant>
<constant name="field-table-unsigned-byte" value="0x02" width="1" datatype="unsigned-integer"
class="field-table-type">
<doc>
8-bit unsigned integral value (0 - 255)
</doc>
</constant>
<constant name="field-table-char" value="0x04" width="1" datatype="char"
class="field-table-type">
<doc>
8-bit representation of single character in the iso-8859-15 character set
</doc>
</constant>
<constant name="field-table-boolean" value="0x08" width="1" datatype="boolean"
class="field-table-type">
<doc>
Boolean value (0 represents false, 1 represents true)
</doc>
</constant>
<!--
0x10 - 0x1f: Fixed width, 2 octets
-->
<constant name="field-table-two-octets" value="0x10" width="2" datatype="binary"
class="field-table-type">
<doc>
Two octets of unspecified binary encoding
</doc>
</constant>
<constant name="field-table-signed-short" value="0x11" width="2" datatype="signed-integer"
class="field-table-type">
<doc>
16-bit signed integral value
</doc>
</constant>
<constant name="field-table-unsigned-short" value="0x12" width="2" datatype="unsigned-integer"
class="field-table-type">
<doc>
16-bit unsigned integral value
</doc>
</constant>
<!--
0x20 - 0x2f: Fixed width, 4 octets
-->
<constant name="field-table-four-octets" value="0x20" width="4" datatype="binary"
class="field-table-type">
<doc>
Four octets of unspecified binary encoding
</doc>
</constant>
<constant name="field-table-signed-int" value="0x21" width="4" datatype="signed-integer"
class="field-table-type">
<doc>
32-bit signed integral value
</doc>
</constant>
<constant name="field-table-unsigned-int" value="0x22" width="4" datatype="unsigned-integer"
class="field-table-type">
<doc>
32-bit unsigned integral value
</doc>
</constant>
<constant name="field-table-float" value="0x23" width="4" datatype="ieee-float"
class="field-table-type">
<doc>
Single precision IEEE 754 32-bit floating point
</doc>
</constant>
<constant name="field-table-utf32-char" value="0x27" width="4" datatype="char"
class="field-table-type">
<doc>
Single unicode character in UTF-32 encoding
</doc>
</constant>
<!--
0x30 - 0x3f: Fixed width types - 8 octets
-->
<constant name="field-table-eight-octets" value="0x30" width="8" datatype="binary"
class="field-table-type">
<doc>
Eight octets of unspecified binary encoding
</doc>
</constant>
<constant name="field-table-signed-long" value="0x31" width="8" datatype="signed-integer"
class="field-table-type">
<doc>
64-bit signed integral value
</doc>
</constant>
<constant name="field-table-unsigned-long" value="0x32" width="8" datatype="unsigned-integer"
class="field-table-type">
<doc>
64-bit unsigned integral value
</doc>
</constant>
<constant name="field-table-double" value="0x33" width="8" datatype="ieee-float"
class="field-table-type">
<doc>
Double precision IEEE 754 floating point
</doc>
</constant>
<constant name="field-table-datetime" value="0x38" width="8" datatype="special"
class="field-table-type">
<doc>
Datetime in POSIX time_t format
</doc>
</constant>
<!--
0x40 - 0x4f: Fixed width types - 16 octets
-->
<constant name="field-table-sixteen-octets" value="0x40" width="16" datatype="binary"
class="field-table-type">
<doc>
Sixteen octets of unspecified binary encoding
</doc>
</constant>
<constant name="field-table-uuid" value="0x48" width="16" datatype="special"
class="field-table-type">
<doc>
UUID as defined by RFC4122
</doc>
</constant>
<!--
0x50 - 0x5f: Fixed width types - 32 octets
-->
<constant name="field-table-thirty-two-octets" value="0x50" width="32" datatype="binary"
class="field-table-type">
<doc>
Thirty two octets of unspecified binary encoding
</doc>
</constant>
<!--
0x60 - 0x6f: Fixed width types - 64 octets
-->
<constant name="field-table-sixty-four-octets" value="0x60" width="64" datatype="binary"
class="field-table-type">
<doc>
Sixty four octets of unspecified binary encoding
</doc>
</constant>
<!--
0x70 - 0x7f: Fixed width types - 128 octets
-->
<constant name="field-table-128-octets" value="0x70" width="128" datatype="binary"
class="field-table-type">
<doc>
One hundred and twenty eight octets of unspecified binary encoding
</doc>
</constant>
<!--
0x80 - 0x8f: Variable length - one byte length field (up to 255 octets)
-->
<constant name="field-table-short-binary" value="0x80" lfwidth="1" datatype="binary"
class="field-table-type">
<doc>
A sequence of up to 255 octets representing opaque binary data
</doc>
</constant>
<constant name="field-table-short-string" value="0x84" lfwidth="1" datatype="string"
class="field-table-type">
<doc>
A sequence of up to 255 characters in the iso-8859-15 character set
</doc>
</constant>
<constant name="field-table-short-utf8-string" value="0x85" lfwidth="1" datatype="string"
class="field-table-type">
<doc>
A sequence of unicode characters in the utf8 encoding which is able to be encoded in at most
255 bytes
</doc>
</constant>
<constant name="field-table-short-utf16-string" value="0x86" lfwidth="1" datatype="string"
class="field-table-type">
<doc>
A sequence of unicode characters in the utf16 encoding which is able to be encoded in at most
255 bytes
</doc>
</constant>
<constant name="field-table-short-utf32-string" value="0x87" lfwidth="1" datatype="string"
class="field-table-type">
<doc>
A sequence of unicode characters in the utf32 encoding which is able to be encoded in at most
255 bytes (i.e. of 0-63 utf32 characters)
</doc>
</constant>
<!--
0x90 - 0x9f: Variable length types - two byte length field (up to 65535 octets)
-->
<constant name="field-table-binary" value="0x90" lfwidth="2" datatype="binary"
class="field-table-type">
<doc>
A sequence of up to 65535 octets representing opaque binary data
</doc>
</constant>
<constant name="field-table-string" value="0x94" lfwidth="2" datatype="string"
class="field-table-type">
<doc>
A sequence of up to 65535 characters in the iso-8859-15 character set
</doc>
</constant>
<constant name="field-table-utf8-string" value="0x95" lfwidth="2" datatype="string"
class="field-table-type">
<doc>
A sequence of unicode characters in the utf8 encoding which is able to be encoded in at most
65535 bytes
</doc>
</constant>
<constant name="field-table-utf16-string" value="0x96" lfwidth="2" datatype="string"
class="field-table-type">
<doc>
A sequence of unicode characters in the utf16 encoding which is able to be encoded in at most
65535 bytes
</doc>
</constant>
<constant name="field-table-utf32-string" value="0x97" lfwidth="2" datatype="string"
class="field-table-type">
<doc>
A sequence of unicode characters in the utf32 encoding which is able to be encoded in at most
65535 bytes (i.e. of 0-16383 utf32 characters)
</doc>
</constant>
<!--
0xa0 - 0xaf: Variable length types - four byte length field (up to 4294967295 octets)
-->
<constant name="field-table-long-binary" value="0xa0" lfwidth="4" datatype="binary"
class="field-table-type">
<doc>
A sequence of up to 4294967295 octets representing opaque binary data
</doc>
</constant>
<constant name="field-table-long-string" value="0xa4" lfwidth="4" datatype="string"
class="field-table-type">
<doc>
A sequence of up to 4294967295 characters in the iso-8859-15 character set
</doc>
</constant>
<constant name="field-table-long-utf8-string" value="0xa5" lfwidth="4" datatype="string"
class="field-table-type">
<doc>
A sequence of unicode characters in the utf8 encoding which is able to be encoded in at most
4294967295 bytes
</doc>
</constant>
<constant name="field-table-long-utf16-string" value="0xa6" lfwidth="4" datatype="string"
class="field-table-type">
<doc>
A sequence of unicode characters in the utf16 encoding which is able to be encoded in at most
4294967295 bytes
</doc>
</constant>
<constant name="field-table-long-utf32-string" value="0xa7" lfwidth="4" datatype="string"
class="field-table-type">
<doc>
A sequence of unicode characters in the utf32 encoding which is able to be encoded in at most
4294967295 bytes (i.e. of 0-1073741823 utf32 characters)
</doc>
</constant>
<constant name="field-table-table" value="0xa8" lfwidth="4" datatype="field-table"
class="field-table-type">
<doc>
A field table following the encoding specification given here
</doc>
</constant>
<constant name="field-table-sequence" value="0xa9" lfwidth="4" datatype="sequence"
class="field-table-type">
<doc>
A sequence is a series of consecutive type-value pairs; using the same type designators as the
field table
</doc>
</constant>
<constant name="field-table-array" value="0xaa" lfwidth="4" datatype="array"
class="field-table-type">
<doc>
An array represents a collection of values of the same type. The array is encoded as a single
octet type designator (using the same system as given here for the field table), followed by a
four-octet unsigned integer which represents the number of elements in the collection,
followed by the encoding of that number of values of the given type
</doc>
</constant>
<!--
0xb0 - 0xbf: Reserved
-->
<!--
0xc0 - 0xcf:Fixed width types - 5 octets
-->
<constant name="field-table-five-octets" value="0xc0" width="5" datatype="binary"
class="field-table-type">
<doc>
Five octets of unspecified binary encoding
</doc>
</constant>
<constant name="field-table-decimal" value="0xc8" width="5" datatype="decimal"
class="field-table-type">
<doc>
Encoded as an octet representing the number of decimal places followed by a signed 4 octet
integer. The 'decimals' octet is not signed
</doc>
</constant>
<!--
0xd0 - 0xdf: Fixed width types - 9 octets
-->
<constant name="field-table-nine-octets" value="0xd0" width="9" datatype="binary"
class="field-table-type">
<doc>
Eight octets of unspecified binary encoding
</doc>
</constant>
<constant name="field-table-long-decimal" value="0xd8" width="9" datatype="decimal"
class="field-table-type">
<doc>
Encoded as an octet representing the number of decimal places followed by a signed 8 octet
integer. The 'decimals' octet is not signed
</doc>
</constant>
<!--
0xe0 - 0xef: Reserved
-->
<!--
0xf0 - 0xff: Zero-length types
-->
<constant name="field-table-void" value="0xf0" width="0" datatype="void"
class="field-table-type">
<doc>
The void type
</doc>
</constant>
<!--
======================================================
== DOMAIN TYPES
======================================================
-->
<domain name="access-ticket" type="short" label="access ticket granted by server">
<doc>
An access ticket granted by the server for a certain set of access rights within a specific
realm. Access tickets are valid within the session where they were created, and expire when
the session closes.
</doc>
<assert check="ne" value="0" />
</domain>
<domain name="class-id" type="short">
<doc>
<!-- TODO: Description required for docs -->
</doc>
</domain>
<domain name="method-id" type="short">
<doc>
<!-- TODO: Description required for docs -->
</doc>
</domain>
<domain name="consumer-tag" type="shortstr" label="consumer tag">
<doc>
Identifier for the consumer, valid within the current connection.
</doc>
</domain>
<domain name="delivery-tag" type="longlong" label="server-assigned delivery tag">
<doc>
The server-assigned and session-specific delivery tag
</doc>
<rule name="session-local">
<doc>
The delivery tag is valid only within the session from which the message was received. i.e.
A client MUST NOT receive a message on one session and then acknowledge it on another.
</doc>
</rule>
<rule name="non-zero">
<doc>
The server MUST NOT use a zero value for delivery tags. Zero is reserved for client use,
meaning "all messages so far received".
</doc>
</rule>
<assert check="ne" value="0" />
</domain>
<domain name="exchange-name" type="shortstr" label="exchange name">
<doc>
The exchange name is a client-selected string that identifies the exchange for publish
methods. Exchange names may consist of any mixture of digits, letters, and underscores.
Exchange names are scoped by the virtual host.
</doc>
<assert check="regexp" value="[a-zA-Z0-9_]{1,127}">
<doc>
This regular expression checks that all characters are one of a-z (lower case), A-Z (upper
case), 0-9 (any digit) and the underscore character. There may be between 1 and 127 of these
characters.
</doc>
</assert>
</domain>
<domain name="known-hosts" type="shortstr" label="list of known hosts">
<doc>
Specifies the list of equivalent or alternative hosts that the server knows about, which will
normally include the current server itself. Clients can cache this information and use it when
reconnecting to a server after a failure. This field may be empty.
</doc>
</domain>
<domain name="message-id" type="uuid">
<doc>
Message-id is an optional property of UUID type which uniquly identifies a message within the
message system. The message producer is usually responsible for setting the message-id. Note
that the server may discard a message as a duplicate if the value of the message-id matches
that of a previously received message.
</doc>
<rule name="unique">
<doc>
A message MUST be unique within a given server instance. A message SHOULD be globally unique
(i.e. across different systems).
</doc>
</rule>
<rule name="immutable">
<doc>
A message ID is immutable. Once set, a message-id MUST NOT be changed or reassigned, even if
the message is replicated, resent or sent to multiple queues.
</doc>
</rule>
</domain>
<domain name="no-ack" type="bit" label="no acknowledgement needed">
<doc>
If this field is set the server does not expect acknowledgements for messages. That is, when a
message is delivered to the client the server automatically and silently acknowledges it on
behalf of the client. This functionality increases performance but at the cost of reliability.
Messages can get lost if a client dies before it can deliver them to the application.
</doc>
</domain>
<domain name="no-local" type="bit" label="do not deliver own messages">
<doc>
If the no-local field is set the server will not send messages to the connection that
published them.
</doc>
</domain>
<domain name="path" type="shortstr">
<doc>
Must start with a slash "/" and continue with path names separated by slashes. A path name
consists of any combination of at least one of [A-Za-z0-9] plus zero or more of [.-_+!=:].
</doc>
<assert check="notnull" />
<assert check="syntax" rule="path" />
<assert check="length" value="127" />
</domain>
<domain name="peer-properties" type="table">
<doc>
This string provides a set of peer properties, used for identification, debugging, and general
information.
</doc>
</domain>
<domain name="queue-name" type="shortstr" label="queue name">
<doc>
The queue name identifies the queue within the vhost. Queue names must have a length of
between 1 and 255 chatacters inclusive, must start with a digit, letter or underscores ('_')
character, and must be otherwise encoded in UTF-8.
</doc>
<assert check="regexp" value="[a-zA-Z0-9_].{0,254}">
<doc>
This regular expression checks that the first character is one of a-z (lower case), A-Z
(upper case), 0-9 (any digit) and the underscore character. Following may be between 0 and
254 characters of any value.
</doc>
</assert>
</domain>
<domain name="redelivered" type="bit" label="message is being redelivered">
<doc>
This indicates that the message has been previously delivered to this or another client.
</doc>
<rule name="implementation">
<doc>
The server SHOULD try to signal redelivered messages when it can. When redelivering a
message that was not successfully acknowledged, the server SHOULD deliver it to the original
client if possible.
</doc>
<doc type="scenario">
Create a shared queue and publish a message to the queue. Consume the message using explicit
acknowledgements, but do not acknowledge the message. Close the connection, reconnect, and
consume from the queue again. The message should arrive with the redelivered flag set.
</doc>
</rule>
<rule name="hinting">
<doc>
The client MUST NOT rely on the redelivered field but should take it as a hint that the
message may already have been processed. A fully robust client must be able to track
duplicate received messages on non-transacted, and locally-transacted sessions.
</doc>
</rule>
</domain>
<domain name="rfc1982-long" type="long" label="serial number with arithmetic per RFC1982">
<doc>
Serial number defined in RFC1982 which defines the arithmatic, operators and ranges of such
numbers.
</doc>
</domain>
<domain name="reply-code" type="short" label="reply code from server">
<doc>
The reply code. The AMQ reply codes are defined as constants at the start of this formal
specification.
</doc>
<assert check="notnull" />
</domain>
<domain name="reply-text" type="shortstr" label="localised reply text">
<doc>
The localised reply text. This text can be logged as an aid to resolving issues.
</doc>
<assert check="notnull" />
</domain>
<!-- Domains for the message class -->
<domain name="duration" type="longlong" label="duration in milliseconds">
<doc>
Duration of an event or process measured in milliseconds.
</doc>
</domain>
<domain name="offset" type="longlong" label="offset into a message body">
<doc>
Offset in bytes into a message body.
</doc>
</domain>
<domain name="reference" type="longstr" label="pointer to a message body">
<doc>
Identifier to be used as a reference to a message body.
</doc>
</domain>
<domain name="destination" type="shortstr" label="destination for a message">
<doc>
Specifies the destination to which the message is to be transferred. The destination can be
empty, meaning the default exchange or consumer.
</doc>
</domain>
<domain name="reject-code" type="short" label="reject code for transfer">
<doc>
Code specifying the reason for a message reject.
</doc>
<rule name="allowed-values">
<doc>
The reject code must be one of 0 (generic) or 1 (immediate delivery was attempted but
failed).
</doc>
</rule>
</domain>
<domain name="reject-text" type="shortstr" label="informational text for message reject">
<doc>
String describing the reason for a message transfer rejection.
</doc>
</domain>
<domain name="security-token" type="longstr" label="security token">
<doc>
A security token used for authentication, replay prevention, and encrypted message bodies.
</doc>
</domain>
<domain name="reply-to">
<struct size="short" pack="short">
<field name="exchange-name" domain="exchange-name" />
<field name="routing-key" domain="shortstr" />
</struct>
</domain>
<domain name="confirm-mode" type="octet" label="indicates a confirmation mode">
<doc>
Controls whether message transfer needs to be confirmed.
One of:
- off (0): confirmation is not required, once a message has been transferred in pre-acquire
mode (or once acquire has been sent in no-acquire mode) the message is considered
transferred
- on (1): an acquired message (whether acquisition was implicit as in pre-acquire mode or
explicit as in no-acquire mode) is not considered transferred until the original
transfer is complete (signaled via execution.complete)
</doc>
</domain>
<domain name="acquire-mode" type="octet" label="indicates the transfer mode">
<doc>
Indicates whether a transferred message can be considered as automatically acquired or whether
an explicit request is necessary in order to acquire it.
One of:
- no-acquire (0): the message must be explicitly acquired
- pre-acquire (1): the message is acquired when the transfer starts
</doc>
</domain>
<!-- message header domains -->
<domain name="delivery-properties">
<struct size="long" pack="short" type="0">
<field name="discard-unroutable" domain="bit" label="controls discard of unroutable messages">
<doc>
If set on a message that is not routable the broker can discard it. If not set unroutable
should be handled by reject when confirmation is on or by routing to the
alternate-exchange if defined when confirmation is off.
</doc>
</field>
<field name="redelivered" domain="redelivered" label="redelivery flag">
<doc>
This boolean flag indicates that the message has been previously delivered to this or
another client.
</doc>
</field>
<field name="priority" domain="octet" label="message priority, 0 to 9">
<doc>
Message priority, which can be between 0 and 9. Messages with higher priorities may be
delivered before those with lower priorities.
</doc>
</field>
<field name="delivery-mode" domain="octet" label="message persistence">
<doc>
The delivery mode may be non-persistent (1) or persistent (2). A persistent message is one
which must be stored on a persistent medium (usually hard drive) at every stage of
delivery so that it will not be lost in event of failure (other than the medium itself).
This is normally accomplished with some additional overhead. A persistent message may be
delivered more than once if there is uncertainty about the state of its delivery after a
failure and recovery.
Conversely, a non-persistent message may be lost in event of a failure, but the nature of
the communication is such that an occasional message loss is tolerable. This is the lowest
overhead mode. Non-persistent messages are delivered at most once only.
</doc>
</field>
<field name="ttl" domain="duration" label="time to live">
<doc>
If this is set to a non zero value then a message expiration time will be computed based
on the current time plus this value. Messages that live longer than their expiration time
will be discarded (or dead lettered).
</doc>
<rule name="ttl-decrement">
<doc>
If a message is transferred between brokers before delivery to a final consumer the ttl
should be decremented before peer to peer transfer and both timestamp and expiration
should be cleared.
</doc>
</rule>
</field>
<field name="timestamp" domain="timestamp" label="message timestamp">
<doc>
The timestamp is set by the broker on arrival of the message.
</doc>
</field>
<field name="expiration" domain="timestamp" label="message expiration time">
<doc>
The expiration header assigned by the broker. After receiving the message the broker sets
expiration to the sum of the ttl specified in the publish method and the current time.
(ttl=expiration - timestamp)
</doc>
</field>
<field name="exchange" domain="exchange-name" label="originating exchange">
<doc>
The exchange name is a client-selected string that identifies the exchange for transfer
methods. Exchange names may consist of any mixture of digits, letters, and underscores.
Exchange names are scoped by the virtual host.
</doc>
</field>
<field name="routing-key" domain="shortstr" label="message routing key">
<doc>
The value of the key determines to which queue the exchange will send the message. The way
in which keys are used to make this routing decision depends on the type of exchange to
which the message is sent. For example, a direct exchange will route a message to a queue
if that queue is bound to the exchange with an identical key to that of the message.
</doc>
</field>
</struct>
</domain>
<domain name="message-properties">
<struct size="long" pack="short" type="1">
<field name="content-length" domain="longlong" label="length of content in bytes">
<doc>
The length of the message content in bytes.
</doc>
</field>
<field name="message-id" domain="shortstr" label="application message identifier">
<doc>
This is a unique identifier for the message that is guaranteed to be unique across
multiple instances, sessions and in time. This allows duplicate messages to be detected.
This may be a UUID. Note that this is usually set by the server when it first receives a
message.
If a client wishes to identify a message, it should use the correlation-id instead.
</doc>
</field>
<field name="correlation-id" domain="shortstr" label="application correlation identifier">
<doc>
This is a client-specific id that may be used to mark or identify messages between
clients. The server ignores this field.
</doc>
</field>
<field name="reply-to" domain="reply-to" label="destination to reply to">
<doc>
The destination of any message that is sent in reply to this message.
</doc>
</field>
<field name="content-type" domain="shortstr" label="MIME content type">
<doc>
The RFC-2046 MIME type for the message content (such as "text/plain"). This is set by the
originating client.
</doc>
</field>
<field name="content-encoding" domain="shortstr" label="MIME content encoding">
<doc>
The encoding for character-based message content. This is set by the originating client.
Examples include UTF-8 and ISO-8859-16.
</doc>
</field>
<field name="type" domain="shortstr" label="message type name">
<doc>
The JMS message type.
</doc>
</field>
<field name="user-id" domain="shortstr" label="creating user id">
<doc>
The identity of the user responsible for producing the message.
</doc>
</field>
<field name="app-id" domain="shortstr" label="creating application id">
<doc>
The identity of the client application responsible for producing the message.
</doc>
</field>
<field name="transaction-id" domain="shortstr" label="distributed transaction id">
<doc>
An identifier that links this message to a distributed transaction.
</doc>
</field>
<field name="security-token" domain="security-token" label="security token">
<doc>
A security token used for authentication, replay prevention, and encrypted message bodies.
</doc>
</field>
<field name="application-headers" domain="table" label="application specific headers table">
<doc>
This is a collection of user-defined headers or properties which may be set by the
producing client and retrieved by the consuming client. Similar to JMS Properties.
</doc>
</field>
</struct>
</domain>
<!-- Domians for DTX -->
<domain name="xid" type="longstr" label="Dtx branch identifier">
<doc>
An xid uniquely identifies a transaction branch.
</doc>
<rule name="implementation">
<doc>
xid contains a format identifier, two length fields and a data field:
format_id long
gtrid_length octet
bqual_length octet
data gtrid_length + bqual_length
</doc>
<doc type="picture">
4 1 1 g b
+---+---+---+---+---+---+---+- -+---+---+- -+---+
| format_id | g | b | txn-id | br-id |
+---+---+---+---+---+---+---+- -+---+---+- -+---+
0 4 5 6 6+g 6+g+b
</doc>
<doc>
format_id: an implementation specific format identifier
gtrid_length: how many bytes of this form the transaction id
bqual_length: how many bytes of this form the branch id
data: a sequence of octets of at most 128 bytes containing the txn id and the
branch id
Note - The sum of the two lengths must equal the length of the data field.
</doc>
</rule>
</domain>
<!-- Domains for session class -->
<domain name="detached-lifetime" type="long" label="possibly unbounded duration in seconds">
<doc>
Detached-lifetime is an integer encoded as follows:
* the maximum representable value means unbounded - the maximum length permitted by the peer
* otherwise, any other value (including zero) is the number of seconds the session's state
is retained during periods when no channel (or equivalent) is attached to the session
(DetachedLifetimeFinite above).
</doc>
</domain>
<domain name="session-id" type="uuid" label="session identifier" />
<!-- Domains for the execution class -->
<domain name="correlation" type="rfc1982-long-set">
<doc>
Identifies a set of commands inside the window of open conversations.
</doc>
</domain>
<domain name="command-id" type="long"/>
<domain name="long-struct" type="long-struct">
<doc>
Any typed struct whose size width is long.
</doc>
</domain>
<domain name="execution-header">
<doc>
The execution header appears on commands after the class and method id, but prior to method
arguments.
</doc>
<struct size="octet" pack="octet">
<field name="sync" domain="bit" label="request notification of completion for a specific command">
<doc>
Indicates that the peer sending the request wants to be notified when this command is
completed.
</doc>
</field>
</struct>
</domain>
<!-- Elementary domains -->
<domain name="bit" type="bit" label="single bit" />
<domain name="octet" type="octet" label="single octet" />
<domain name="short" type="short" label="16-bit integer" />
<domain name="long" type="long" label="32-bit integer" />
<domain name="longlong" type="longlong" label="64-bit integer" />
<domain name="shortstr" type="shortstr" label="short string" />
<domain name="longstr" type="longstr" label="long string" />
<domain name="timestamp" type="timestamp" label="64-bit POSIX timestamp" />
<domain name="table" type="table" label="field table" />
<domain name="uuid" type="uuid" label="UUID (RFC4122 section 4.1.2) - 16 octets" />
<domain name="array" type="array" label="array"/>
<domain name="content" type="content" label="message content">
<doc>
Content of a message. It should be considered opaque binary data. The length of the message is
determined from the context of this type (the message length field of the message.transfer
method).
</doc>
</domain>
<domain name="rfc1982-long-set" type="rfc1982-long-set" label="ranged set representation">
<doc>
Set of pairs of RFC-1982 numbers representing a discontinuous range. Each pair represents a
closed interval within the list.
For example, the set (1,3), (6,6), (8,9) represents the sequence 1,2,3,6,8,9.
</doc>
</domain>
<!-- == Class: connection ==================================================================== -->
<class name="connection" index="10" label="work with socket connections">
<doc>
The connection class provides methods for a client to establish a network connection to a
server, and for both peers to operate the connection thereafter.
</doc>
<doc type="grammar">
connection = open-connection
*use-connection
close-connection
open-connection = C:protocol-header
S:START C:START-OK
*challenge
S:TUNE C:TUNE-OK
C:OPEN S:OPEN-OK | S:REDIRECT
challenge = S:SECURE C:SECURE-OK
use-connection = *channel
close-connection = C:CLOSE S:CLOSE-OK
/ S:CLOSE C:CLOSE-OK
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<!-- - Method: connection.start - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="start" synchronous="1" index="10" label="start connection negotiation">
<doc>
This method starts the connection negotiation process by telling the client the protocol
version that the server proposes, along with a list of security mechanisms which the client
can use for authentication.
</doc>
<rule name="protocol-name">
<doc>
If the server cannot support the protocol specified in the protocol header, it MUST close
the socket connection without sending any response method.
</doc>
<doc type="scenario">
The client sends a protocol header containing an invalid protocol name. The server must
respond by closing the connection.
</doc>
</rule>
<rule name="server-support">
<doc>
The server MUST provide a protocol version that is lower than or equal to that requested
by the client in the protocol header.
</doc>
<doc type="scenario">
The client requests a protocol version that is higher than any valid implementation, e.g.
9.0. The server must respond with a current protocol version, e.g. 1.0.
</doc>
</rule>
<rule name="client-support">
<doc>
If the client cannot handle the protocol version suggested by the server it MUST close the
socket connection.
</doc>
<doc type="scenario">
The server sends a protocol version that is lower than any valid implementation, e.g. 0.1.
The client must respond by closing the connection.
</doc>
</rule>
<chassis name="client" implement="MUST" />
<response name="start-ok" />
<field name="version-major" domain="octet" label="protocol major version">
<doc>
The protocol version, major component, as transmitted in the AMQP protocol header. This,
combined with the protocol minor component fully describe the protocol version, which is
written in the format major-minor. Hence, with major=1, minor=3, the protocol version
would be "1-3".
</doc>
</field>
<field name="version-minor" domain="octet" label="protocol minor version">
<doc>
The protocol version, minor component, as transmitted in the AMQP protocol header. This,
combined with the protocol major component fully describe the protocol version, which is
written in the format major-minor. Hence, with major=1, minor=3, the protocol version
would be "1-3".
</doc>
</field>
<field name="server-properties" domain="peer-properties" label="server properties">
<rule name="required-fields">
<doc>
The properties SHOULD contain at least these fields: "host", specifying the server host
name or address, "product", giving the name of the server product, "version", giving the
name of the server version, "platform", giving the name of the operating system,
"copyright", if appropriate, and "information", giving other general information.
</doc>
<doc type="scenario">
Client connects to server and inspects the server properties. It checks for the presence
of the required fields.
</doc>
</rule>
</field>
<field name="mechanisms" domain="longstr" label="available security mechanisms">
<doc>
A list of the security mechanisms that the server supports, delimited by spaces.
</doc>
<assert check="notnull" />
</field>
<field name="locales" domain="longstr" label="available message locales">
<doc>
A list of the message locales that the server supports, delimited by spaces. The locale
defines the language in which the server will send reply texts.
</doc>
<rule name="required-support">
<doc>
The server MUST support at least the en_US locale.
</doc>
<doc type="scenario">
Client connects to server and inspects the locales field. It checks for the presence of
the required locale(s).
</doc>
</rule>
<assert check="notnull" />
</field>
</method>
<!-- - Method: connection.start-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="start-ok" synchronous="1" index="11"
label="select security mechanism and locale">
<doc>
This method selects a SASL security mechanism.
</doc>
<chassis name="server" implement="MUST" />
<field name="client-properties" domain="peer-properties" label="client properties">
<rule name="required-fields">
<!-- This rule is not testable from the client side -->
<doc>
The properties SHOULD contain at least these fields: "product", giving the name of the
client product, "version", giving the name of the client version, "platform", giving the
name of the operating system, "copyright", if appropriate, and "information", giving
other general information.
</doc>
</rule>
</field>
<field name="mechanism" domain="shortstr" label="selected security mechanism">
<doc>
A single security mechanisms selected by the client, which must be one of those specified
by the server.
</doc>
<rule name="security">
<doc>
The client SHOULD authenticate using the highest-level security profile it can handle
from the list provided by the server.
</doc>
</rule>
<rule name="validity">
<doc>
If the mechanism field does not contain one of the security mechanisms proposed by the
server in the Start method, the server MUST close the connection without sending any
further data.
</doc>
<doc type="scenario">
Client connects to server and sends an invalid security mechanism. The server must
respond by closing the connection (a socket close, with no connection close
negotiation).
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="response" domain="longstr" label="security response data">
<doc>
A block of opaque data passed to the security mechanism. The contents of this data are
defined by the SASL security mechanism.
</doc>
<assert check="notnull" />
</field>
<field name="locale" domain="shortstr" label="selected message locale">
<doc>
A single message locale selected by the client, which must be one of those specified by
the server.
</doc>
<assert check="notnull" />
</field>
</method>
<!-- - Method: connection.secure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="secure" synchronous="1" index="20" label="security mechanism challenge">
<doc>
The SASL protocol works by exchanging challenges and responses until both peers have
received sufficient information to authenticate each other. This method challenges the
client to provide more information.
</doc>
<chassis name="client" implement="MUST" />
<response name="secure-ok" />
<field name="challenge" domain="longstr" label="security challenge data">
<doc>
Challenge information, a block of opaque binary data passed to the security mechanism.
</doc>
</field>
</method>
<!-- - Method: connection.secure-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="secure-ok" synchronous="1" index="21" label="security mechanism response">
<doc>
This method attempts to authenticate, passing a block of SASL data for the security
mechanism at the server side.
</doc>
<chassis name="server" implement="MUST" />
<field name="response" domain="longstr" label="security response data">
<doc>
A block of opaque data passed to the security mechanism. The contents of this data are
defined by the SASL security mechanism.
</doc>
<assert check="notnull" />
</field>
</method>
<!-- - Method: connection.tune - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="tune" synchronous="1" index="30" label="propose connection tuning parameters">
<doc>
This method proposes a set of connection configuration values to the client. The client can
accept and/or adjust these.
</doc>
<chassis name="client" implement="MUST" />
<response name="tune-ok" />
<field name="channel-max" domain="short" label="proposed maximum channels">
<doc>
The maximum total number of channels that the server allows per connection. Zero means
that the server does not impose a fixed limit, but the number of allowed channels may be
limited by available server resources.
</doc>
</field>
<field name="frame-max" domain="long" label="proposed maximum frame size">
<doc>
The largest frame size that the server proposes for the connection. The client can
negotiate a lower value. Zero means that the server does not impose any specific limit but
may reject very large frames if it cannot allocate resources for them.
</doc>
<rule name="minimum">
<doc>
Until the frame-max has been negotiated, both peers MUST accept frames of up to
frame-min-size octets large, and the minimum negotiated value for frame-max is also
frame-min-size.
</doc>
<doc type="scenario">
Client connects to server and sends a large properties field, creating a frame of
frame-min-size octets. The server must accept this frame.
</doc>
</rule>
</field>
<field name="heartbeat" domain="short" label="desired heartbeat delay">
<!-- TODO 0.82 - the heartbeat negotiation mechanism was changed during implementation
because the model documented here does not actually work properly. The best model we
found is that the server proposes a heartbeat value to the client; the client can reply
with zero, meaning 'do not use heartbeats (as documented here), or can propose its own
heartbeat value, which the server should then accept. This is different from the model
here which is disconnected - e.g. each side requests a heartbeat independently. Basically
a connection is heartbeated in both ways, or not at all, depending on whether both peers
support heartbeating or not, and the heartbeat value should itself be chosen by the client
so that remote links can get a higher value. Also, the actual heartbeat mechanism needs
documentation, and is as follows: so long as there is activity on a connection - in or out
- both peers assume the connection is active. When there is no activity, each peer must
send heartbeat frames. When no heartbeat frame is received after N cycles (where N is at
least 2), the connection can be considered to have died. /PH 2006/07/19
-->
<doc>
The delay, in seconds, of the connection heartbeat that the server wants. Zero means the
server does not want a heartbeat.
</doc>
</field>
</method>
<!-- - Method: connection.tune-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="tune-ok" synchronous="1" index="31"
label="negotiate connection tuning parameters">
<doc>
This method sends the client's connection tuning parameters to the server. Certain fields
are negotiated, others provide capability information.
</doc>
<chassis name="server" implement="MUST" />
<field name="channel-max" domain="short" label="negotiated maximum channels">
<doc>
The maximum total number of channels that the client will use per connection.
</doc>
<rule name="upper-limit">
<doc>
If the client specifies a channel max that is higher than the value provided by the
server, the server MUST close the connection without attempting a negotiated close. The
server may report the error in some fashion to assist implementors.
</doc>
</rule>
<assert check="notnull" />
<assert check="le" value="channel-max" />
</field>
<field name="frame-max" domain="long" label="negotiated maximum frame size">
<doc>
The largest frame size that the client and server will use for the connection. Zero means
that the client does not impose any specific limit but may reject very large frames if it
cannot allocate resources for them. Note that the frame-max limit applies principally to
content frames, where large contents can be broken into frames of arbitrary size.
</doc>
<rule name="minimum">
<doc>
Until the frame-max has been negotiated, both peers MUST accept frames of up to
frame-min-size octets large, and the minimum negotiated value for frame-max is also
frame-min-size.
</doc>
</rule>
<rule name="upper-limit">
<doc>
If the client specifies a frame max that is higher than the value provided by the
server, the server MUST close the connection without attempting a negotiated close. The
server may report the error in some fashion to assist implementors.
</doc>
</rule>
</field>
<field name="heartbeat" domain="short" label="desired heartbeat delay">
<doc>
The delay, in seconds, of the connection heartbeat that the client wants. Zero means the
client does not want a heartbeat.
</doc>
</field>
</method>
<!-- - Method: connection.open - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="open" synchronous="1" index="40" label="open connection to virtual host">
<doc>
This method opens a connection to a virtual host, which is a collection of resources, and
acts to separate multiple application domains within a server. The server may apply
arbitrary limits per virtual host, such as the number of each type of entity that may be
used, per connection and/or in total.
</doc>
<chassis name="server" implement="MUST" />
<response name="open-ok" />
<response name="redirect" />
<field name="virtual-host" domain="path" label="virtual host name">
<!-- TODO 0.82 - the entire vhost model needs review. This concept was prompted by the HTTP
vhost concept but does not fit very well into AMQP. Currently we use the vhost as a
"cluster identifier" which is inaccurate usage. /PH 2006/07/19
-->
<doc>
The name of the virtual host to work with.
</doc>
<rule name="separation">
<doc>
If the server supports multiple virtual hosts, it MUST enforce a full separation of
exchanges, queues, and all associated entities per virtual host. An application,
connected to a specific virtual host, MUST NOT be able to access resources of another
virtual host.
</doc>
</rule>
<rule name="security">
<doc>
The server SHOULD verify that the client has permission to access the specified virtual
host.
</doc>
</rule>
<assert check="regexp" value="^[a-zA-Z0-9/-_]+$" />
</field>
<field name="capabilities" domain="shortstr" label="required capabilities">
<doc>
The client can specify zero or more capability names, delimited by spaces. The server can
use this string to how to process the client's connection request.
</doc>
</field>
<field name="insist" domain="bit" label="insist on connecting to server">
<doc>
In a configuration with multiple collaborating servers, the server may respond to a
Connection.Open method with a Connection.Redirect. The insist option tells the server that
the client is insisting on a connection to the specified server.
</doc>
<rule name="behaviour">
<doc>
When the client uses the insist option, the server MUST NOT respond with a
Connection.Redirect method. If it cannot accept the client's connection request it
should respond by closing the connection with a suitable reply code.
</doc>
</rule>
</field>
</method>
<!-- - Method: connection.open-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="open-ok" synchronous="1" index="41" label="signal that connection is ready">
<doc>
This method signals to the client that the connection is ready for use.
</doc>
<chassis name="client" implement="MUST" />
<field name="known-hosts" domain="known-hosts" />
</method>
<!-- - Method: connection.redirect - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="redirect" synchronous="1" index="42" label="redirects client to other server">
<doc>
This method redirects the client to another server, based on the requested virtual host
and/or capabilities.
</doc>
<rule name="usage">
<doc>
When getting the Connection.Redirect method, the client SHOULD reconnect to the host
specified, and if that host is not present, to any of the hosts specified in the
known-hosts list.
</doc>
</rule>
<chassis name="client" implement="MUST" />
<field name="host" domain="shortstr" label="server to connect to">
<doc>
Specifies the server to connect to. This is an IP address or a DNS name, optionally
followed by a colon and a port number. If no port number is specified, the client should
use the default port number for the protocol.
</doc>
<assert check="notnull" />
</field>
<field name="known-hosts" domain="known-hosts" />
</method>
<!-- - Method: connection.close - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="close" synchronous="1" index="50" label="request a connection close">
<doc>
This method indicates that the sender wants to close the connection. This may be due to
internal conditions (e.g. a forced shut-down) or due to an error handling a specific method,
i.e. an exception. When a close is due to an exception, the sender provides the class and
method id of the method which caused the exception.
</doc>
<!-- TODO: The connection close mechanism needs to be reviewed from the ODF documentation and
better expressed as rules here. /PH 2006/07/20
-->
<rule name="stability">
<doc>
After sending this method any received method except the Close-OK method MUST be
discarded.
</doc>
</rule>
<chassis name="client" implement="MUST" />
<chassis name="server" implement="MUST" />
<response name="close-ok" />
<field name="reply-code" domain="reply-code" />
<field name="reply-text" domain="reply-text" />
<field name="class-id" domain="class-id" label="failing method class">
<doc>
When the close is provoked by a method exception, this is the class of the method.
</doc>
</field>
<field name="method-id" domain="method-id" label="failing method ID">
<doc>
When the close is provoked by a method exception, this is the ID of the method.
</doc>
</field>
</method>
<!-- - Method: connection.close-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="close-ok" synchronous="1" index="51" label="confirm a connection close">
<doc>
This method confirms a Connection.Close method and tells the recipient that it is safe to
release resources for the connection and close the socket.
</doc>
<rule name="reporting">
<doc>
A peer that detects a socket closure without having received a Close-Ok handshake method
SHOULD log the error.
</doc>
</rule>
<chassis name="client" implement="MUST" />
<chassis name="server" implement="MUST" />
</method>
</class>
<!-- == Class: session ======================================================================= -->
<class name="session" index="20" label="session control methods">
<doc>
The session class provides methods for a client to establish a session with a server and for
both peers to operate the session thereafter.
</doc>
<doc type="grammar">
session = open-session
*use-session
close-session
open-session = C:OPEN S:ATTACHED
/ C:RESUME S:ATTACHED
use-session = C:FLOW S:FLOW-OK
/ S:FLOW C:FLOW-OK
/ S:PING
/ C:PONG
/ C:PING
/ S:PONG
close-session = C:SUSPEND S:DETACHED
/ C:CLOSE S:CLOSED
/ S:CLOSED
/ S:CLOSE C:CLOSED
/ C:CLOSED
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<!-- - Method: session.open - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="open" synchronous="1" index="10" label="open a session for use">
<doc>
This method opens a session with the server.
When the responding peer creates the session, it MUST create a new, appropriately-unique
name for the session and return this to the creator with the rest of the session details.
Note that the timer controlling a session's automatic expiry, if any, counts down
immediately from the moment of its creation, unless simultaneously with that moment a
channel (or equivalent) is attached to the session. For this reason, it is recommended that
network protocol mappings create sessions simultaneously with the creation and attachment of
their channel-equivalents, since a zero lease time is perfectly valid and indicates that the
session should be destroyed as soon as it first finds itself inactive.
During the period that a channel (or equivalent) is attached to a session, the session has
no deletion timer. Every time a channel is detached from a session such that the session is
left without any attached network-level entities, the timer is created, set to its declared
value and started.
Note that if the peer decides that the requested detached-lifetime timeout is too long,
either because the replying peer does not support sessions with non-zero requested timeouts,
or because the requested timeout exceeds some peer-specific limitation, it may substitute an
acceptable value for the detached-lifetime parameter in its reply to the creation request.
An exception is not required.
</doc>
<rule name="expiration">
<doc>
Whether the detachment is explicit or implicit, as a result of application action or of
application error, the channel (or equivalent) is detached from its session and the
session timer MUST start counting down as defined in session.open.
</doc>
</rule>
<rule name="channel-busy">
<!-- TODO: Figure out how to make this error conditional to stateful network mappings with
channels.
-->
<doc>
The client MUST NOT send session.open on a channel that is already associated with a
session. A "channel busy" connection exception will occur if the channel down which the
open request was sent was already attached to a session.
</doc>
<doc type="scenario">
Client sends session.open twice down the same channel.
</doc>
</rule>
<!--
<throws name="out-of-resources"/>
-->
<chassis name="server" implement="MUST" />
<response name="attached" />
<field name="detached-lifetime" domain="detached-lifetime">
<doc>
The number of seconds the session's state is retained during periods when no channel (or
equivalent) is attached to the session.
</doc>
</field>
</method>
<!-- - Method: session.attached - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="attached" synchronous="1" index="11" label="signal that the session is ready">
<doc>
This method signals to the client that the session is ready for use.
Once a session.attached is received by the client, everything is in place for normal
transmission of frames. However, depending on the network protocol mapping in use, the
frame-id be undefined until certain control frames have been sent. Please see the specific
details for each protocol mapping.
If the attached session was freshly created, the session-id here will be a freshly-generated
UUID.
Note that the actual session detached-lifetime value, as decided by the peer, is returned
using this method. The value returned may not be the same as that requested in the
corresponding session creation request. In particular, a request for an unbounded
detached-lifetime of may be fulfilled by creation of a session with a bounded actual
lifetime parameter. The requesting peer SHOULD take the lifetime value returned as
authoritative for its own session-related record-keeping.
</doc>
<chassis name="client" implement="MUST" />
<field name="session-id" domain="session-id">
<doc>
The session identifier (a UUID) used to identify this session.
</doc>
</field>
<field name="detached-lifetime" domain="detached-lifetime">
<doc>
The number of seconds the session's state is retained during periods when no channel (or
equivalent) is attached to the session.
</doc>
</field>
</method>
<!-- - Method: session.flow - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="flow" synchronous="1" index="20" label="enable/disable flow from peer">
<doc>
This method asks the peer to pause or restart the flow of content data. This is a simple
flow-control mechanism that a peer can use to avoid overflowing its queues or otherwise
finding itself receiving more messages than it can process. Note that this method is not
intended for window control. The peer that receives a disable flow method should finish
sending the current content frame, if any, then pause.
</doc>
<rule name="initial-state">
<doc>
When a new session is opened, it is active (flow is active). Some applications assume that
sessions are inactive until started. To emulate this behaviour a client MAY open the
session, then pause it.
</doc>
</rule>
<rule name="bidirectional">
<doc>
When sending content frames, a peer SHOULD monitor the session for incoming methods and
respond to a Session.Flow as rapidly as possible.
</doc>
</rule>
<rule name="throttling">
<doc>
A peer MAY use the Session.Flow method to throttle incoming content data for internal
reasons, for example, when exchanging data over a slower connection.
</doc>
</rule>
<rule name="expected-behaviour">
<doc>
The peer that requests a Session.Flow method MAY disconnect and/or ban a peer that does
not respect the request. This is to prevent badly-behaved clients from overwhelming a
broker.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<response name="flow-ok" />
<field name="active" domain="bit" label="start/stop content frames">
<doc>
If true (1), the peer starts sending content frames. If false (0), the peer stops sending
content frames.
</doc>
</field>
</method>
<!-- - Method: session.flow-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="flow-ok" index="21" label="confirm a flow method">
<doc>
Confirms to the peer that a flow command was received and processed.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<field name="active" domain="bit" label="current flow setting">
<doc>
Confirms the setting of the processed flow method: true (1) means the peer will start
sending or continue to send content frames; false (0) means it will not.
</doc>
</field>
</method>
<!-- - Method: session.close - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="close" index="40" label="request a session close">
<doc>
Requests that the receiving peer destroy a session, implicitly detaching any attached
channels or channel-equivalents.
Note that the reply, session.closed, is also used for asynchronous exception notifications.
For normal closure, such as in response to a session.close request, reason code 200 ("ok")
is to be used.
</doc>
<chassis name="client" implement="MUST" />
<chassis name="server" implement="MUST" />
<!--
<response name="closed" />
-->
</method>
<!-- - Method: session.closed - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="closed" index="41" label="notify of a session close">
<doc>
Notifies the receiver that not only has the current channel been detached from its
underlying session, but that the session itself has been destroyed.
This method confirms a session.close method and tells the recipient that it is safe to
release resources for the channel.
Note also that for normal closure, reason code 200 ("ok") is to be used.
</doc>
<chassis name="client" implement="MUST" />
<chassis name="server" implement="MUST" />
<field name="reply-code" domain="reply-code">
<doc>
The numeric reply code.
</doc>
</field>
<field name="reply-text" domain="reply-text">
<doc>
The localised reply text.
</doc>
</field>
</method>
<!-- - Method: session.resume - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="resume" index="50" label="resume an interrupted session">
<doc>
Attaches to an already-existing session.
</doc>
<rule name="session-busy">
<doc>
A "session busy" exception is returned if the session exists, but is not in a condition
where it can accept the requested attachment. Peers receiving this exception may wish to
retain their session state and retry the session.resume operation after a delay.
</doc>
</rule>
<chassis name="server" implement="MAY" />
<response name="attached" />
<field name="session-id" domain="session-id">
<doc>
The session identifier (a UUID) used to identify this session.
</doc>
</field>
</method>
<!-- - Method: session.suspend - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="suspend" index="90" label="suspend the session">
<doc>
Indicates the sending peer wishes to detach from this session, but not necessarily to
destroy it.
</doc>
<!-- TODO: Ratify the inclusion of the chassis element in the XML. -->
<chassis name="server" implement="MAY" />
<response name="detached"/>
</method>
<!-- - Method: session.detached - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="detached" index="100" label="signal detachment of the session">
<doc>
Signal detachment from the session.
</doc>
<!-- TODO: Ratify the inclusion of the chassis element in the XML. -->
<chassis name="client" implement="MAY" />
</method>
<!-- - Method: session.ack - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<!-- TODO: This method does not appear in any grammar as yet... -->
<method name="ack" index="110" label="acknowledge receipt of frames">
<doc>
Signals receipt of all frames such that frame-id &lt;= cumulative-seen-mark, or frame-id is
in the set defined by seen-frame-set. This can be sent spontaneously, or in response to
either session.solicit-ack or session.high-water-mark.
Note that an encoded acknowledgement frame carried over the TCP network mapping (in the
absence of cross-protocol use of a session) will never have any entries in its
seen-frame-set.
<!-- TODO: See chapter (TBD here) for how frame ids are computed. -->
</doc>
<rule name="unique-encoding">
<doc>
In order to ensure a canonical wire representation, the value cumulative-seen-mark +
1 must not be covered by the seen-frame-set.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<field name="cumulative-seen-mark" domain="rfc1982-long" label="Low-water mark for seen ids">
<doc>
The low-water mark for seen frame-ids. All ids below this mark have been seen; above this
mark, there are gaps containing unseen ids (i.e. discontinuous). By definition, the first
frame-id above this mark (if it exists) is an unseen id.
</doc>
</field>
<field name="seen-frame-set" domain="rfc1982-long-set"
label="Set of discontinuous seen ids above cumulative-seen-mark">
<doc>
This set contains a sequence of discontinuous seen-frame-ids above the low-water mark
(i.e. above the first gap of unseen ids). In some transports where out-of-order delivery
is not possible (such as TCP), this set will always be empty.
</doc>
</field>
</method>
<!-- - Method: session.high-water-mark - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="high-water-mark" index="120" label="Inform the peer of most recent sent frame-id">
<doc>
Carries information about the highest (most recent) frame-id number that the sending peer
has sent through this session so far.
The receiver should issue a session.ack at the earliest possible opportunity.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<field name="last-sent-mark" domain="rfc1982-long" label="Frame-id of last sent frame">
<doc>
Highest frame-id sent by the sending peer through this session so far.
</doc>
</field>
</method>
<!-- - Method: session.solicit-ack - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="solicit-ack" index="130" label="request an ack">
<doc>
Requests a session.ack from the peer. The peer should issue one at the earliest possible
opportunity.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
</method>
</class>
<!-- == Class: access ======================================================================== -->
<!-- TODO 0.82 - this class must be implemented by two teams before we can consider it matured.
-->
<class name="access" index="30" label="work with access tickets">
<doc>
The protocol control access to server resources using access tickets. A client must explicitly
request access tickets before doing work. An access ticket grants a client the right to use a
specific set of resources - called a "realm" - in specific ways.
</doc>
<doc type="grammar">
access = C:REQUEST S:REQUEST-OK
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<!-- - Method: access.request - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="request" synchronous="1" index="10" label="request an access ticket">
<doc>
This method requests an access ticket for an access realm. The server responds by granting
the access ticket. If the client does not have access rights to the requested realm this
causes a connection exception. Access tickets are a per-session resource.
</doc>
<chassis name="server" implement="MUST" />
<response name="request-ok" />
<field name="realm" domain="shortstr" label="name of requested realm">
<doc>
Specifies the name of the realm to which the client is requesting access. The realm is a
configured server-side object that collects a set of resources (exchanges, queues, etc.).
If the session has already requested an access ticket onto this realm, the previous ticket
is destroyed and a new ticket is created with the requested access rights, if allowed.
</doc>
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST specify a realm that is known to the server. The server makes an
identical response for undefined realms as it does for realms that are defined but
inaccessible to this client.
</doc>
<doc type="scenario">
Client specifies an undefined realm.
</doc>
</rule>
</field>
<field name="exclusive" domain="bit" label="request exclusive access">
<doc>
Request exclusive access to the realm, meaning that this will be the only session that
uses the realm's resources.
</doc>
<rule name="in-use" on-failure="access-refused">
<doc>
The client MUST NOT request exclusive access to a realm that has active access tickets,
unless the same session already had the only access ticket onto that realm.
</doc>
<doc type="scenario">
Client opens two sessions and requests exclusive access to the same realm.
</doc>
</rule>
</field>
<field name="passive" domain="bit" label="request passive access">
<doc>
Request message passive access to the specified access realm. Passive access lets a client
get information about resources in the realm but not to make any changes to them.
</doc>
</field>
<field name="active" domain="bit" label="request active access">
<doc>
Request message active access to the specified access realm. Active access lets a client
get create and delete resources in the realm.
</doc>
</field>
<field name="write" domain="bit" label="request write access">
<doc>
Request write access to the specified access realm. Write access lets a client publish
messages to all exchanges in the realm.
</doc>
</field>
<field name="read" domain="bit" label="request read access">
<doc>
Request read access to the specified access realm. Read access lets a client consume
messages from queues in the realm.
</doc>
</field>
</method>
<!-- - Method: access.request-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="request-ok" synchronous="1" index="11" label="grant access to server resources">
<doc>
This method provides the client with an access ticket. The access ticket is valid within the
current session and for the lifespan of the session.
</doc>
<rule name="per-session" on-failure="not-allowed">
<doc>
The client MUST NOT use access tickets except within the same session as originally
granted.
</doc>
<doc type="scenario">
Client opens two sessions, requests a ticket on one session and then tries to use that
ticket in a second session.
</doc>
</rule>
<chassis name="client" implement="MUST" />
<field name="ticket" domain="access-ticket">
<doc>
A valid access ticket to be used for gaining access to the server.
</doc>
</field>
</method>
</class>
<!-- == Class: exchange ====================================================================== -->
<class name="exchange" index="40" label="work with exchanges">
<doc>
Exchanges match and distribute messages across queues. Exchanges can be configured in the
server or created at runtime.
</doc>
<doc type="grammar">
exchange = C:DECLARE
/ C:DELETE
</doc>
<rule name="required-types">
<doc>
The server MUST implement these standard exchange types: fanout, direct.
</doc>
<doc type="scenario">
Client attempts to declare an exchange with each of these standard types.
</doc>
</rule>
<rule name="recommended-types">
<doc>
The server SHOULD implement these standard exchange types: topic, headers.
</doc>
<doc type="scenario">
Client attempts to declare an exchange with each of these standard types.
</doc>
</rule>
<rule name="required-instances">
<doc>
The server MUST, in each virtual host, pre-declare an exchange instance for each standard
exchange type that it implements, where the name of the exchange instance, if defined, is
"amq." followed by the exchange type name.
The server MUST, in each virtual host, pre-declare at least two direct exchange instances:
one named "amq.direct", the other with no public name that serves as a default exchange for
publish methods (such as message.transfer).
</doc>
<doc type="scenario">
Client creates a temporary queue and attempts to bind to each required exchange instance
("amq.fanout", "amq.direct", "amq.topic", and "amq.headers" if those types are defined).
</doc>
</rule>
<rule name="default-exchange">
<doc>
The server MUST pre-declare a direct exchange with no public name to act as the default
exchange for content publish methods (such as message.transfer) and for default queue
bindings.
</doc>
<doc type="scenario">
Client checks that the default exchange is active by publishing a message with a suitable
routing key but without specifying the exchange name, then ensuring that the message arrives
in the queue correctly.
</doc>
</rule>
<rule name="default-access">
<doc>
The default exchange MUST NOT be accessible to the client except by specifying an empty
exchange name in a content publish method (such as message.transfer). That is, the server
must not let clients explicitly bind, unbind, delete, or make any other reference to this
exchange.
</doc>
</rule>
<rule name="extensions">
<doc>
The server MAY implement other exchange types as wanted.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<!-- - Method: exchange.declare - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="declare" synchronous="1" index="10"
label="verify exchange exists, create if needed">
<doc>
This method creates an exchange if it does not already exist, and if the exchange exists,
verifies that it is of the correct and expected class.
</doc>
<rule name="minimum">
<doc>
The server SHOULD support a minimum of 16 exchanges per virtual host and ideally, impose
no limit except as defined by available resources.
</doc>
<doc type="scenario">
The client creates as many exchanges as it can until the server reports an error; the
number of exchanges successfully created must be at least sixteen.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<doc>
When a client defines a new exchange, this belongs to the access realm of the ticket used.
All further work done with that exchange must be done with an access ticket for the same
realm.
</doc>
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "active" access to the realm in
which the exchange exists or will be created, or "passive" access if the if-exists flag
is set.
</doc>
<doc type="scenario">
Client creates access ticket with wrong access rights and attempts to use in this
method.
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="exchange" domain="exchange-name">
<rule name="reserved-names" on-failure="access-refused">
<doc>
Exchange names starting with "amq." are reserved for pre-declared and standardised
exchanges. The client MUST NOT attempt to create an exchange starting with "amq.".
</doc>
</rule>
<rule name="exchange-name-required" on-failure="not-allowed">
<doc>
The name of the exchange MUST NOT be a blank or empty string.
</doc>
</rule>
</field>
<field name="type" domain="shortstr" label="exchange type">
<doc>
Each exchange belongs to one of a set of exchange types implemented by the server. The
exchange types define the functionality of the exchange - i.e. how messages are routed
through it. It is not valid or meaningful to attempt to change the type of an existing
exchange.
</doc>
<rule name="typed" on-failure="not-allowed">
<doc>
Exchanges cannot be redeclared with different types. The client MUST not attempt to
redeclare an existing exchange with a different type than used in the original
Exchange.Declare method.
</doc>
</rule>
<rule name="support" on-failure="command-invalid">
<doc>
The client MUST NOT attempt to create an exchange with a type that the server does not
support.
</doc>
</rule>
<assert check="regexp" value="^[a-zA-Z0-9-_.:]+$" />
</field>
<field name="alternate-exchange" domain="exchange-name"
label= "exchange-name for unroutable messages">
<doc>
In the event that a message cannot be routed, this is the name of the exchange to which
the message will be sent.
</doc>
<rule name="empty-name">
<doc>
If alternate-exchange is not set (its name is an empty string), unroutable messages MUST
be dropped silently.
</doc>
</rule>
<rule name="pre-existing-exchange" on-failure="channel-error">
<doc>
If the alternate-exchange is not empty and if the exchange already exists with a
different alternate-exchange, then the declaration MUST result in a channel error.
</doc>
</rule>
<rule name="double-failure">
<doc>
A message which is being routed to a alternate exchange, MUST NOT be re-routed to a
secondary alternate exchange if it fails to route in the primary alternate exchange.
After such a failure, the message MUST be dropped. This prevents looping.
</doc>
</rule>
</field>
<field name="passive" domain="bit" label="do not create exchange">
<doc>
If set, the server will not create the exchange. The client can use this to check whether
an exchange exists without modifying the server state.
</doc>
<rule name="not-found" on-failure="not-found">
<doc>
If set, and the exchange does not already exist, the server MUST raise a channel
exception with reply code 404 (not found).
</doc>
</rule>
</field>
<field name="durable" domain="bit" label="request a durable exchange">
<doc>
If set when creating a new exchange, the exchange will be marked as durable. Durable
exchanges remain active when a server restarts. Non-durable exchanges (transient
exchanges) are purged if/when a server restarts.
</doc>
<rule name="support">
<doc>
The server MUST support both durable and transient exchanges.
</doc>
</rule>
<rule name="sticky">
<doc>
The server MUST ignore the durable field if the exchange already exists.
</doc>
</rule>
</field>
<field name="auto-delete" domain="bit" label="auto-delete when unused">
<doc>
If set, the exchange is deleted when all queues have finished using it.
</doc>
<rule name="sticky">
<doc>
The server MUST ignore the auto-delete field if the exchange already exists.
</doc>
</rule>
</field>
<field name="arguments" domain="table" label="arguments for declaration">
<doc>
A set of arguments for the declaration. The syntax and semantics of these arguments
depends on the server implementation. This field is ignored if passive is 1.
</doc>
</field>
</method>
<!-- - Method: exchange.delete - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="delete" synchronous="1" index="20" label="delete an exchange">
<doc>
This method deletes an exchange. When an exchange is deleted all queue bindings on the
exchange are cancelled.
</doc>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "active" access rights to the
exchange's access realm.
</doc>
<doc type="scenario">
Client creates access ticket with wrong access rights and attempts to use in this
method.
</doc>
</rule>
</field>
<field name="exchange" domain="exchange-name">
<rule name="exists" on-failure="not-found">
<doc>
The client MUST NOT attempt to delete an exchange that does not exist.
</doc>
</rule>
<rule name="exchange-name-required" on-failure="not-allowed">
<doc>
The name of the exchange MUST NOT be a blank or empty string.
</doc>
</rule>
<assert check="notnull" />
</field>
<!-- TODO 0.82 - discuss whether this option is useful or not. I don't have any real use case
for it. /PH 2006-07-23.
-->
<field name="if-unused" domain="bit" label="delete only if unused">
<doc>
If set, the server will only delete the exchange if it has no queue bindings. If the
exchange has queue bindings the server does not delete it but raises a channel exception
instead.
</doc>
</field>
</method>
<!-- - Method: exchange.query - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="query" synchronous="1" index="30" label="request information about an exchange">
<doc>
This method is used to request information on a particular exchange.
</doc>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "passive" access rights to the
exchange's access realm.
</doc>
</rule>
</field>
<field name="name" domain="shortstr" label="the exchange name">
<doc>
The name of the exchange for which information is requested. If not specified explicitly
the default exchange is implied.
</doc>
</field>
<result>
<struct size="long" type="31">
<doc>
This is sent in response to a query request and conveys information on a particular
exchange.
</doc>
<field name="type" domain="shortstr" label="indicate the exchange type">
<doc>
The type of the exchange. Will be empty if the exchange is not found.
</doc>
</field>
<field name="durable" domain="bit" label="indicate the durability">
<doc>
The durability of the exchange, i.e. if set the exchange is durable. Will not be set if
the exchange is not found.
</doc>
</field>
<field name="not-found" domain="bit" label="indicate an unknown exchange">
<doc>
If set, the exchange for which information was requested is not known.
</doc>
</field>
<field name="arguments" domain="table" label="other unspecified exchange properties">
<doc>
A set of properties of the exchange whose syntax and semantics depends on the server
implementation. Will be empty if the exchange is not found.
</doc>
</field>
</struct>
</result>
</method>
</class>
<!-- == Class: queue ========================================================================= -->
<class name="queue" index="50" label="work with queues">
<doc>
Queues store and forward messages. Queues can be configured in the server or created at
runtime. Queues must be attached to at least one exchange in order to receive messages from
publishers.
</doc>
<doc type="grammar">
queue = C:DECLARE
/ C:BIND
/ C:PURGE
/ C:DELETE
/ C:QUERY
/ C:UNBIND
</doc>
<rule name="any-content">
<doc>
A server MUST allow any content class to be sent to any queue, in any mix, and queue and
deliver these content classes independently. Note that all methods that fetch content off
queues are specific to a given content class.
</doc>
<doc type="scenario">
Client creates an exchange of each standard type and several queues that it binds to each
exchange. It must then successfully send each of the standard content types to each of the
available queues.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<!-- - Method: queue.declare - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="declare" synchronous="1" index="10" label="declare queue, create if needed">
<doc>
This method creates or checks a queue. When creating a new queue the client can specify
various properties that control the durability of the queue and its contents, and the level
of sharing for the queue.
</doc>
<rule name="default-binding">
<doc>
The server MUST create a default binding for a newly-created queue to the default
exchange, which is an exchange of type 'direct' and use the queue name as the routing key.
</doc>
<doc type="scenario">
Client creates a new queue, and then without explicitly binding it to an exchange,
attempts to send a message through the default exchange binding, i.e. publish a message to
the empty exchange, with the queue name as routing key.
</doc>
</rule>
<rule name="minimum-queues">
<doc>
The server SHOULD support a minimum of 256 queues per virtual host and ideally, impose no
limit except as defined by available resources.
</doc>
<doc type="scenario">
Client attempts to create as many queues as it can until the server reports an error. The
resulting count must at least be 256.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<doc>
When a client defines a new queue, this belongs to the access realm of the ticket used.
All further work done with that queue must be done with an access ticket for the same
realm.
</doc>
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "active" access to the realm in
which the queue exists or will be created.
</doc>
<doc type="scenario">
Client creates access ticket with wrong access rights and attempts to use in this
method.
</doc>
</rule>
</field>
<field name="queue" domain="queue-name">
<rule name="reserved-prefix" on-failure="not-allowed">
<doc>
Queue names starting with "amq." are reserved for pre-declared and standardised server
queues. A client MUST NOT attempt to declare a queue with a name that starts with "amq."
and the passive option set to zero.
</doc>
<doc type="scenario">
A client attempts to create a queue with a name starting with "amq." and with the
passive option set to zero.
</doc>
</rule>
</field>
<field name="alternate-exchange" domain="exchange-name"
label= "exchange-name for messages with exceptions">
<doc>
If a message is rejected by a queue, then it is sent to the alternate-exchange. A message
may be rejected by a queue for the following reasons:
1. The queue is deleted when it is not empty;
2. Immediate delivery of a message is requested, but there are no consumers connected to
the queue.
</doc>
<rule name="empty">
<doc>
If alternate-exchange is not set (its name is an empty string), rejected messages MUST
be dropped silently.
</doc>
</rule>
<rule name="pre-existing-exchange" on-failure="channel-error">
<doc>
If the alternate-exchange is not empty and if the queue already exists with a different
alternate-exchange, then the declaration MUST result in a channel error.
</doc>
</rule>
<rule name="delete-exchange" on-failure="channel-error">
<doc>
The alternate-exchange MUST NOT be deleted while a queue bound to it still exists. Such
an attempt MUST result in a channel exception.
</doc>
</rule>
</field>
<field name="passive" domain="bit" label="do not create queue">
<doc>
If set, the server will not create the queue. This field allows the client to assert the
presence of a queue without modifying the server state.
</doc>
<rule name="passive" on-failure="not-found">
<doc>
The client MAY ask the server to assert that a queue exists without creating the queue
if not. If the queue does not exist, the server treats this as a failure.
</doc>
<doc type="scenario">
Client declares an existing queue with the passive option and expects the command to
succeed. Client then attempts to declare a non-existent queue with the passive option,
and the server must close the channel with the correct reply-code.
</doc>
</rule>
</field>
<field name="durable" domain="bit" label="request a durable queue">
<doc>
If set when creating a new queue, the queue will be marked as durable. Durable queues
remain active when a server restarts. Non-durable queues (transient queues) are purged
if/when a server restarts. Note that durable queues do not necessarily hold persistent
messages, although it does not make sense to send persistent messages to a transient
queue.
</doc>
<rule name="persistence">
<doc>
The server MUST recreate the durable queue after a restart.
</doc>
<doc type="scenario">
Client creates a durable queue; server is then restarted. Client then attempts to send
message to the queue. The message should be successfully delivered.
</doc>
</rule>
<rule name="types">
<doc>
The server MUST support both durable and transient queues.
</doc>
<doc type="scenario">
A client creates two named queues, one durable and one transient.
</doc>
</rule>
<rule name="pre-existence">
<doc>
The server MUST ignore the durable field if the queue already exists.
</doc>
<doc type="scenario">
A client creates two named queues, one durable and one transient. The client then
attempts to declare the two queues using the same names again, but reversing the value
of the durable flag in each case. Verify that the queues still exist with the original
durable flag values.
<!-- TODO: but how? -->
</doc>
</rule>
</field>
<field name="exclusive" domain="bit" label="request an exclusive queue">
<doc>
Exclusive queues can only be used from one connection at a time. Once a connection
declares an exclusive queue, that queue cannot be used by any other connections until the
declaring connection closes.
</doc>
<rule name="types">
<doc>
The server MUST support both exclusive (private) and non-exclusive (shared) queues.
</doc>
<doc type="scenario">
A client creates two named queues, one exclusive and one non-exclusive.
</doc>
</rule>
<rule name="in-use" on-failure="resource-locked">
<doc>
If the server receives a declare, bind, consume or get request for a queue that has been
declared as exclusive by an existing client connection, it MUST raise a channel
exception.
</doc>
<doc type="scenario">
A client declares an exclusive named queue. A second client on a different connection
attempts to declare a queue of the same name.
</doc>
</rule>
</field>
<field name="auto-delete" domain="bit" label="auto-delete queue when unused">
<doc>
If this field is set and the exclusive field is also set, then the queue MUST be deleted
when the connection closes.
If this field is set and the exclusive field is not set the queue is deleted when all
the consumers have finished using it. Last consumer can be cancelled either explicitly
or because its channel is closed. If there was no consumer ever on the queue, it won't
be deleted.
</doc>
<rule name="pre-existence">
<doc>
The server MUST ignore the auto-delete field if the queue already exists.
</doc>
<doc type="scenario">
A client creates two named queues, one as auto-delete and one explicit-delete. The
client then attempts to declare the two queues using the same names again, but reversing
the value of the auto-delete field in each case. Verify that the queues still exist with
the original auto-delete flag values.
<!-- TODO: but how? -->
</doc>
</rule>
</field>
<field name="arguments" domain="table" label="arguments for declaration">
<doc>
A set of arguments for the declaration. The syntax and semantics of these arguments
depends on the server implementation. This field is ignored if passive is 1.
</doc>
</field>
</method>
<!-- - Method: queue.bind - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="bind" synchronous="1" index="20" label="bind queue to an exchange">
<doc>
This method binds a queue to an exchange. Until a queue is bound it will not receive any
messages. In a classic messaging model, store-and-forward queues are bound to a direct
exchange and subscription queues are bound to a topic exchange.
</doc>
<rule name="duplicates">
<doc>
A server MUST allow ignore duplicate bindings - that is, two or more bind methods for a
specific queue, with identical arguments - without treating these as an error.
</doc>
<doc type="scenario">
A client binds a named queue to an exchange. The client then repeats the bind (with
identical arguments).
</doc>
</rule>
<rule name="failure">
<!--
TODO: Find correct on-failure code. The on-failure code returned should depend on why the
bind failed. Assuming that failures owing to bad parameters are covered in the rules
relating to those parameters, the only remaining reason for a failure would be the lack of
server resorces or some internal error - such as too many queues open. Would these cases
qualify as "resource error" 506 or "internal error" 541?
-->
<doc>
If a bind fails, the server MUST raise a connection exception.
</doc>
</rule>
<rule name="transient-exchange" on-failure="not-allowed">
<doc>
The server MUST NOT allow a durable queue to bind to a transient exchange.
</doc>
<doc type="scenario">
A client creates a transient exchange. The client then declares a named durable queue and
then attempts to bind the transient exchange to the durable queue.
</doc>
</rule>
<rule name="durable-exchange">
<doc>
Bindings for durable queues are automatically durable and the server SHOULD restore such
bindings after a server restart.
</doc>
<doc type="scenario">
A server creates a named durable queue and binds it to a durable exchange. The server is
restarted. The client then attempts to use the queue/exchange combination.
</doc>
</rule>
<rule name="internal-exchange" on-failure="not-allowed">
<doc>
If the client attempts to bind to an exchange that was declared as internal, the server
MUST raise a connection exception with reply code 530 (not allowed).
</doc>
<doc type="scenario">
A client attempts to bind a named queue to an internal exchange.
</doc>
</rule>
<rule name="binding-count">
<doc>
The server SHOULD support at least 4 bindings per queue, and ideally, impose no limit
except as defined by available resources.
</doc>
<doc type="scenario">
A client creates a named queue and attempts to bind it to 4 different non-internal
exchanges.
</doc>
</rule>
<rule name="multiple-bindings">
<doc>
Where more than one binding exists between a particular exchange instance and a particular
queue instance any given message published to that exchange should be delivered to that
queue at most once, regardless of how many distinct bindings match.
</doc>
<doc type="scenario">
A client creates a named queue and binds it to the same topic exchange at least three
times using intersecting routing keys (for example, "animals.*", "animals.dogs.*",
"animal.dogs.chihuahua"). Verify that a message matching all the bindings (using previous
example, routing key = "animal.dogs.chihuahua") is delivered once only.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client provides a valid access ticket giving "active" access rights to the queue's
access realm.
</doc>
</rule>
</field>
<field name="queue" domain="queue-name">
<doc>
Specifies the name of the queue to bind. If the queue name is empty, refers to the current
queue for the session, which is the last declared queue.
</doc>
<rule name="empty-queue" on-failure="not-allowed">
<doc>
A client MUST NOT be allowed to bind a non-existent and unnamed queue (i.e. empty queue
name) to an exchange.
</doc>
<doc type="scenario">
A client attempts to bind with an unnamed (empty) queue name to an exchange.
</doc>
</rule>
<rule name="queue-existence" on-failure="not-found">
<doc>
A client MUST NOT be allowed to bind a non-existent queue (i.e. not previously declared)
to an exchange.
</doc>
<doc type="scenario">
A client attempts to bind an undeclared queue name to an exchange.
</doc>
</rule>
</field>
<field name="exchange" domain="exchange-name" label="name of the exchange to bind to">
<rule name="exchange-existence" on-failure="not-found">
<doc>
A client MUST NOT be allowed to bind a queue to a non-existent exchange.
</doc>
<doc type="scenario">
A client attempts to bind a named queue to a undeclared exchange.
</doc>
</rule>
<rule name="exchange-name-required" on-failure="not-allowed">
<doc>
The name of the exchange MUST NOT be a blank or empty string.
</doc>
</rule>
</field>
<field name="routing-key" domain="shortstr" label="message routing key">
<doc>
Specifies the routing key for the binding. The routing key is used for routing messages
depending on the exchange configuration. Not all exchanges use a routing key - refer to
the specific exchange documentation. If the queue name is empty, the server uses the last
queue declared on the session. If the routing key is also empty, the server uses this
queue name for the routing key as well. If the queue name is provided but the routing key
is empty, the server does the binding with that empty routing key. The meaning of empty
routing keys depends on the exchange implementation.
</doc>
<rule name="direct-exchange-key-matching">
<doc>
If a message queue binds to a direct exchange using routing key K and a publisher sends
the exchange a message with routing key R, then the message MUST be passed to the
message queue if K = R.
</doc>
</rule>
</field>
<field name="arguments" domain="table" label="arguments for binding">
<doc>
A set of arguments for the binding. The syntax and semantics of these arguments depends on
the exchange class.
</doc>
</field>
</method>
<!-- - Method: queue.unbind - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="unbind" synchronous="1" index="50" label="unbind a queue from an exchange">
<doc>
This method unbinds a queue from an exchange.
</doc>
<rule name="failure">
<doc>
If a unbind fails, the server MUST raise a connection exception.
<!-- TODO: define failure code -->
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client provides a valid access ticket giving "active" access rights to the queue's
access realm.
</doc>
</rule>
</field>
<field name="queue" domain="queue-name">
<doc>
Specifies the name of the queue to unbind.
</doc>
<rule name="non-existent-queue" on-failure="not-found">
<doc>
If the queue does not exist the server MUST raise a channel exception with reply code
404 (not found).
</doc>
</rule>
</field>
<field name="exchange" domain="exchange-name">
<doc>
The name of the exchange to unbind from.
</doc>
<rule name="non-existent-exchange" on-failure="not-found">
<doc>
If the exchange does not exist the server MUST raise a channel exception with reply code
404 (not found).
</doc>
</rule>
<rule name="exchange-name-required" on-failure="not-allowed">
<doc>
The name of the exchange MUST NOT be a blank or empty string.
</doc>
</rule>
</field>
<field name="routing-key" domain="shortstr" label="routing key of binding">
<doc>
Specifies the routing key of the binding to unbind.
</doc>
</field>
<field name="arguments" domain="table" label="arguments of binding">
<doc>
Specifies the arguments of the binding to unbind.
</doc>
</field>
</method>
<!-- - Method: queue.purge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="purge" synchronous="1" index="30" label="purge a queue">
<doc>
This method removes all messages from a queue. It does not cancel consumers. Purged messages
are deleted without any formal "undo" mechanism.
</doc>
<rule name="empty">
<doc>
A call to purge MUST result in an empty queue.
</doc>
</rule>
<rule name="tx-exception">
<doc>
On transacted sessions the server MUST not purge messages that have already been sent to a
client but not yet acknowledged.
</doc>
</rule>
<rule name="purge-recovery">
<doc>
The server MAY implement a purge queue or log that allows system administrators to recover
accidentally-purged messages. The server SHOULD NOT keep purged messages in the same
storage spaces as the live messages since the volumes of purged messages may get very
large.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "read" access rights to the queue's
access realm. Note that purging a queue is equivalent to reading all messages and
discarding them.
</doc>
</rule>
</field>
<field name="queue" domain="queue-name">
<doc>
Specifies the name of the queue to purge. If the queue name is empty, refers to the
current queue for the session, which is the last declared queue.
</doc>
<rule name="empty-name" on-failure="not-allowed">
<doc>
If the client did not previously declare a queue, and the queue name in this method is
empty, the server MUST raise a connection exception with reply code 530 (not allowed).
</doc>
</rule>
<rule name="queue-exists" on-failure="not-found">
<doc>
The queue MUST exist. Attempting to purge a non-existing queue MUST cause a channel
exception with reply code 404 (not found).
</doc>
</rule>
</field>
</method>
<!-- - Method: queue.delete - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="delete" synchronous="1" index="40" label="delete a queue">
<doc>
This method deletes a queue. When a queue is deleted any pending messages are sent to a
dead-letter queue if this is defined in the server configuration, and all consumers on the
queue are cancelled.
</doc>
<rule name="dead-letter-queue">
<doc>
The server SHOULD use a dead-letter queue to hold messages that were pending on a deleted
queue, and MAY provide facilities for a system administrator to move these messages back
to an active queue.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client provides a valid access ticket giving "active" access rights to the queue's
access realm.
</doc>
</rule>
</field>
<field name="queue" domain="queue-name">
<doc>
Specifies the name of the queue to delete. If the queue name is empty, refers to the
current queue for the session, which is the last declared queue.
</doc>
<rule name="empty-name" on-failure="not-allowed">
<doc>
If the client did not previously declare a queue, and the queue name in this method is
empty, the server MUST raise a connection exception with reply code 530 (not allowed).
</doc>
</rule>
<rule name="queue-exists" on-failure="not-found">
<doc>
The queue must exist. If the client attempts to delete a non-existing queue the server
MUST raise a channel exception with reply code 404 (not found).
</doc>
</rule>
</field>
<field name="if-unused" domain="bit" label="delete only if unused">
<doc>
If set, the server will only delete the queue if it has no consumers. If the queue has
consumers the server does does not delete it but raises a channel exception instead.
</doc>
<rule name="if-unused-flag">
<doc>
The server MUST respect the if-unused flag when deleting a queue.
</doc>
</rule>
</field>
<field name="if-empty" domain="bit" label="delete only if empty">
<doc>
If set, the server will only delete the queue if it has no messages.
</doc>
<rule name="not-empty" on-failure="precondition-failed">
<doc>
If the queue is not empty the server MUST raise a channel exception with reply code 406
(precondition failed).
</doc>
</rule>
</field>
</method>
<!-- - Method: queue.query - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="query" synchronous="1" index="60" label="request information about a queue">
<doc>
This method requests information about a queue.
</doc>
<chassis name="server" implement="MUST" />
<field name="queue" domain="queue-name" label="the queried queue">
<assert check="notnull" />
</field>
<result>
<struct size="long" type="61">
<doc>
This is sent in response to queue.query, and conveys the requested information about a
queue.
</doc>
<field name="queue" domain="queue-name">
<doc>
Reports the name of the queue.
</doc>
<assert check="notnull" />
</field>
<field name="alternate-exchange" domain="exchange-name" />
<field name="durable" domain="bit" />
<field name="exclusive" domain="bit" />
<field name="auto-delete" domain="bit" />
<field name="arguments" domain="table" />
<field name="message-count" domain="long" label="number of messages in queue">
<doc>
Reports the number of messages in the queue.
</doc>
</field>
<field name="consumer-count" domain="long" label="number of consumers">
<doc>
Reports the number of active consumers for the queue. Note that consumers can suspend
activity (Session.Flow) in which case they do not appear in this count.
</doc>
</field>
</struct>
</result>
</method>
</class>
<!-- == Class: basic ========================================================================= -->
<class name="basic" index="60" label="[DEPRECATED] work with basic content">
<doc>
[DEPRECATED: replaced by message class.] The Basic class provides methods that support an
industry-standard messaging model.
</doc>
<doc type="grammar">
basic = C:QOS
/ C:CONSUME S:CONSUME-OK
/ C:CANCEL
/ C:PUBLISH content
/ S:RETURN content
/ S:DELIVER content
/ C:GET ( S:GET-OK content / S:GET-EMPTY )
/ C:ACK
/ C:REJECT
</doc>
<rule name="persistence">
<doc>
The server SHOULD respect the persistent property of basic messages and SHOULD make a
best-effort to hold persistent basic messages on a reliable storage mechanism.
</doc>
<doc type="scenario">
Send a persistent message to queue, stop server, restart server and then verify whether
message is still present. Assumes that queues are durable. Persistence without durable
queues makes no sense.
</doc>
</rule>
<rule name="persistent-overflow">
<doc>
The server MUST NOT discard a persistent basic message in case of a queue overflow.
</doc>
<doc type="scenario">
Create a queue overflow situation with persistent messages and verify that messages do not
get lost (presumably the server will write them to disk).
</doc>
</rule>
<rule name="throttling">
<doc>
The server MAY use the Session.Flow method to slow or stop a basic message publisher when
necessary.
</doc>
<doc type="scenario">
Create a queue overflow situation with non-persistent messages and verify whether the server
responds with Session.Flow or not. Repeat with persistent messages.
</doc>
</rule>
<rule name="non-persistent-overflow">
<doc>
The server MAY overflow non-persistent basic messages to persistent storage.
</doc>
<!-- Test scenario: untestable -->
</rule>
<rule name="dead-letter-overflow">
<doc>
The server MAY discard or dead-letter non-persistent basic messages on a priority basis if
the queue size exceeds some configured limit.
</doc>
<!-- Test scenario: untestable -->
</rule>
<rule name="min-priority-levels">
<doc>
The server MUST implement at least 2 priority levels for basic messages, where priorities
0-4 and 5-9 are treated as two distinct levels.
</doc>
<doc type="scenario">
Send a number of priority 0 messages to a queue. Send one priority 9 message. Consume
messages from the queue and verify that the first message received was priority 9.
</doc>
</rule>
<rule name="max-priority-levels">
<doc>
The server MAY implement up to 10 priority levels.
</doc>
<doc type="scenario">
Send a number of messages with mixed priorities to a queue, so that all priority values from
0 to 9 are exercised. A good scenario would be ten messages in low-to-high priority. Consume
from queue and verify how many priority levels emerge.
</doc>
</rule>
<rule name="priority">
<doc>
The server MUST deliver messages of the same priority in order irrespective of their
individual persistence.
</doc>
<doc type="scenario">
Send a set of messages with the same priority but different persistence settings to a queue.
Consume and verify that messages arrive in same order as originally published.
</doc>
</rule>
<rule name="automatic-acknowledgement">
<doc>
The server MUST support automatic acknowledgements on Basic content, i.e. consumers with the
no-ack field set to FALSE.
</doc>
<doc type="scenario">
Create a queue and a consumer using automatic acknowledgements. Publish a set of messages to
the queue. Consume the messages and verify that all messages are received.
</doc>
</rule>
<rule name="explicit-acknowledgement">
<doc>
The server MUST support explicit acknowledgements on Basic content, i.e. consumers with the
no-ack field set to TRUE.
</doc>
<doc type="scenario">
Create a queue and a consumer using explicit acknowledgements. Publish a set of messages to
the queue. Consume the messages but acknowledge only half of them. Disconnect and reconnect,
and consume from the queue. Verify that the remaining messages are received.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MAY" />
<!-- These are the properties for a Basic content -->
<field name="content-type" domain="shortstr" label="MIME content type" />
<field name="content-encoding" domain="shortstr" label="MIME content encoding" />
<field name="headers" domain="table" label="message header field table" />
<field name="delivery-mode" domain="octet" label="non-persistent (1) or persistent (2)" />
<field name="priority" domain="octet" label="message priority, 0 to 9" />
<field name="correlation-id" domain="shortstr" label="application correlation identifier" />
<field name="reply-to" domain="shortstr" label="destination to reply to" />
<field name="expiration" domain="shortstr" label="message expiration specification" />
<field name="message-id" domain="shortstr" label="application message identifier" />
<field name="timestamp" domain="timestamp" label="message timestamp" />
<field name="type" domain="shortstr" label="message type name" />
<field name="user-id" domain="shortstr" label="creating user id" />
<field name="app-id" domain="shortstr" label="creating application id" />
<!-- - Method: basic.qos - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="qos" synchronous="1" index="10" label="[DEPRECATED] specify quality of service">
<doc>
[DEPRECATED: Basic replaced by message class.] This method requests a specific quality of
service. The QoS can be specified for the current session or for all sessions on the
connection. The particular properties and semantics of a qos method always depend on the
content class semantics. Though the qos method could in principle apply to both peers, it is
currently meaningful only for the server.
</doc>
<chassis name="server" implement="MUST" />
<field name="prefetch-size" domain="long" label="prefetch window in octets">
<doc>
The client can request that messages be sent in advance so that when the client finishes
processing a message, the following message is already held locally, rather than needing
to be sent within the session. Prefetching gives a performance improvement. This field
specifies the prefetch window size in octets. The server will send a message in advance if
it is equal to or smaller in size than the available prefetch size (and also falls into
other prefetch limits). May be set to zero, meaning "no specific limit", although other
prefetch limits may still apply. The prefetch-size is ignored if the no-ack option is set.
</doc>
<rule name="ignore">
<doc>
The server MUST ignore this setting when the client is not processing any messages -
i.e. the prefetch size does not limit the transfer of single messages to a client, only
the sending in advance of more messages while the client still has one or more
unacknowledged messages.
</doc>
<doc type="scenario">
Define a QoS prefetch-size limit and send a single message that exceeds that limit.
Verify that the message arrives correctly.
</doc>
</rule>
</field>
<field name="prefetch-count" domain="short" label="prefetch window in messages">
<doc>
Specifies a prefetch window in terms of whole messages. This field may be used in
combination with the prefetch-size field; a message will only be sent in advance if both
prefetch windows (and those at the session and connection level) allow it. The
prefetch-count is ignored if the no-ack option is set.
</doc>
<rule name="prefetch">
<doc>
The server may send less data in advance than allowed by the client's specified prefetch
windows but it MUST NOT send more.
</doc>
<doc type="scenario">
Define a QoS prefetch-size limit and a prefetch-count limit greater than one. Send
multiple messages that exceed the prefetch size. Verify that no more than one message
arrives at once.
</doc>
</rule>
</field>
<field name="global" domain="bit" label="apply to entire connection">
<doc>
By default the QoS settings apply to the current session only. If this field is set, they
are applied to the entire connection.
</doc>
</field>
</method>
<!-- - Method: basic.consume - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="consume" synchronous="1" index="20" label="[DEPRECATED] start a queue consumer">
<doc>
[DEPRECATED: Basic replaced by message class.] This method asks the server to start a
"consumer", which is a transient request for messages from a specific queue. Consumers last
as long as the session they were created on, or until the client cancels them.
</doc>
<rule name="min-consumers">
<doc>
The server SHOULD support at least 16 consumers per queue, and ideally, impose no limit
except as defined by available resources.
</doc>
<doc type="scenario">
Create a queue and create consumers on that queue until the server closes the connection.
Verify that the number of consumers created was at least sixteen and report the total
number.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<response name="consume-ok" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "read" access rights to the realm
for the queue from which the message will be consumed.
</doc>
<doc type="scenario">
Attempt to create a consumer with an invalid (non-zero) access ticket.
</doc>
</rule>
</field>
<field name="queue" domain="queue-name">
<doc>
Specifies the name of the queue to consume from. If the queue name is null, refers to the
current queue for the session, which is the last declared queue.
</doc>
<rule name="queue-exists-if-empty" on-failure="not-allowed">
<doc>
If the queue name is empty the client MUST have previously declared a queue using this
session.
</doc>
<doc type="scenario">
Attempt to create a consumer with an empty queue name and no previously declared queue
on the session.
</doc>
</rule>
</field>
<field name="consumer-tag" domain="consumer-tag">
<doc>
Specifies the identifier for the consumer. The consumer tag is local to a connection, so
two clients can use the same consumer tags. If this field is empty the server will
generate a unique tag.
</doc>
<rule name="not-existing-consumer" on-failure="not-allowed">
<doc>
The client MUST NOT specify a tag that refers to an existing consumer.
</doc>
<doc type="scenario">
Attempt to create two consumers with the same non-empty tag.
</doc>
</rule>
<rule name="session-bound" on-failure="not-allowed">
<doc>
The consumer tag is valid only within the session from which the consumer was created.
i.e. A client MUST NOT create a consumer in one session and then use it in another.
</doc>
<doc type="scenario">
Attempt to create a consumer in one session, then use in another session, in which
consumers have also been created (to test that the server uses unique consumer tags).
</doc>
</rule>
</field>
<field name="no-local" domain="no-local" />
<field name="no-ack" domain="no-ack" />
<field name="exclusive" domain="bit" label="request exclusive access">
<doc>
Request exclusive consumer access, meaning only this consumer can access the queue.
</doc>
<rule name="in-use" on-failure="access-refused">
<doc>
The client MUST NOT gain exclusive access to a queue that already has active consumers.
</doc>
<doc type="scenario">
Open two connections to a server, and in one connection create a shared (non-exclusive)
queue and then consume from the queue. In the second connection attempt to consume from
the same queue using the exclusive option.
</doc>
</rule>
</field>
<field name="nowait" domain="bit" label="do not send a reply method">
<doc>
If set, the server will not respond to the method. The client should not wait for a reply
method. If the server could not complete the method it will raise a channel or connection
exception.
</doc>
</field>
<field name="arguments" domain="table" label="arguments for consuming">
<doc>
A set of arguments for the consume. The syntax and semantics of these arguments depends on
the providers implementation.
</doc>
</field>
</method>
<!-- - Method: basic.consume-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="consume-ok" synchronous="1" index="21"
label="[DEPRECATED] confirm a new consumer">
<doc>
[DEPRECATED: Basic replaced by message class.] The server provides the client with a
consumer tag, which is used by the client for methods called on the consumer at a later
stage.
</doc>
<chassis name="client" implement="MUST" />
<field name="consumer-tag" domain="consumer-tag">
<doc>
Holds the consumer tag specified by the client or provided by the server.
</doc>
</field>
</method>
<!-- - Method: basic.cancel - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="cancel" synchronous="1" index="30" label="[DEPRECATED] end a queue consumer">
<doc>
[DEPRECATED: Basic replaced by message class.] This method cancels a consumer. This does not
affect already delivered messages, but it does mean the server will not send any more
messages for that consumer. The client may receive an arbitrary number of messages in
between sending the cancel method and receiving notification of the completion of the cancel command.
</doc>
<rule name="non-existent">
<doc>
If the queue does not exist the server MUST ignore the cancel method, so long as the
consumer tag is valid for that session.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="consumer-tag" domain="consumer-tag" />
</method>
<!-- - Method: basic.publish - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="publish" content="1" index="40" label="[DEPRECATED] publish a message">
<doc>
[DEPRECATED: Basic replaced by message class.] This method publishes a message to a specific
exchange. The message will be routed to queues as defined by the exchange configuration and
distributed to any active consumers when the transaction, if any, is committed.
</doc>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "passive" access rights to the
realm for the exchange and "write" access rights to the realm for the queue to which the
message will be published.
</doc>
</rule>
</field>
<field name="exchange" domain="exchange-name">
<doc>
Specifies the name of the exchange to publish to. The exchange name can be empty, meaning
the default exchange. If the exchange name is specified, and that exchange does not exist,
the server will raise a channel exception.
</doc>
<rule name="default">
<doc>
The server MUST accept a blank exchange name to mean the default exchange.
</doc>
</rule>
<rule name="internal" on-failure="access-refused">
<doc>
If the exchange was declared as an internal exchange, the server MUST raise a channel
exception with a reply code 403 (access refused).
</doc>
</rule>
<rule name="refusal" on-failure="not-implemented">
<doc>
The exchange MAY refuse basic content in which case it MUST raise a channel exception
with reply code 540 (not implemented).
</doc>
</rule>
</field>
<field name="routing-key" domain="shortstr" label="Message routing key">
<doc>
Specifies the routing key for the message. The routing key is used for routing messages
depending on the exchange configuration.
</doc>
</field>
<field name="reject-unroutable" domain="bit" label="reject message if unroutable flag">
<doc>
If the reject-unroutable flag is set, then at the time of publishing the broker
determines if the message will be routed to any queues. If it will not be routed to any
queue then the broker responds with a basic.reject.
</doc>
</field>
<field name="immediate" domain="bit" label="Request immediate delivery">
<doc>
If this flag is set, and the resulting message is delivered to a queue with no
consumers, the message will not be queued but will instead be routed to the
alternate-exchange for that queue. If no such exchange is defined the message will be
silently dropped.
</doc>
<rule name="implementation">
<doc>
The server SHOULD implement the immediate flag.
</doc>
</rule>
</field>
</method>
<!-- - Method: basic.deliver - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="deliver" content="1" index="60"
label="[DEPRECATED] notify the client of a consumer message">
<doc>
[DEPRECATED: Basic replaced by message class.] This method delivers a message to the client,
via a consumer. In the asynchronous message delivery model, the client starts a consumer
using the Consume method, then the server responds with Deliver methods as and when messages
arrive for that consumer.
</doc>
<rule name="redelivery-tracking">
<doc>
The server SHOULD track the number of times a message has been delivered to clients and
when a message is redelivered a certain number of times - e.g. 5 times - without being
acknowledged, the server SHOULD consider the message to be unprocessable (possibly causing
client applications to abort), and move the message to a dead letter queue.
</doc>
</rule>
<chassis name="client" implement="MUST" />
<field name="consumer-tag" domain="consumer-tag" />
<field name="delivery-tag" domain="delivery-tag" />
<field name="redelivered" domain="redelivered" />
<field name="exchange" domain="exchange-name">
<doc>
Specifies the name of the exchange that the message was originally published to.
</doc>
</field>
<field name="routing-key" domain="shortstr" label="Message routing key">
<doc>
Specifies the routing key name specified when the message was published.
</doc>
</field>
</method>
<!-- - Method: basic.get - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="get" synchronous="1" index="70" label="[DEPRECATED] direct access to a queue">
<doc>
[DEPRECATED: Basic replaced by message class.] This method provides a direct access to the
messages in a queue using a synchronous dialogue that is designed for specific types of
application where synchronous functionality is more important than performance.
</doc>
<chassis name="server" implement="MUST" />
<response name="get-ok" />
<response name="get-empty" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "read" access rights to the realm
for the queue from which the message will be obtained.
</doc>
</rule>
</field>
<field name="queue" domain="queue-name">
<doc>
Specifies the name of the queue to consume from. If the queue name is null, refers to the
current queue for the session, which is the last declared queue.
</doc>
<rule name="queue-exists-if-empty">
<doc>
If the client did not previously declare a queue, and the queue name in this method is
empty, the server MUST raise a connection exception with reply code 530 (not allowed).
</doc>
</rule>
</field>
<field name="no-ack" domain="no-ack" />
</method>
<!-- - Method: basic.get-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="get-ok" synchronous="1" content="1" index="71"
label="[DEPRECATED] provide client with a message">
<doc>
[DEPRECATED: Basic replaced by message class.] This method delivers a message to the client
following a get method. A message delivered by 'get-ok' must be acknowledged unless the
no-ack option was set in the get method.
</doc>
<chassis name="client" implement="MAY" />
<field name="delivery-tag" domain="delivery-tag" />
<field name="redelivered" domain="redelivered" />
<field name="exchange" domain="exchange-name">
<doc>
Specifies the name of the exchange that the message was originally published to. If empty,
the message was published to the default exchange.
</doc>
</field>
<field name="routing-key" domain="shortstr" label="Message routing key">
<doc>
Specifies the routing key name specified when the message was published.
</doc>
</field>
<field name="message-count" domain="long" label="number of messages pending">
<doc>
This field reports the number of messages pending on the queue, excluding the message
being delivered. Note that this figure is indicative, not reliable, and can change
arbitrarily as messages are added to the queue and removed by other clients.
</doc>
</field>
</method>
<!-- - Method: basic.get-empty - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="get-empty" synchronous="1" index="72"
label="[DEPRECATED] indicate no messages available">
<doc>
[DEPRECATED: Basic replaced by message class.] This method tells the client that the queue
has no messages available for the client.
</doc>
<chassis name="client" implement="MAY" />
<!-- This field is deprecated pending review -->
<field name="cluster-id" domain="shortstr" label="Cluster id">
<doc>
For use by cluster applications, should not be used by client applications.
</doc>
</field>
</method>
<!-- - Method: basic.ack - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="ack" index="80" label="[DEPRECATED] acknowledge one or more messages">
<doc>
[DEPRECATED: Basic replaced by message class.] This method acknowledges one or more messages
delivered via the Deliver or Get-Ok methods. The client can ask to confirm a single message
or a set of messages up to and including a specific message.
</doc>
<chassis name="server" implement="MUST" />
<field name="delivery-tag" domain="delivery-tag" />
<field name="multiple" domain="bit" label="acknowledge multiple messages">
<doc>
If set to 1, the delivery tag is treated as "up to and including", so that the client can
acknowledge multiple messages with a single method. If set to zero, the delivery tag
refers to a single message. If the multiple field is 1, and the delivery tag is zero,
tells the server to acknowledge all outstanding messages.
</doc>
<rule name="validation">
<doc>
The server MUST validate that a non-zero delivery-tag refers to a delivered message, and
raise a channel exception if this is not the case.
</doc>
</rule>
</field>
</method>
<!-- - Method: basic.reject - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="reject" index="90" label="[DEPRECATED] reject an incoming message">
<doc>
[DEPRECATED: Basic replaced by message class.] This method allows a client to reject a
message. It can be used to interrupt and cancel large incoming messages, or return
untreatable messages to their original queue.
</doc>
<rule name="concurrent-processing">
<doc>
The server SHOULD be capable of accepting and processing the Reject method while sending
message content with a Deliver or Get-Ok method. i.e. The server should read and process
incoming methods while sending output frames. To cancel a partially-send content, the
server sends a content body frame of size 1 (i.e. with no data except the frame-end
octet).
</doc>
</rule>
<rule name="server-interpretation">
<doc>
The server SHOULD interpret this method as meaning that the client is unable to process
the message at this time.
</doc>
</rule>
<rule name="not-selection">
<doc>
A client MUST NOT use this method as a means of selecting messages to process. A rejected
message MAY be discarded or dead-lettered, not necessarily passed to another client.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="delivery-tag" domain="delivery-tag" />
<field name="requeue" domain="bit" label="requeue the message">
<doc>
If this field is zero, the message will be discarded. If this bit is 1, the server will
attempt to requeue the message.
</doc>
<rule name="requeue-strategy">
<doc>
The server MUST NOT deliver the message to the same client within the context of the
current session. The recommended strategy is to attempt to deliver the message to an
alternative consumer, and if that is not possible, to move the message to a dead-letter
queue. The server MAY use more sophisticated tracking to hold the message on the queue
and redeliver it to the same client at a later stage.
</doc>
</rule>
</field>
</method>
<!-- - Method: basic.recover - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="recover" index="100" label="[DEPRECATED] redeliver unacknowledged messages">
<doc>
[DEPRECATED: Basic replaced by message class.] This method asks the broker to redeliver all
unacknowledged messages on a specified session. Zero or more messages may be redelivered.
This method is only allowed on non-transacted sessions.
</doc>
<rule name="redelivered-flag">
<doc>
The server MUST set the redelivered flag on all messages that are resent.
</doc>
</rule>
<rule name="non-transacted-session">
<doc>
The server MUST raise a channel exception if this is called on a transacted session.
<!-- TODO: define failure code -->
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="requeue" domain="bit" label="requeue the message">
<doc>
If this field is zero, the message will be redelivered to the original recipient. If this
bit is 1, the server will attempt to requeue the message, potentially then delivering it
to an alternative subscriber.
</doc>
</field>
</method>
</class>
<!-- == Class: file ========================================================================== -->
<class name="file" index="70" label="work with file content">
<doc>
The file class provides methods that support reliable file transfer. File messages have a
specific set of properties that are required for interoperability with file transfer
applications. File messages and acknowledgements are subject to session transactions. Note
that the file class does not provide message browsing methods; these are not compatible with
the staging model. Applications that need browsable file transfer should use Basic content and
the Basic class.
</doc>
<doc type="grammar">
file = C:QOS S:QOS-OK
/ C:CONSUME S:CONSUME-OK
/ C:CANCEL
/ C:OPEN S:OPEN-OK C:STAGE content
/ S:OPEN C:OPEN-OK S:STAGE content
/ C:PUBLISH
/ S:DELIVER
/ S:RETURN
/ C:ACK
/ C:REJECT
</doc>
<rule name="reliable-storage">
<doc>
The server MUST make a best-effort to hold file messages on a reliable storage mechanism.
</doc>
</rule>
<!-- TODO Rule implement attr inverse? -->
<rule name="no-discard">
<doc>
The server MUST NOT discard a file message in case of a queue overflow. The server MUST use
the Session.Flow method to slow or stop a file message publisher when necessary.
</doc>
</rule>
<rule name="priority-levels">
<doc>
The server MUST implement at least 2 priority levels for file messages, where priorities 0-4
and 5-9 are treated as two distinct levels. The server MAY implement up to 10 priority
levels.
</doc>
</rule>
<rule name="acknowledgement-support">
<doc>
The server MUST support both automatic and explicit acknowledgements on file content.
</doc>
</rule>
<chassis name="server" implement="MAY" />
<chassis name="client" implement="MAY" />
<!-- These are the properties for a File content -->
<field name="content-type" domain="shortstr" label="MIME content type" />
<field name="content-encoding" domain="shortstr" label="MIME content encoding" />
<field name="headers" domain="table" label="message header field table" />
<field name="priority" domain="octet" label="message priority, 0 to 9" />
<field name="reply-to" domain="shortstr" label="destination to reply to" />
<field name="message-id" domain="shortstr" label="application message identifier" />
<field name="filename" domain="shortstr" label="message filename" />
<field name="timestamp" domain="timestamp" label="message timestamp" />
<!-- This field is deprecated pending review -->
<field name="cluster-id" domain="shortstr" label="intra-cluster routing identifier" />
<!-- - Method: file.qos - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="qos" synchronous="1" index="10" label="specify quality of service">
<doc>
This method requests a specific quality of service. The QoS can be specified for the current
session or for all sessions on the connection. The particular properties and semantics of a
qos method always depend on the content class semantics. Though the qos method could in
principle apply to both peers, it is currently meaningful only for the server.
</doc>
<chassis name="server" implement="MUST" />
<response name="qos-ok" />
<field name="prefetch-size" domain="long" label="prefetch window in octets">
<doc>
The client can request that messages be sent in advance so that when the client finishes
processing a message, the following message is already held locally, rather than needing
to be sent within the session. Prefetching gives a performance improvement. This field
specifies the prefetch window size in octets. May be set to zero, meaning "no specific
limit". Note that other prefetch limits may still apply. The prefetch-size is ignored if
the no-ack option is set.
</doc>
</field>
<field name="prefetch-count" domain="short" label="prefetch window in messages">
<doc>
Specifies a prefetch window in terms of whole messages. This is compatible with some file
API implementations. This field may be used in combination with the prefetch-size field; a
message will only be sent in advance if both prefetch windows (and those at the session
and connection level) allow it. The prefetch-count is ignored if the no-ack option is set.
</doc>
<rule name="prefetch-discretion">
<doc>
The server MAY send less data in advance than allowed by the client's specified prefetch
windows but it MUST NOT send more.
</doc>
</rule>
</field>
<field name="global" domain="bit" label="apply to entire connection">
<doc>
By default the QoS settings apply to the current session only. If this field is set, they
are applied to the entire connection.
</doc>
</field>
</method>
<!-- - Method: file.qos-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="qos-ok" synchronous="1" index="11" label="confirm the requested qos">
<doc>
This method tells the client that the requested QoS levels could be handled by the server.
The requested QoS applies to all active consumers until a new QoS is defined.
</doc>
<chassis name="client" implement="MUST" />
</method>
<!-- - Method: file.consume - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="consume" synchronous="1" index="20" label="start a queue consumer">
<doc>
This method asks the server to start a "consumer", which is a transient request for messages
from a specific queue. Consumers last as long as the session they were created on, or until
the client cancels them.
</doc>
<rule name="min-consumers">
<doc>
The server SHOULD support at least 16 consumers per queue, unless the queue was declared
as private, and ideally, impose no limit except as defined by available resources.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<response name="consume-ok" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "read" access rights to the realm
for the queue from which the message will be consumed.
</doc>
</rule>
</field>
<field name="queue" domain="queue-name">
<doc>
Specifies the name of the queue to consume from. If the queue name is null, refers to the
current queue for the session, which is the last declared queue.
</doc>
<rule name="queue-exists-if-empty" on-failure="not-allowed">
<doc>
If the client did not previously declare a queue, and the queue name in this method is
empty, the server MUST raise a connection exception with reply code 530 (not allowed).
</doc>
</rule>
</field>
<field name="consumer-tag" domain="consumer-tag">
<doc>
Specifies the identifier for the consumer. The consumer tag is local to a connection, so
two clients can use the same consumer tags. If this field is empty the server will
generate a unique tag.
</doc>
<rule name="not-existing-consumer" on-failure="not-allowed">
<doc>
The tag MUST NOT refer to an existing consumer. If the client attempts to create two
consumers with the same non-empty tag the server MUST raise a connection exception with
reply code 530 (not allowed).
</doc>
</rule>
</field>
<field name="no-local" domain="no-local" />
<field name="no-ack" domain="no-ack" />
<field name="exclusive" domain="bit" label="request exclusive access">
<doc>
Request exclusive consumer access, meaning only this consumer can access the queue.
</doc>
<rule name="in-use" on-failure="resource-locked">
<doc>
If the server cannot grant exclusive access to the queue when asked, - because there are
other consumers active - it MUST raise a channel exception with return code 405
(resource locked).
</doc>
</rule>
</field>
<field name="nowait" domain="bit" label="do not send a reply method">
<doc>
If set, the server will not respond to the method. The client should not wait for a reply
method. If the server could not complete the method it will raise a channel or connection
exception.
</doc>
</field>
<field name="filter" domain="table" label="arguments for consuming">
<doc>
A set of filters for the consume. The syntax and semantics of these filters depends on the
providers implementation.
</doc>
</field>
</method>
<method name="consume-ok" synchronous="1" index="21" label="confirm a new consumer">
<doc>
This method provides the client with a consumer tag which it MUST use in methods that work
with the consumer.
</doc>
<chassis name="client" implement="MUST" />
<field name="consumer-tag" domain="consumer-tag">
<doc>
Holds the consumer tag specified by the client or provided by the server.
</doc>
</field>
</method>
<!-- - Method: file.cancel - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="cancel" synchronous="1" index="30" label="end a queue consumer">
<doc>
This method cancels a consumer. This does not affect already delivered messages, but it does
mean the server will not send any more messages for that consumer.
</doc>
<chassis name="server" implement="MUST" />
<field name="consumer-tag" domain="consumer-tag" />
</method>
<!-- - Method: file.open - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="open" synchronous="1" index="40" label="request to start staging">
<doc>
This method requests permission to start staging a message. Staging means sending the
message into a temporary area at the recipient end and then delivering the message by
referring to this temporary area. Staging is how the protocol handles partial file transfers
- if a message is partially staged and the connection breaks, the next time the sender
starts to stage it, it can restart from where it left off.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<response name="open-ok" />
<field name="identifier" domain="shortstr" label="staging identifier">
<doc>
This is the staging identifier. This is an arbitrary string chosen by the sender. For
staging to work correctly the sender must use the same staging identifier when staging the
same message a second time after recovery from a failure. A good choice for the staging
identifier would be the SHA1 hash of the message properties data (including the original
filename, revised time, etc.).
</doc>
</field>
<field name="content-size" domain="longlong" label="message content size">
<doc>
The size of the content in octets. The recipient may use this information to allocate or
check available space in advance, to avoid "disk full" errors during staging of very large
messages.
</doc>
<rule name="content-size">
<doc>
The sender MUST accurately fill the content-size field. Zero-length content is
permitted.
</doc>
</rule>
</field>
</method>
<!-- - Method: file.open-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="open-ok" synchronous="1" index="41" label="confirm staging ready">
<doc>
This method confirms that the recipient is ready to accept staged data. If the message was
already partially-staged at a previous time the recipient will report the number of octets
already staged.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<response name="stage" />
<field name="staged-size" domain="longlong" label="already staged amount">
<doc>
The amount of previously-staged content in octets. For a new message this will be zero.
</doc>
<rule name="behaviour">
<doc>
The sender MUST start sending data from this octet offset in the message, counting from
zero.
<!-- TODO: review this text, it seems ambiguous or confusing... -->
</doc>
</rule>
<rule name="staging">
<doc>
The recipient MAY decide how long to hold partially-staged content and MAY implement
staging by always discarding partially-staged content. However if it uses the file
content type it MUST support the staging methods.
</doc>
</rule>
</field>
</method>
<!-- - Method: file.stage - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="stage" content="1" index="50" label="stage message content">
<doc>
This method stages the message, sending the message content to the recipient from the octet
offset specified in the Open-Ok method.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
</method>
<!-- - Method: file.publish - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="publish" index="60" label="publish a message">
<doc>
This method publishes a staged file message to a specific exchange. The file message will be
routed to queues as defined by the exchange configuration and distributed to any active
consumers when the transaction, if any, is committed.
</doc>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "passive" access rights to the
realm for the exchange and "write" access rights to the realm for the queue to which the
message will be published.
</doc>
</rule>
</field>
<field name="exchange" domain="exchange-name">
<doc>
Specifies the name of the exchange to publish to. The exchange name can be empty, meaning
the default exchange. If the exchange name is specified, and that exchange does not exist,
the server will raise a channel exception.
</doc>
<rule name="default">
<doc>
The server MUST accept a blank exchange name to mean the default exchange.
</doc>
</rule>
<rule name="internal" on-failure="access-refused">
<doc>
If the exchange was declared as an internal exchange, the server MUST respond with a
reply code 403 (access refused) and raise a channel exception.
</doc>
</rule>
<rule name="refusal" on-failure="not-implemented">
<doc>
The exchange MAY refuse file content in which case it MUST respond with a reply code 540
(not implemented) and raise a channel exception.
</doc>
</rule>
</field>
<field name="routing-key" domain="shortstr" label="Message routing key">
<doc>
Specifies the routing key for the message. The routing key is used for routing messages
depending on the exchange configuration.
</doc>
</field>
<field name="mandatory" domain="bit" label="indicate mandatory routing">
<doc>
This flag tells the server how to react if the message cannot be routed to a queue. If
this flag is set, the server will return an unroutable message with a Return method. If
this flag is zero, the server silently drops the message.
</doc>
<rule name="implementation">
<doc>
The server SHOULD implement the mandatory flag.
</doc>
</rule>
</field>
<field name="immediate" domain="bit" label="request immediate delivery">
<doc>
This flag tells the server how to react if the message cannot be routed to a queue
consumer immediately. If this flag is set, the server will return an undeliverable message
with a Return method. If this flag is zero, the server will queue the message, but with no
guarantee that it will ever be consumed.
</doc>
<rule name="implementation">
<doc>
The server SHOULD implement the immediate flag.
</doc>
</rule>
</field>
<field name="identifier" domain="shortstr" label="staging identifier">
<doc>
This is the staging identifier of the message to publish. The message must have been
staged. Note that a client can send the Publish method asynchronously without waiting for
staging to finish.
</doc>
</field>
</method>
<!-- - Method: file.return - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="return" content="1" index="70" label="return a failed message">
<doc>
This method returns an undeliverable message that was published with the "immediate" flag
set, or an unroutable message published with the "mandatory" flag set. The reply code and
text provide information about the reason that the message was undeliverable.
</doc>
<chassis name="client" implement="MUST" />
<field name="reply-code" domain="reply-code" />
<field name="reply-text" domain="reply-text" />
<field name="exchange" domain="exchange-name">
<doc>
Specifies the name of the exchange that the message was originally published to.
</doc>
</field>
<field name="routing-key" domain="shortstr" label="Message routing key">
<doc>
Specifies the routing key name specified when the message was published.
</doc>
</field>
</method>
<!-- - Method: file.deliver - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="deliver" index="80" label="notify the client of a consumer message">
<doc>
This method delivers a staged file message to the client, via a consumer. In the
asynchronous message delivery model, the client starts a consumer using the Consume method,
then the server responds with Deliver methods as and when messages arrive for that consumer.
</doc>
<rule name="redelivery-tracking">
<doc>
The server SHOULD track the number of times a message has been delivered to clients and
when a message is redelivered a certain number of times - e.g. 5 times - without being
acknowledged, the server SHOULD consider the message to be unprocessable (possibly causing
client applications to abort), and move the message to a dead letter queue.
</doc>
</rule>
<chassis name="client" implement="MUST" />
<field name="consumer-tag" domain="consumer-tag" />
<field name="delivery-tag" domain="delivery-tag" />
<field name="redelivered" domain="redelivered" />
<field name="exchange" domain="exchange-name">
<doc>
Specifies the name of the exchange that the message was originally published to.
</doc>
</field>
<field name="routing-key" domain="shortstr" label="Message routing key">
<doc>
Specifies the routing key name specified when the message was published.
</doc>
</field>
<field name="identifier" domain="shortstr" label="staging identifier">
<doc>
This is the staging identifier of the message to deliver. The message must have been
staged. Note that a server can send the Deliver method asynchronously without waiting for
staging to finish.
</doc>
</field>
</method>
<!-- - Method: file.ack - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="ack" index="90" label="acknowledge one or more messages">
<doc>
This method acknowledges one or more messages delivered via the Deliver method. The client
can ask to confirm a single message or a set of messages up to and including a specific
message.
</doc>
<chassis name="server" implement="MUST" />
<field name="delivery-tag" domain="delivery-tag" />
<field name="multiple" domain="bit" label="acknowledge multiple messages">
<doc>
If set to 1, the delivery tag is treated as "up to and including", so that the client can
acknowledge multiple messages with a single method. If set to zero, the delivery tag
refers to a single message. If the multiple field is 1, and the delivery tag is zero,
tells the server to acknowledge all outstanding messages.
</doc>
<rule name="validation">
<doc>
The server MUST validate that a non-zero delivery-tag refers to an delivered message,
and raise a channel exception if this is not the case.
</doc>
</rule>
</field>
</method>
<!-- - Method: file.reject - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="reject" index="100" label="reject an incoming message">
<doc>
This method allows a client to reject a message. It can be used to return untreatable
messages to their original queue. Note that file content is staged before delivery, so the
client will not use this method to interrupt delivery of a large message.
</doc>
<rule name="server-interpretation">
<doc>
The server SHOULD interpret this method as meaning that the client is unable to process
the message at this time.
</doc>
</rule>
<rule name="not-selection">
<doc>
A client MUST NOT use this method as a means of selecting messages to process. A rejected
message MAY be discarded or dead-lettered, not necessarily passed to another client.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="delivery-tag" domain="delivery-tag" />
<field name="requeue" domain="bit" label="requeue the message">
<doc>
If this field is zero, the message will be discarded. If this bit is 1, the server will
attempt to requeue the message.
</doc>
<rule name="requeue-strategy">
<doc>
The server MUST NOT deliver the message to the same client within the context of the
current session. The recommended strategy is to attempt to deliver the message to an
alternative consumer, and if that is not possible, to move the message to a dead-letter
queue. The server MAY use more sophisticated tracking to hold the message on the queue
and redeliver it to the same client at a later stage.
</doc>
</rule>
</field>
</method>
</class>
<!-- == Class: stream ======================================================================== -->
<class name="stream" index="80" label="work with streaming content">
<doc>
The stream class provides methods that support multimedia streaming. The stream class uses the
following semantics: one message is one packet of data; delivery is unacknowledged and
unreliable; the consumer can specify quality of service parameters that the server can try to
adhere to; lower-priority messages may be discarded in favour of high priority messages.
</doc>
<doc type="grammar">
stream = C:QOS S:QOS-OK
/ C:CONSUME S:CONSUME-OK
/ C:CANCEL
/ C:PUBLISH content
/ S:RETURN
/ S:DELIVER content
</doc>
<rule name="overflow-discard">
<doc>
The server SHOULD discard stream messages on a priority basis if the queue size exceeds some
configured limit.
</doc>
</rule>
<rule name="priority-levels">
<doc>
The server MUST implement at least 2 priority levels for stream messages, where priorities
0-4 and 5-9 are treated as two distinct levels. The server MAY implement up to 10 priority
levels.
</doc>
</rule>
<rule name="acknowledgement-support">
<doc>
The server MUST implement automatic acknowledgements on stream content. That is, as soon as
a message is delivered to a client via a Deliver method, the server must remove it from the
queue.
</doc>
</rule>
<chassis name="server" implement="MAY" />
<chassis name="client" implement="MAY" />
<!-- These are the properties for a Stream content -->
<field name="content-type" domain="shortstr" label="MIME content type" />
<field name="content-encoding" domain="shortstr" label="MIME content encoding" />
<field name="headers" domain="table" label="message header field table" />
<field name="priority" domain="octet" label="message priority, 0 to 9" />
<field name="timestamp" domain="timestamp" label="message timestamp" />
<!-- - Method: stream.qos - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="qos" synchronous="1" index="10" label="specify quality of service">
<doc>
This method requests a specific quality of service. The QoS can be specified for the current
session or for all sessions on the connection. The particular properties and semantics of a
qos method always depend on the content class semantics. Though the qos method could in
principle apply to both peers, it is currently meaningful only for the server.
</doc>
<chassis name="server" implement="MUST" />
<response name="qos-ok" />
<field name="prefetch-size" domain="long" label="prefetch window in octets">
<doc>
The client can request that messages be sent in advance so that when the client finishes
processing a message, the following message is already held locally, rather than needing
to be sent within the session. Prefetching gives a performance improvement. This field
specifies the prefetch window size in octets. May be set to zero, meaning "no specific
limit". Note that other prefetch limits may still apply.
</doc>
</field>
<field name="prefetch-count" domain="short" label="prefetch window in messages">
<doc>
Specifies a prefetch window in terms of whole messages. This field may be used in
combination with the prefetch-size field; a message will only be sent in advance if both
prefetch windows (and those at the session and connection level) allow it.
</doc>
</field>
<field name="consume-rate" domain="long" label="transfer rate in octets/second">
<doc>
Specifies a desired transfer rate in octets per second. This is usually determined by the
application that uses the streaming data. A value of zero means "no limit", i.e. as
rapidly as possible.
</doc>
<rule name="ignore-prefetch">
<doc>
The server MAY ignore the prefetch values and consume rates, depending on the type of
stream and the ability of the server to queue and/or reply it.
</doc>
</rule>
<rule name="drop-by-priority">
<doc>
The server MAY drop low-priority messages in favour of high-priority messages.
</doc>
</rule>
</field>
<field name="global" domain="bit" label="apply to entire connection">
<doc>
By default the QoS settings apply to the current session only. If this field is set, they
are applied to the entire connection.
</doc>
</field>
</method>
<!-- - Method: stream.qos-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="qos-ok" synchronous="1" index="11" label="confirm the requested qos">
<doc>
This method tells the client that the requested QoS levels could be handled by the server.
The requested QoS applies to all active consumers until a new QoS is defined.
</doc>
<chassis name="client" implement="MUST" />
</method>
<!-- - Method: stream.consume - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="consume" synchronous="1" index="20" label="start a queue consumer">
<doc>
This method asks the server to start a "consumer", which is a transient request for messages
from a specific queue. Consumers last as long as the session they were created on, or until
the client cancels them.
</doc>
<rule name="min-consumers">
<doc>
The server SHOULD support at least 16 consumers per queue, unless the queue was declared
as private, and ideally, impose no limit except as defined by available resources.
</doc>
</rule>
<rule name="priority-based-delivery">
<doc>
Streaming applications SHOULD use different sessions to select different streaming
resolutions. AMQP makes no provision for filtering and/or transforming streams except on
the basis of priority-based selective delivery of individual messages.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<response name="consume-ok" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "read" access rights to the realm
for the queue from which the message will be consumed.
</doc>
</rule>
</field>
<field name="queue" domain="queue-name">
<doc>
Specifies the name of the queue to consume from. If the queue name is null, refers to the
current queue for the session, which is the last declared queue.
</doc>
<rule name="queue-exists-if-empty" on-failure="not-allowed">
<doc>
If the client did not previously declare a queue, and the queue name in this method is
empty, the server MUST raise a connection exception with reply code 530 (not allowed).
</doc>
</rule>
</field>
<field name="consumer-tag" domain="consumer-tag">
<doc>
Specifies the identifier for the consumer. The consumer tag is local to a connection, so
two clients can use the same consumer tags. If this field is empty the server will
generate a unique tag.
</doc>
<rule name="not-existing-consumer" on-failure="not-allowed">
<doc>
The tag MUST NOT refer to an existing consumer. If the client attempts to create two
consumers with the same non-empty tag the server MUST raise a connection exception with
reply code 530 (not allowed).
</doc>
</rule>
</field>
<field name="no-local" domain="no-local" />
<field name="exclusive" domain="bit" label="request exclusive access">
<doc>
Request exclusive consumer access, meaning only this consumer can access the queue.
</doc>
<rule name="in-use" on-failure="resource-locked">
<doc>
If the server cannot grant exclusive access to the queue when asked, - because there are
other consumers active - it MUST raise a channel exception with return code 405
(resource locked).
</doc>
</rule>
</field>
<field name="nowait" domain="bit" label="do not send a reply method">
<doc>
If set, the server will not respond to the method. The client should not wait for a reply
method. If the server could not complete the method it will raise a channel or connection
exception.
</doc>
</field>
<field name="filter" domain="table" label="arguments for consuming">
<doc>
A set of filters for the consume. The syntax and semantics of these filters depends on the
providers implementation.
</doc>
</field>
</method>
<!-- - Method: stream.consume-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="consume-ok" synchronous="1" index="21" label="confirm a new consumer">
<doc>
This method provides the client with a consumer tag which it may use in methods that work
with the consumer.
</doc>
<chassis name="client" implement="MUST" />
<field name="consumer-tag" domain="consumer-tag">
<doc>
Holds the consumer tag specified by the client or provided by the server.
</doc>
</field>
</method>
<!-- - Method: stream.cancel - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="cancel" synchronous="1" index="30" label="end a queue consumer">
<doc>
This method cancels a consumer. Since message delivery is asynchronous the client may
continue to receive messages for a short while after cancelling a consumer. It may process
or discard these as appropriate.
</doc>
<chassis name="server" implement="MUST" />
<field name="consumer-tag" domain="consumer-tag" />
</method>
<!-- - Method: stream.publish - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="publish" content="1" index="40" label="publish a message">
<doc>
This method publishes a message to a specific exchange. The message will be routed to queues
as defined by the exchange configuration and distributed to any active consumers as
appropriate.
</doc>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "passive" access rights to the
realm for the exchange and "write" access rights to the realm for the queue to which the
message will be published.
</doc>
</rule>
</field>
<field name="exchange" domain="exchange-name">
<doc>
Specifies the name of the exchange to publish to. The exchange name can be empty, meaning
the default exchange. If the exchange name is specified, and that exchange does not exist,
the server will raise a channel exception.
</doc>
<rule name="default">
<doc>
The server MUST accept a blank exchange name to mean the default exchange.
</doc>
</rule>
<rule name="internal" on-failure="access-refused">
<doc>
If the exchange was declared as an internal exchange, the server MUST respond with a
reply code 403 (access refused) and raise a channel exception.
</doc>
</rule>
<rule name="refusal" on-failure="not-implemented">
<doc>
The exchange MAY refuse stream content in which case it MUST respond with a reply code
540 (not implemented) and raise a channel exception.
</doc>
</rule>
</field>
<field name="routing-key" domain="shortstr" label="Message routing key">
<doc>
Specifies the routing key for the message. The routing key is used for routing messages
depending on the exchange configuration.
</doc>
</field>
<field name="mandatory" domain="bit" label="indicate mandatory routing">
<doc>
This flag tells the server how to react if the message cannot be routed to a queue. If
this flag is set, the server will return an unroutable message with a Return method. If
this flag is zero, the server silently drops the message.
</doc>
<rule name="implementation">
<doc>
The server SHOULD implement the mandatory flag.
</doc>
</rule>
</field>
<field name="immediate" domain="bit" label="request immediate delivery">
<doc>
This flag tells the server how to react if the message cannot be routed to a queue
consumer immediately. If this flag is set, the server will return an undeliverable message
with a Return method. If this flag is zero, the server will queue the message, but with no
guarantee that it will ever be consumed.
</doc>
<rule name="implementation">
<doc>
The server SHOULD implement the immediate flag.
</doc>
</rule>
</field>
</method>
<!-- - Method: stream.return - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="return" content="1" index="50" label="return a failed message">
<doc>
This method returns an undeliverable message that was published with the "immediate" flag
set, or an unroutable message published with the "mandatory" flag set. The reply code and
text provide information about the reason that the message was undeliverable.
</doc>
<chassis name="client" implement="MUST" />
<field name="reply-code" domain="reply-code" />
<field name="reply-text" domain="reply-text" />
<field name="exchange" domain="exchange-name">
<doc>
Specifies the name of the exchange that the message was originally published to.
</doc>
</field>
<field name="routing-key" domain="shortstr" label="Message routing key">
<doc>
Specifies the routing key name specified when the message was published.
</doc>
</field>
</method>
<!-- - Method: stream.deliver - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="deliver" content="1" index="60" label="notify the client of a consumer message">
<doc>
This method delivers a message to the client, via a consumer. In the asynchronous message
delivery model, the client starts a consumer using the Consume method, then the server
responds with Deliver methods as and when messages arrive for that consumer.
</doc>
<chassis name="client" implement="MUST" />
<field name="consumer-tag" domain="consumer-tag" />
<field name="delivery-tag" domain="delivery-tag" />
<field name="exchange" domain="exchange-name">
<doc>
Specifies the name of the exchange that the message was originally published to.
</doc>
</field>
<field name="queue" domain="queue-name">
<doc>
Specifies the name of the queue that the message came from. Note that a single session can
start many consumers on different queues.
</doc>
<assert check="notnull" />
</field>
</method>
</class>
<!-- == Class: tx ============================================================================ -->
<class name="tx" index="90" label="work with standard transactions">
<doc>
Standard transactions provide so-called "1.5 phase commit". We can ensure that work is never
lost, but there is a chance of confirmations being lost, so that messages may be resent.
Applications that use standard transactions must be able to detect and ignore duplicate
messages.
</doc>
<doc type="grammar">
tx = C:SELECT
/ C:COMMIT
/ C:ROLLBACK
</doc>
<rule name="duplicate-tracking">
<doc>
An client using standard transactions SHOULD be able to track all messages received within a
reasonable period, and thus detect and reject duplicates of the same message. It SHOULD NOT
pass these to the application layer.
</doc>
</rule>
<chassis name="server" implement="SHOULD" />
<chassis name="client" implement="MAY" />
<!-- - Method: tx.select - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="select" synchronous="1" index="10" label="select standard transaction mode">
<doc>
This method sets the session to use standard transactions. The client must use this method
at least once on a session before using the Commit or Rollback methods.
</doc>
<chassis name="server" implement="MUST" />
</method>
<!-- - Method: tx.commit - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="commit" synchronous="1" index="20" label="commit the current transaction">
<doc>
This method commits all messages published and acknowledged in the current transaction. A
new transaction starts immediately after a commit.
</doc>
<chassis name="server" implement="MUST" />
</method>
<!-- - Method: tx.rollback - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="rollback" synchronous="1" index="30" label="abandon the current transaction">
<doc>
This method abandons all messages published and acknowledged in the current transaction. A
new transaction starts immediately after a rollback.
</doc>
<chassis name="server" implement="MUST" />
</method>
</class>
<!-- == Class: dtx-demarcation =============================================================== -->
<!-- NOTE: (TODO) Comments on AMQP-4 JIRA made since the proposed XML was posted on June 1 have
not yet been incorporated here.
-->
<class name="dtx-demarcation" index="100" label="Demarcates dtx branches">
<doc>
This class is part of the X-Open XA distributed transaction protocol support. It allows a
session to be selected for use with distributed transactions and the transactional boundaries
for work on that session to be demarcated.
</doc>
<doc type="grammar">
dtx-demarcation = C:SELECT *demarcation
demarcation = C:START C:END
</doc>
<rule name="access-control">
<doc>
Access-tickets are propagated with XA association methods with the aim of restricting which
users are allowed to control which transactions. The server MAY restrict transaction
association to a particular identity.
</doc>
</rule>
<rule name="transactionality">
<doc>
Enabling XA transaction support on a session implies that the server MUST manage
transactions demarcated by start-end blocks. That is to say that on this XA-enabled session,
work undergone within transactional blocks is performed on behalf a transaction branch
whereas work performed outside of transactional blocks is NOT transactional.
</doc>
</rule>
<chassis name="server" implement="MAY" />
<chassis name="client" implement="MAY" />
<!-- - Method: dtx-demarcation.select - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="select" synchronous="1" index="10" label="Select dtx mode">
<doc>
This method sets the session to use distributed transactions. The client must use this
method at least once on a session before using XA demarcation operations.
</doc>
<chassis name="server" implement="MAY" />
</method>
<!-- - Method: dtx-demarcation.start - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="start" synchronous="1" index="20" label="Start a dtx branch">
<doc>
This method is called when messages should be produced and consumed on behalf a transaction
branch identified by xid.
</doc>
<rule name="command-invalid" on-failure="command-invalid">
<doc>
If the method is invoked in an improper context (see class grammar) then the server MUST
raise a channel exception with reply code 503 (command invalid)
</doc>
</rule>
<rule name="already-known" on-failure="not-allowed">
<doc>
If neither join nor resume is specified is specified and the transaction branch specified
by xid has previously been seen then the server MUST raise a channel exception with reply
code 530 (not allowed).
</doc>
</rule>
<rule name="join-and-resume" on-failure="command-invalid">
<doc>
If join and resume are specified then the server MUST raise a channel exception with reply
code 503 (command invalid).
</doc>
</rule>
<chassis name="server" implement="MAY" />
<field name="ticket" domain="access-ticket" label="Access-ticket for specific realm">
<doc>
Access-ticket granted by the server for a specific realm.
</doc>
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "active" access rights to all the
realms touched by this transaction.
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="xid" domain="xid" label="Transaction xid">
<doc>
Specifies the xid of the transaction branch to be started.
</doc>
<rule name="unknown-xid" on-failure="not-allowed">
<doc>
If xid is already known by the broker then the server MUST raise a channel exception
with reply code 530 (not allowed).
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="join" domain="bit" label="Join with existing xid flag">
<doc>
Indicate whether this is joining an already associated xid. Indicate that the start
applies to joining a transaction previously seen.
</doc>
<rule name="unsupported" on-failure="not-implemented">
<doc>
If the broker does not support join the server MUST raise a channel exception with reply
code 540 (not implemented).
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="resume" domain="bit" label="Resume flag">
<doc>
Indicate that the start applies to resuming a suspended transaction branch specified.
</doc>
<assert check="notnull" />
</field>
<result>
<struct size="long" type="21">
<doc>
This confirms to the client that the transaction branch is started or specify the error
condition.
</doc>
<field name="status" domain="short" label="Status code">
<doc>
The value of this field may be one of the following constants:
xa-ok: Normal execution.
xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified
reason.
xa-rbtimeout: The work represented by this transaction branch took too long.
</doc>
<assert check="notnull" />
</field>
</struct>
</result>
</method>
<!-- - Method: dtx-demarcation.end - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="end" synchronous="1" index="30" label="End a dtx branch">
<doc>
This method is called when the work done on behalf a transaction branch finishes or needs to
be suspended.
</doc>
<rule name="command-invalid" on-failure="command-invalid">
<doc>
If the method is invoked in an improper context (see class grammar) then the server MUST
raise a channel exception with reply code 503 (command invalid).
</doc>
</rule>
<rule name="suspend-and-fail" on-failure="command-invalid">
<doc>
If suspend and fail are specified then the server MUST raise a channel exception with
reply code 503 (command invalid).
</doc>
</rule>
<rule name="internal-error" on-failure="internal-error">
<doc>
If an error occurs in ending the transaction branch then the server MUST raise a channel
exception with reply code 541 (internal error).
</doc>
</rule>
<rule name="success">
<doc>
If neither fail nor suspend are specified then the portion of work has completed
successfully.
</doc>
</rule>
<rule name="session-closed">
<doc>
When a session is closed then the currently associated transaction branches MUST be marked
rollback-only.
</doc>
</rule>
<chassis name="server" implement="MAY" />
<field name="ticket" domain="access-ticket" label="Access-ticket for specific realm">
<doc>
Access-ticket granted by the server for a specific realm.
</doc>
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "active" access rights to all the
realms touched by this transaction.
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="xid" domain="xid" label="Transaction xid">
<doc>
Specifies the xid of the transaction branch to be ended.
</doc>
<rule name="not-associated" on-failure="command-invalid">
<doc>
The channel MUST be currently associated with the given xid (through an earlier start
call with the same xid).
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="fail" domain="bit" label="Failure flag">
<doc>
If set, indicates that this portion of work has failed; otherwise this portion of work has
completed successfully.
</doc>
<rule name="failure">
<doc>
An implementation MAY elect to roll a transaction back if this failure notification is
recieved. Should an implementation elect to implement this behaviour, and this bit is
set, then then the transaction branch SHOULD be marked as rollback-only and the end
result SHOULD have the xa-rbrollback status set.
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="suspend" domain="bit" label="Temporary suspension flag">
<doc>
Indicates that the transaction branch is temporarily suspended in an incomplete state.
</doc>
<rule name="resume">
<doc>
The transaction context is in a suspended state and must be resumed via the start method
with resume specified.
</doc>
</rule>
<assert check="notnull" />
</field>
<result>
<struct size="long" type="31">
<doc>
This method confirms to the client that the transaction branch is ended or specify the
error condition.
</doc>
<field name="status" domain="short" label="Status code">
<doc>
The value of this field may be one of the following constants:
xa-ok: Normal execution.
xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified
reason. If an implementation chooses to implement rollback-on-failure behaviour, then
this value should be selected if the dtx-demarcation.end.fail bit was set.
xa-rbtimeout: The work represented by this transaction branch took too long.
</doc>
<assert check="notnull" />
</field>
</struct>
</result>
</method>
</class>
<!-- == Class: dtx-coordination ============================================================== -->
<class name="dtx-coordination" index="105" label="Coordinate dtx outcomes">
<doc>
This class is part of the X-Open XA distributed transaction protocol support. It allows the
transaction manager to coordinate transaction outcomes.
</doc>
<doc type="grammar">
dtx-coordination = *coordination
coordination = command
/ outcome
/ recovery
command = C:SET-TIMEOUT
/ C:GET-TIMEOUT
outcome = one-phase-commit
/ one-phase-rollback
/ two-phase-commit
/ two-phase-rollback
one-phase-commit = C:COMMIT
one-phase-rollback = C:ROLLBACK
two-phase-commit = C:PREPARE C:COMMIT
two-phase-rollback = C:PREPARE C:ROLLBACK
recovery = C:RECOVER *recovery-outcome
recovery-outcome = one-phase-commit
/ one-phase-rollback
/ C:FORGET
</doc>
<rule name="security">
<doc>
Access-tickets are propagated with XA demarcation methods with the aim of restricting which
users are allowed to control which transactions. The server MAY restrict transaction
coordination to a particular identity.
</doc>
</rule>
<chassis name="server" implement="MAY" />
<chassis name="client" implement="MAY" />
<!-- - Method: dtx-coordination.commit - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="commit" synchronous="1" index="10" label="Commit work on dtx branch">
<doc>
Commit the work done on behalf a transaction branch. This method commits the work associated
with xid. Any produced messages are made available and any consumed messages are discarded.
</doc>
<rule name="internal-error" on-failure="internal-error">
<doc>
If an error occurs in committing the transaction branch then the server MUST raise a
channel exception with reply code 541 (internal error)
</doc>
</rule>
<rule name="command-invalid" on-failure="command-invalid">
<doc>
If the method is invoked in an improper context (see class grammar) then the server MUST
raise a channel exception with reply code 503 (command invalid)
</doc>
</rule>
<chassis name="server" implement="MAY" />
<field name="ticket" domain="access-ticket" label="Access-ticket for specific realm">
<doc>
Access-ticket granted by the server for a specific realm.
</doc>
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "active" access rights to all the
realms touched by this transaction.
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="xid" domain="xid" label="Transaction xid">
<doc>
Specifies the xid of the transaction branch to be committed.
</doc>
<rule name="unknown-xid" on-failure="not-found">
<doc>
If xid is unknown (the transaction branch has not been started or has already been
ended) then the server MUST raise a channel exception with reply code 404 (not found).
</doc>
</rule>
<rule name="not-disassociated" on-failure="command-invalid">
<doc>
If this method is called when xid is still associated with a session then the server
MUST raise a channel exception with reply code 503 (command invalid)
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="one-phase" domain="bit" label="One-phase optimization flag">
<doc>
When set then one-phase commit optimization is used.
</doc>
<rule name="prerequisite" on-failure="command-invalid">
<doc>
This bit MUST be set if a commit is sent without a preceding prepare.
</doc>
</rule>
<rule name="validity" on-failure="command-invalid">
<doc>
This bit MUST NOT be set if a preceding prepare has been sent.
</doc>
</rule>
<assert check="notnull" />
</field>
<result>
<struct size="long" type="11">
<doc>
This confirms to the client that the transaction branch is committed or specify the
error condition.
</doc>
<field name="status" domain="short" label="Status code">
<doc>
The value of this field may be one of the following constants:
xa-ok: Normal execution
xa-heurhaz: Due to some failure, the work done on behalf of the specified transaction
branch may have been heuristically completed.
xa-heurcom: Due to a heuristic decision, the work done on behalf of the specified
transaction branch was committed.
xa-heurrb: Due to a heuristic decision, the work done on behalf of the specified
transaction branch was rolled back.
xa-heurmix: Due to a heuristic decision, the work done on behalf of the specified
transaction branch was partially committed and partially rolled back.
xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified
reason.
xa-rbtimeout: The work represented by this transaction branch took too long.
</doc>
<assert check="notnull" />
</field>
</struct>
</result>
</method>
<!-- - Method: dtx-coordination.forget - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="forget" synchronous="1" index="20" label="Discard dtx branch">
<doc>
This method is called to forget about a heuristically completed transaction branch.
</doc>
<rule name="internal-error" on-failure="internal-error">
<doc>
If an error occurs in forgetting the transaction branch then the server MUST raise a
channel exception with reply code 541 (internal error)
</doc>
</rule>
<rule name="command-invalid" on-failure="command-invalid">
<doc>
If the method is invoked in an improper context (see class grammar) then the server MUST
raise a channel exception with reply code 503 (command invalid)
</doc>
</rule>
<chassis name="server" implement="MAY" />
<field name="ticket" domain="access-ticket" label="Access-ticket for specific realm">
<doc>
Access-ticket granted by the server for a specific realm.
</doc>
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "active" access rights to all the
realms touched by this transaction.
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="xid" domain="xid" label="Transaction xid">
<doc>
Specifies the xid of the transaction branch to be forgotten.
</doc>
<rule name="unknown-xid" on-failure="not-found">
<doc>
If xid is unknown (the transaction branch has not been started or has already been
ended) then the server MUST raise a channel exception with reply code 404 (not found).
</doc>
</rule>
<rule name="not-disassociated" on-failure="command-invalid">
<doc>
If this method is called when xid is still associated with a session then the server
MUST raise a channel exception with reply code 503 (command invalid).
</doc>
</rule>
<assert check="notnull" />
</field>
</method>
<!-- - Method: dtx-coordination.get-timeout - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="get-timeout" synchronous="1" index="30" label="Obtain dtx timeout in seconds">
<doc>
This method obtains the current transaction timeout value in seconds. If set-timeout was not
used prior to invoking this method, the return value is the default timeout; otherwise, the
value used in the previous set-timeout call is returned.
</doc>
<rule name="internal-error" on-failure="internal-error">
<doc>
If an error occurs in setting the transaction timeout then the server MUST raise a channel
exception with reply code 541 (internal error).
</doc>
</rule>
<chassis name="server" implement="MAY" />
<field name="xid" domain="xid" label="Transaction xid">
<doc>
Specifies the xid of the transaction branch for getting the timeout.
</doc>
<rule name="unknown-xid" on-failure="not-found">
<doc>
If xid is unknown (the transaction branch has not been started or has already been
ended) then the server MUST raise a channel exception with reply code 404 (not found).
</doc>
</rule>
<assert check="notnull" />
</field>
<result>
<struct size="long" type="31">
<doc>
Returns the value of the timeout last specified through set-timeout.
</doc>
<field name="timeout" domain="long" label="The current transaction timeout value">
<doc>
The current transaction timeout value in seconds.
</doc>
<assert check="notnull" />
</field>
</struct>
</result>
</method>
<!-- - Method: dtx-coordination.prepare - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="prepare" synchronous="1" index="40" label="Prepare a dtx branch">
<doc>
This method prepares for commitment any message produced or consumed on behalf of xid.
</doc>
<rule name="internal-error" on-failure="internal-error">
<doc>
If an error occurs in preparing the transaction branch then the server MUST raise a
channel exception with reply code 541 (internal error). The specified xid may or may not
have been prepared.
</doc>
</rule>
<rule name="command-invalid" on-failure="command-invalid">
<doc>
If the method is invoked in an improper context (see class grammar) then the server MUST
raise a channel exception with reply code 503 (command invalid)
</doc>
</rule>
<rule name="obligation-1">
<doc>
Once this method successfully returns it is guaranteed that the transaction branch may be
either committed or rolled back regardless of failures.
</doc>
</rule>
<rule name="obligation-2">
<doc>
The knowledge of xid cannot be erased before commit or rollback complete the branch.
</doc>
</rule>
<chassis name="server" implement="MAY" />
<field name="ticket" domain="access-ticket" label="Access-ticket for specific realm">
<doc>
Access-ticket granted by the server for a specific realm.
</doc>
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "active" access rights to all the
realms touched by this transaction.
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="xid" domain="xid" label="Transaction xid">
<doc>
Specifies the xid of the transaction branch that can be prepared.
</doc>
<rule name="unknown-xid" on-failure="not-found">
<doc>
If xid is unknown (the transaction branch has not been started or has already been
ended) then the server MUST raise a channel exception with reply code 404 (not found).
</doc>
</rule>
<rule name="not-disassociated" on-failure="command-invalid">
<doc>
If this method is called when xid is still associated with a session then the server
MUST raise a channel exception with reply code 503 (command invalid)
</doc>
</rule>
<assert check="notnull" />
</field>
<result>
<struct size="long" type="41">
<doc>
This method confirms to the client that the transaction branch is prepared or specify the
error condition.
</doc>
<field name="status" domain="short" label="Status code">
<doc>
The value of this field may be one of the following constants:
xa-ok: Normal execution.
xa-rdonly: The transaction branch was read-only and has been committed.
xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified
reason.
xa-rbtimeout: The work represented by this transaction branch took too long.
</doc>
<assert check="notnull" />
</field>
</struct>
</result>
</method>
<!-- - Method: dtx-coordination.recover - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="recover" synchronous="1" index="50" label="Get prepared or completed xids">
<doc>
This method is called to obtain a list of transaction branches that are in a prepared or
heuristically completed state.
</doc>
<rule name="internal-error" on-failure="internal-error">
<doc>
If an error occurs in recovering then the server MUST raise a channel exception with reply
code 541 (internal error)
</doc>
</rule>
<rule name="start-end">
<doc>
If this endscan is used in conjunction with startscan then a single call starts and then
ends a scan.
</doc>
</rule>
<rule name="must-be-started" on-failure="command-invalid">
<doc>
If none of endscan and startscan are set then a recovery scan must already be started
otherwise the server MUST raise a channel exception with reply code 503 (command invalid)
</doc>
</rule>
<chassis name="server" implement="MAY" />
<field name="ticket" domain="access-ticket" label="Access-ticket for specific realm">
<doc>
Access-ticket granted by the server for a specific realm.
</doc>
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "active" access rights to all the
realms touched by this transaction.
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="startscan" domain="bit" label="Start recovery scan flag">
<doc>
Indicates that recovery scan should start.
</doc>
<rule name="recovery-already-open">
<doc>
If a recovery scan is already open, the effect is as if the recovery scan were ended and
then restarted.
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="endscan" domain="bit" label="Flag indicating end scan on return of xids">
<doc>
Indicates that the recovery scan should end after returning the xids.
</doc>
<assert check="notnull" />
</field>
<result>
<struct size="long" type="51">
<doc>
Returns to the client a table with single item that is a sequence of transaction xids that
are in a prepared or heuristically completed state.
</doc>
<field name="in-doubt" domain="array" label="array of xids to be recovered">
<doc>
xids to be recovered (xids that are in a prepared or heuristically completed state).
</doc>
<assert check="notnull" />
</field>
</struct>
</result>
</method>
<!-- - Method: dtx-coordination.rollback - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="rollback" synchronous="1" index="60" label="Rollback a dtx branch">
<doc>
This method rolls back the work associated with xid. Any produced messages are discarded and
any consumed messages are re-enqueued.
</doc>
<rule name="internal-error" on-failure="internal-error">
<doc>
If an error occurs in rolling back the transaction branch then the server MUST raise a
channel exception with reply code 541 (internal error)
</doc>
</rule>
<rule name="command-invalid" on-failure="command-invalid">
<doc>
If the method is invoked in an improper context (see class grammar) then the server MUST
raise a channel exception with reply code 503 (command invalid)
</doc>
</rule>
<chassis name="server" implement="MAY" />
<field name="ticket" domain="access-ticket" label="Access-ticket for specific realm">
<doc>
Access-ticket granted by the server for a specific realm.
</doc>
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "active" access rights to all the
realms touched by this transaction.
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="xid" domain="xid" label="Transaction xid">
<doc>
Specifies the xid of the transaction branch that can be rolled back.
</doc>
<rule name="unknown-xid" on-failure="not-found">
<doc>
If xid is unknown (the transaction branch has not been started or has already been
ended) then the server MUST raise a channel exception with reply code 404 (not found).
</doc>
</rule>
<rule name="not-disassociated" on-failure="command-invalid">
<doc>
If this method is called when xid is still associated with a session then the server
MUST raise a channel exception with reply code 503 (command invalid)
</doc>
</rule>
<assert check="notnull" />
</field>
<result>
<struct size="long" type="61">
<doc>
This method confirms to the client that the transaction branch is rolled back or specify the
error condition.
</doc>
<field name="status" domain="short" label="Status code">
<doc>
The value of this field may be one of the following constants:
xa-ok: Normal execution
xa-heurhaz: Due to some failure, the work done on behalf of the specified transaction
branch may have been heuristically completed.
xa-heurcom: Due to a heuristic decision, the work done on behalf of the specified
transaction branch was committed.
xa-heurrb: Due to a heuristic decision, the work done on behalf of the specified
transaction branch was rolled back.
xa-heurmix: Due to a heuristic decision, the work done on behalf of the specified
transaction branch was partially committed and partially rolled back.
xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified
reason.
xa-rbtimeout: The work represented by this transaction branch took too long.
</doc>
<assert check="notnull" />
</field>
</struct>
</result>
</method>
<!-- - Method: dtx-coordination.set-timeout - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="set-timeout" synchronous="1" index="70" label="Set dtx timeout value">
<doc>
Sets the specified transaction branch timeout value in seconds.
</doc>
<rule name="internal-error" on-failure="internal-error">
<doc>
If an error occurs in setting the transaction timeout then the server MUST raise a channel
exception with reply code 541 (internal error)
</doc>
</rule>
<rule name="effective">
<doc>
Once set, this timeout value is effective until this method is reinvoked with a different
value.
</doc>
</rule>
<rule name="reset">
<doc>
A value of zero resets the timeout value to the default value.
</doc>
</rule>
<chassis name="server" implement="MAY" />
<field name="ticket" domain="access-ticket" label="Access-ticket for specific realm">
<doc>
Access-ticket granted by the server for a specific realm.
</doc>
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "active" access rights to all the
realms touched by this transaction.
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="xid" domain="xid" label="Transaction xid">
<doc>
Specifies the xid of the transaction branch for setting the timeout.
</doc>
<rule name="unknown-xid" on-failure="not-found">
<doc>
If xid is unknown (the transaction branch has not been started or has already been
ended) then the server MUST raise a channel exception with reply code 404 (not found).
</doc>
</rule>
<assert check="notnull" />
</field>
<field name="timeout" domain="long" label="Dtx timeout in seconds">
<doc>
The transaction timeout value in seconds.
</doc>
<assert check="notnull" />
</field>
</method>
</class>
<!-- == Class: tunnel ========================================================================= -->
<class name="tunnel" index="110" label="methods for protocol tunnelling">
<doc>
The tunnel methods are used to send blocks of binary data - which can be serialised AMQP
methods or other protocol frames - between AMQP peers.
</doc>
<doc type="grammar">
tunnel = C:REQUEST
/ S:REQUEST
</doc>
<chassis name="server" implement="MAY" />
<chassis name="client" implement="MAY" />
<field name="headers" domain="table" label="message header field table" />
<field name="proxy-name" domain="shortstr" label="identity of tunnelling proxy" />
<field name="data-name" domain="shortstr" label="name or type of message being tunnelled" />
<field name="durable" domain="octet" label="message durability indicator" />
<field name="broadcast" domain="octet" label="message broadcast mode" />
<!-- - Method: tunnel.request - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="request" content="1" index="10" label="sends a tunnelled method">
<doc>
This method tunnels a block of binary data, which can be an encoded AMQP method or other
data. The binary data is sent as the content for the Tunnel.Request method.
</doc>
<chassis name="server" implement="MUST" />
<field name="meta-data" domain="table" label="meta data for the tunnelled block">
<doc>
This field table holds arbitrary meta-data that the sender needs to pass to the recipient.
</doc>
</field>
</method>
</class>
<!-- == Class: message ======================================================================= -->
<class name="message" index="120" label="message transfer">
<doc>
The message class provides methods that support an industry-standard messaging model.
</doc>
<doc type="grammar">
message = C:QOS
/ C:CONSUME
/ C:CANCEL
/ C:TRANSFER [ S:REJECT ]
/ S:TRANSFER [ C:REJECT ]
/ C:GET [ S:EMPTY ]
/ C:RECOVER
/ C:OPEN
/ S:OPEN
/ C:APPEND
/ S:APPEND
/ C:CLOSE
/ S:CLOSE
/ C:CHECKPOINT
/ S:CHECKPOINT
/ C:RESUME S:OFFSET
/ S:RESUME C:OFFSET
</doc>
<rule name="persistent-message">
<doc>
The server SHOULD respect the persistent property of messages and SHOULD make a best-effort
to hold persistent mess ages on a reliable storage mechanism.
</doc>
<doc type="scenario">
Send a persistent message to queue, stop server, restart server and then verify whether
message is still present. Assumes that queues are durable. Persistence without durable
queues makes no sense.
</doc>
</rule>
<rule name="no-persistent-message-discard">
<doc>
The server MUST NOT discard a persistent message in case of a queue overflow.
</doc>
<doc type="scenario">
Create a queue overflow situation with persistent messages and verify that messages do not
get lost (presumably the server will write them to disk).
</doc>
</rule>
<rule name="throttling">
<doc>
The server MAY use the Session.Flow method to slow or stop a message publisher when
necessary.
</doc>
<doc type="scenario">
Create a queue overflow situation with non-persistent messages and verify whether the server
responds with Session.Flow or not. Repeat with persistent messages.
</doc>
</rule>
<rule name="non-persistent-message-overflow">
<doc>
The server MAY overflow non-persistent messages to persistent storage.
</doc>
</rule>
<rule name="non-persistent-message-discard">
<doc>
The server MAY discard or dead-letter non-persistent messages on a priority basis if the
queue size exceeds some configured limit.
</doc>
</rule>
<rule name="min-priority-levels">
<doc>
The server MUST implement at least 2 priority levels for messages, where priorities 0-4 and
5-9 are treated as two distinct levels.
</doc>
<doc type="scenario">
Send a number of priority 0 messages to a queue. Send one priority 9 message. Consume
messages from the queue and verify that the first message received was priority 9.
</doc>
</rule>
<rule name="max-priority-levels">
<doc>
The server MAY implement up to 10 priority levels.
</doc>
<doc type="scenario">
Send a number of messages with mixed priorities to a queue, so that all priority values from
0 to 9 are exercised. A good scenario would be ten messages in low-to-high priority. Consume
from queue and verify how many priority levels emerge.
</doc>
</rule>
<rule name="priority-delivery">
<doc>
The server MUST deliver messages of the same priority in order irrespective of their
individual persistence.
</doc>
<doc type="scenario">
Send a set of messages with the same priority but different persistence settings to a queue.
Consume and verify that messages arrive in same order as originally published.
</doc>
</rule>
<rule name="automatic-acknowledgements">
<doc>
The server MUST support automatic acknowledgements on messages, i.e. consumers with the
no-ack field set to FALSE.
</doc>
<doc type="scenario">
Create a queue and a consumer using automatic acknowledgements. Publish a set of messages to
the queue. Consume the messages and verify that all messages are received.
</doc>
</rule>
<rule name="explicit-acknowledgements">
<doc>
The server MUST support explicit acknowledgements on messages, i.e. consumers with the
no-ack field set to TRUE.
</doc>
<doc type="scenario">
Create a queue and a consumer using explicit acknowledgements. Publish a set of messages to
the queue. Consume the messages but acknowledge only half of them. Disconnect and reconnect,
and consume from the queue. Verify that the remaining messages are received.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<!-- - Method: message.transfer - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="transfer" content="1" index="10" label="transfer a message">
<doc>
This method transfers a message between two peers. When a client uses this method to publish
a message to a broker, the destination identifies a specific exchange. The message will then
be routed to queues as defined by the exchange configuration and distributed to any active
subscriptions when the transaction, if any, is committed.
The client may initiate transfers from the broker by starting a subscription using the
subscribe method and passing in a destination, then the broker responds with transfer
methods to the specified destination as and when messages arrive in the subscribed queue.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<field name="ticket" domain="access-ticket" label="access ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "passive" access rights to the
realm for the exchange and "write" access rights to the realm for the queue to which the
message will be published.
</doc>
</rule>
</field>
<field name="destination" domain="destination" label="message destination">
<doc>
Specifies the destination to which the message is to be transferred. The destination can
be empty, meaning the default exchange or subscription. If the destination is specified,
and that exchange or subscription does not exist, the peer must raise a channel exception.
</doc>
<rule name="blank-destination">
<doc>
The server MUST accept a blank destination to mean the default exchange.
</doc>
</rule>
<rule name="internal-exchange">
<doc>
If the destination refers to an internal exchange, the server MUST raise a channel
exception with a reply code 403 (access refused).
</doc>
</rule>
<rule name="message-refusal">
<doc>
A destination MAY refuse message content in which case it MUST raise a channel exception
with reply code 540 (not implemented).
</doc>
</rule>
</field>
<field name="confirm-mode" domain="confirm-mode" />
<field name="acquire-mode" domain="acquire-mode" />
</method>
<!-- - Method: message.reject - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="reject" index="160" label="reject a message">
<doc>
Indicates that the message transfers are un-processable in some way. A message may be
rejected for a number of reasons. A server may reject a message if it is unroutable. A
client may reject a message if it is invalid.
</doc>
<rule name="alternate-exchange">
<doc>
When a client rejects a message, the server MUST deliver that message to the
alternate-exchange on the queue from which it was delivered. If no alternate-exchange is
defined for that queue the broker MAY discard the message.
</doc>
</rule>
<rule name="acquisition">
<doc>
The recipient MUST have acquired a message in order to reject it. If the message is not
acquired any reject MUST be ignored.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MAY" />
<field name="transfers" domain="correlation" />
<field name="code" domain="reject-code" />
<field name="text" domain="reject-text" />
</method>
<!-- - Method: message.acquire - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="acquire" index="170" label="acquire messages for consumption">
<doc>
Acquires previously transferred messages for consumption. The acquired ids (if any) are
sent via message.acquired.
</doc>
<chassis name="server" implement="MUST" />
<field name="transfers" domain="correlation" />
<!-- do we need this field? -->
<field name="mode" domain="octet">
<doc>
One of:
- any (0): acquire any available messages for consumption
- all (1): only acquire messages if all are available for consumption
</doc>
</field>
</method>
<!-- - Method: message.acquired - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="acquired" index="180" label="indicates acquired messages">
<doc>
Identifies a set of previously transferred messages now available for consumption.
</doc>
<chassis name="client" implement="MAY" />
<field name="transfers" domain="correlation" />
</method>
<!-- - Method: message.release - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="release" index="190" label="release a message">
<doc>
Release previously transferred messages that have been acquired for consumption (whether
implicitly or explicitly). Released messages will be available for acquisition by other
consumers. The order of released messages may be lost.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MAY" />
<field name="transfers" domain="correlation" />
</method>
<!-- - Method: message.subscribe - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="subscribe" index="20" label="start a queue subscription">
<doc>
This method asks the server to start a "subscription", which is a transient request for
messages from a specific queue. Subscriptions last as long as the session they were created
on, or until the client cancels them.
</doc>
<rule name="simultaneous-subscriptions">
<doc>
The server SHOULD support at least 16 subscriptions per queue, and ideally, impose no
limit except as defined by available resources.
</doc>
<doc type="scenario">
Create a queue and create subscriptions on that queue until the server closes the
connection. Verify that the number of subscriptions created was at least sixteen and
report the total number.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "read" access rights to the realm
for the subscribed queue.
</doc>
<doc type="scenario">
Attempt to create a subscription with an invalid (non-zero) access ticket.
</doc>
</rule>
</field>
<field name="queue" domain="queue-name">
<doc>
Specifies the name of the subscribed queue.
</doc>
</field>
<field name="destination" domain="destination" label="incoming message destination">
<doc>
Specifies the destination for the subscription. The destination is local to a connection,
so two clients can use the same destination.
</doc>
<rule name="destination-non-existing-subscription" on-failure="not-allowed">
<doc>
The client MUST NOT specify a destination that refers to an existing subscription.
</doc>
<doc type="scenario">
Attempt to create two subscriptions with the same non-empty destination.
</doc>
</rule>
<rule name="destination-session-bound" on-failure="not-allowed">
<doc>
The destination is valid only within the session from which the subscription was
created. i.e. A client MUST NOT create a subscription in one session and then use it in
another.
</doc>
<doc type="scenario">
Attempt to create a subscription in one session, then use in another session, in which
subscriptions have also been created (to test that the server uses unique destinations).
</doc>
</rule>
</field>
<field name="no-local" domain="no-local" label="messages not returned to publisher">
<doc>
If the no-local field is set the server will not send messages to the connection that
published them.
</doc>
</field>
<field name="confirm-mode" domain="confirm-mode">
<doc>
The default confirm-mode for this subscription.
</doc>
</field>
<field name="acquire-mode" domain="acquire-mode">
<doc>
The default acquire-mode for this subscription.
</doc>
</field>
<field name="exclusive" domain="bit" label="request exclusive access">
<doc>
Request exclusive subscription access, meaning only this subscription can access the queue.
</doc>
<rule name="in-use" on-failure="access-refused">
<doc>
The client MUST NOT gain exclusive access to a queue that already has active subscriptions.
</doc>
<doc type="scenario">
Open two connections to a server, and in one connection create a shared (non-exclusive)
queue and then subscribe to the queue. In the second connection attempt to subscribe to
the same queue using the exclusive option.
</doc>
</rule>
</field>
<field name="filter" domain="table" label="arguments for filtering">
<doc>
A set of filters for the subscription. The syntax and semantics of these filters depends
on the providers implementation.
</doc>
</field>
</method>
<!-- - Method: message.cancel - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="cancel" index="30" label="end a queue consumer">
<doc>
This method cancels a consumer. This does not affect already delivered messages, but it does
mean the server will not send any more messages for that consumer. The client may receive an
arbitrary number of messages in between sending the cancel method and receiving the
notification of completion of the cancel command.
</doc>
<rule name="ignore">
<doc>
If the queue does not exist the server MUST ignore the cancel method, so long as the
consumer tag is valid for that session.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="destination" domain="destination" />
</method>
<!-- - Method: message.get - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="get" index="40" label="direct access to a queue">
<doc>
This method provides a direct access to the messages in a queue using a synchronous dialogue
that is designed for specific types of application where synchronous functionality is more
important than performance.
</doc>
<chassis name="server" implement="MUST" />
<response name="empty" />
<field name="ticket" domain="access-ticket">
<rule name="ticket-required" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "read" access rights to the realm
for the queue from which the message will be consumed.
</doc>
</rule>
</field>
<field name="queue" domain="queue-name">
<doc>
Specifies the name of the queue to consume from. If the queue name is null, refers to the
current queue for the session, which is the last declared queue.
</doc>
<rule name="empty-name">
<doc>
If the client did not previously declare a queue, and the queue name in this method is
empty, the server MUST raise a connection exception with reply code 530 (not allowed).
</doc>
</rule>
</field>
<field name="destination" domain="destination">
<doc>
On normal completion of the get request (i.e. a response of ok). A message will be
transferred to the supplied destination.
</doc>
</field>
<field name="no-ack" domain="no-ack" />
</method>
<!-- - Method: message.recover - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="recover" index="50" label="redeliver unacknowledged messages">
<doc>
This method asks the broker to redeliver all unacknowledged messages on a specified session.
Zero or more messages may be redelivered. This method is only allowed on non-transacted
sessions.
</doc>
<rule name="redelivered-flag">
<doc>
The server MUST set the redelivered flag on all messages that are resent.
</doc>
</rule>
<rule name="transacted-session">
<doc>
The server MUST raise a channel exception if this is called on a transacted session.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<field name="requeue" domain="bit" label="requeue the message">
<doc>
If this field is zero, the message will be redelivered to the original recipient. If this
bit is 1, the server will attempt to requeue the message, potentially then delivering it
to an alternative subscriber.
</doc>
</field>
</method>
<!-- - Method: message.open - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="open" index="60" label="create a reference to an empty message body">
<doc>
This method creates a reference. A references provides a means to send a message body into a
temporary area at the recipient end and then deliver the message by referring to this
temporary area. This is how the protocol handles large message transfers.
The scope of a ref is defined to be between calls to open (or resume) and close. Between
these points it is valid for a ref to be used from any content data type, and so the
receiver must hold onto its contents. Should the session be closed when a ref is still in
scope, the receiver may discard its contents (unless it is checkpointed). A ref that is in
scope is considered open.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<field name="reference" domain="reference">
<rule name="duplicate-reference">
<doc>
The recipient MUST generate an error if the reference is currently open (in scope).
</doc>
</rule>
</field>
</method>
<!-- - Method: message.close - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="close" index="70" label="close a reference">
<doc>
This method signals the recipient that no more data will be appended to the reference.
</doc>
<rule name="message-acknowledge-after-close">
<doc>
A recipient MUST NOT acknowledge a message until its reference is closed (not in scope).
</doc>
</rule>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<field name="reference" domain="reference" label="target reference">
<rule name="non-existent-reference">
<doc>
The recipient MUST generate an error if the reference was not previously open (in
scope).
</doc>
</rule>
</field>
</method>
<!-- - Method: message.append - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="append" index="80" label="append to a reference">
<doc>This method appends data to a reference.</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<field name="reference" domain="reference" label="target reference">
<rule name="non-existent-reference">
<doc>
The recipient MUST generate an error if the reference is not open (not in scope).
</doc>
</rule>
</field>
<field name="bytes" domain="longstr" label="data to append" />
</method>
<!-- - Method: message.checkpoint - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="checkpoint" index="90" label="checkpoint a message body">
<doc>
This method provides a means to checkpoint large message transfer. The sender may ask the
recipient to checkpoint the contents of a reference using the supplied identifier. The
sender may then resume the transfer at a later point. It is at the discretion of the
recipient how much data to save with the checkpoint, and the sender MUST honour the offset
returned by the resume method.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<field name="reference" domain="reference" label="target reference">
<rule name="non-existent-reference">
<doc>
The recipient MUST generate an error if the reference is not open (not in scope).
</doc>
</rule>
</field>
<field name="identifier" domain="shortstr" label="checkpoint identifier">
<doc>
This is the checkpoint identifier. This is an arbitrary string chosen by the sender. For
checkpointing to work correctly the sender must use the same checkpoint identifier when
resuming the message. A good choice for the checkpoint identifier would be the SHA1 hash
of the message properties data (including the original filename, revised time, etc.).
</doc>
</field>
</method>
<!-- - Method: message.resume - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="resume" index="100" label="open and resume a checkpointed message">
<doc>
This method resumes a reference from the last checkpoint. A reference is considered to be
open (in scope) after a resume even though it will not have been opened via the open method
during this session.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<response name="offset" />
<field name="reference" domain="reference" label="target reference">
<rule name="non-existent-reference">
<doc>
The recipient MUST generate an error if the reference is currently open (in scope).
</doc>
</rule>
</field>
<field name="identifier" domain="shortstr" label="checkpoint identifier" />
</method>
<!-- - Method: message.qos - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="qos" index="110" label="specify quality of service">
<doc>
This method requests a specific quality of service. The QoS can be specified for the current
session or for all sessions on the connection. The particular properties and semantics of a
qos method always depend on the content class semantics. Though the qos method could in
principle apply to both peers, it is currently meaningful only for the server.
</doc>
<chassis name="server" implement="MUST" />
<field name="prefetch-size" domain="long" label="prefetch window in octets">
<doc>
The client can request that messages be sent in advance so that when the client finishes
processing a message, the following message is already held locally, rather than needing
to be sent within the session. Prefetching gives a performance improvement. This field
specifies the prefetch window size in octets. The server will send a message in advance if
it is equal to or smaller in size than the available prefetch size (and also falls into
other prefetch limits). May be set to zero, meaning "no specific limit", although other
prefetch limits may still apply. The prefetch-size is ignored if the no-ack option is set.
</doc>
<rule name="non-responsive-client">
<doc>
The server MUST ignore this setting when the client is not processing any messages -
i.e. the prefetch size does not limit the transfer of single messages to a client, only
the sending in advance of more messages while the client still has one or more
unacknowledged messages.
</doc>
<doc type="scenario">
Define a QoS prefetch-size limit and send a single message that exceeds that limit.
Verify that the message arrives correctly.
</doc>
</rule>
</field>
<field name="prefetch-count" domain="short" label="prefetch window in messages">
<doc>
Specifies a prefetch window in terms of whole messages. This field may be used in
combination with the prefetch-size field; a message will only be sent in advance if both
prefetch windows (and those at the session and connection level) allow it. The
prefetch-count is ignored if the no-ack option is set.
</doc>
<rule name="prefetch-maximum">
<doc>
The server may send less data in advance than allowed by the client's specified prefetch
windows but it MUST NOT send more.
</doc>
<doc type="scenario">
Define a QoS prefetch-size limit and a prefetch-count limit greater than one. Send
multiple messages that exceed the prefetch size. Verify that no more than one message
arrives at once.
</doc>
</rule>
</field>
<field name="global" domain="bit" label="apply to entire connection">
<doc>
By default the QoS settings apply to the current session only. If this field is set, they
are applied to the entire connection.
</doc>
</field>
</method>
<!-- - Method: message.flow-mode - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="flow-mode" index="120" label="set the flow control mode">
<doc>
Sets the mode of flow control used for a given destination.
With credit based flow control, the sender of messages continually maintains its current
credit balance with the recipient. The credit balance consists of two values, a message
count, and a byte count. Whenever message data is sent, both counts must be decremented.
If either value reaches zero, the flow of message data must stop. Additional credit is
received via the message.flow method.
The sender MUST NOT send partial framesets. This means that if there is not enough byte
credit available to send a complete message, the sender must either wait or use chunked
transfer to send the first part of the message data in a complete frameset.
Window based flow control is identical to credit based flow control, however message
acknowledgment implicitly grants a single unit of message credit, and the size of the
message in byte credits for each acknowledged message.
</doc>
<rule name="byte-accounting">
<doc>
The byte count is decremented by the payload size of each transmitted frame with
segment type header or body appearing within a message.transfer command. Note that
the payload size is the frame size less the frame header size (frame-size - 12).
</doc>
</rule>
<rule name="mode-switching">
<doc>
Mode switching may only occur if both outstanding credit balances are zero. There are
three ways for a recipient of messages to be sure that the sender 's credit balance is
zero:
1) The recipient may send a message.stop command to the sender. When the recipient
receives confirmation of completion for the message.stop command, it knows that the
sender's credit is zero.
2) The recipient may perform the same steps described in (1) with the message.flush
command substituted for the message.stop command.
3) Immediately after receiving a message.consume, the credit for that destination
defaults to zero.
</doc>
</rule>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<field name="destination" domain="destination" />
<field name="mode" domain="octet">
<doc>
One of:
- credit (0): choose credit based flow control
- window (1): choose window based flow control
</doc>
</field>
</method>
<!-- - Method: message.flow - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="flow" index="130" label="control message flow">
<doc>
This method controls the flow of message data to a given destination. It is used by the
recipient of messages to dynamically match the incoming rate of message flow to its
processing or forwarding capacity. Upon receipt of this method, the sender must add "value"
number of the specified unit to the available credit balance for the specified destination.
A value of (0xFFFFFFFF) indicates an infinite amount of credit. This disables any limit for
the given unit until the credit balance is zeroed with message.stop or message.flush.
</doc>
<!-- throws no-such-destination -->
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<field name="destination" domain="destination"/>
<field name="unit" domain="octet">
<doc>
Specifies the unit of credit balance.
One of:
- message (0)
- byte (1)
</doc>
</field>
<field name="value" domain="long">
<doc>
A value of (0xFFFFFFFF) indicates an infinite amount of credit.
</doc>
</field>
</method>
<!-- - Method: message.flush - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="flush" index="140">
<doc>
Forces the sender to exhaust his credit supply. The sender's credit will always be zero when
this method completes. The message does not complete until all the message transfers occur.
</doc>
<chassis name="server" implement="MUST" />
<field name="destination" domain="destination" />
</method>
<!-- - Method: message.stop - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="stop" index="150">
<doc>
On receipt of this method, a producer of messages MUST set his credit to zero for the given
destination. This obeys the generic semantics of command completion, i.e. when confirmation
is issued credit MUST be zero and no further messages will be sent until such a time as
further credit is received.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<field name="destination" domain="destination" />
</method>
<!-- - Method: message.empty - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="empty" index="200" label="empty queue">
<doc>
Signals that a queue does not contain any messages; usually sent in response to the get
method.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
</method>
<!-- - Method: message.offset - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="offset" index="210" label="return an offset">
<doc>
Returns the data offset into a reference body; usually sent in response to resume method.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MUST" />
<field name="value" domain="offset" label="offset into a reference body">
<doc>
Offset in bytes into message body data.
</doc>
</field>
</method>
</class>
<!-- == Class: binding ======================================================================= -->
<class name="binding" index="130"
label="provides the ability to query bindings">
<doc>
This is a utility class for querying and exchange about its bindings to queues.
</doc>
<chassis name="server" implement="MUST" />
<chassis name="client" implement="MAY" />
<!-- - Method: binding.query - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="query" synchronous="1" index="10"
label="request information about bindings to an exchange">
<doc>
This method is used to request information on the bindings to a particular exchange.
</doc>
<chassis name="server" implement="MUST" />
<field name="ticket" domain="access-ticket">
<rule name="validity" on-failure="access-refused">
<doc>
The client MUST provide a valid access ticket giving "passive" access rights to the
exchange's access realm.
</doc>
</rule>
</field>
<field name="exchange" domain="shortstr" label="the exchange name">
<doc>
The name of the exchange for which binding information is being requested. If not
specified explicitly the default exchange is implied.
</doc>
</field>
<field name="queue" domain="shortstr" label="a queue name">
<doc>
If populated then determine whether the given queue is bound to the exchange.
</doc>
</field>
<field name="routing-key" domain="shortstr" label="a routing-key">
<doc>
If populated defines the routing key of the binding of interest, if not populated the
request will ignore the routing key on bindings when searching for a match.
</doc>
</field>
<field name="arguments" domain="table" label="a set of binding arguments">
<doc>
If populated defines the arguments of the binding of interest if not populated the request
will ignore the arguments on bindings when searching for a match
</doc>
</field>
<result>
<struct size="long" type="11">
<doc>
This method is used in response to a query and conveys information on the bindings to a
particular exchange.
</doc>
<field name="exchange-not-found" domain="bit" label="indicate an unknown exchange">
<doc>
If set, the exchange for which information was requested is not known.
</doc>
</field>
<field name="queue-not-found" domain="bit" label="indicate an unknown queue">
<doc>
If set, the queue specified is not known.
</doc>
</field>
<field name="queue-not-matched" domain="bit" label="indicate no matching queue">
<doc>
A bit which if set indicates that no binding was found from the specified exchange to the
specified queue.
</doc>
</field>
<field name="key-not-matched" domain="bit" label="indicate no matching routing key">
<doc>
A bit which if set indicates that no binding was found from the specified exchange with
the specified routing key.
</doc>
</field>
<field name="args-not-matched" domain="bit" label="indicate no matching args">
<doc>
A bit which if set indicates that no binding was found from the specified exchange with
the specified arguments.
</doc>
</field>
</struct>
</result>
</method>
</class>
<!-- == Class: execution ===================================================================== -->
<class name="execution" index="140">
<doc>
This class allows for efficiently communicating information about completion of processing.
</doc>
<chassis name="server" implement="MUST"/>
<chassis name="client" implement="MUST"/>
<!-- - Method: execution.flush - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="flush" index="10" label="request an execution.complete return method">
<doc>
Requests notification of all currently complete commands. The server should issue an
execution.complete at the earliest possible opportunity.
</doc>
<chassis name="server" implement="MUST"/>
<chassis name="client" implement="MUST"/>
</method>
<!-- - Method: execution.complete - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="complete" index="20">
<doc>
Signals completion of all commands such that command-id &lt;= cumulative-execution-mark, or
command-id is in the set defined by ranged-execution-set. This can be sent spontaneously,
in response to a execution.flush, or as requested by use of the sync bit.
<!-- TODO: See chapter (TBD here) for how command ids are computed. -->
</doc>
<rule name="unique-encoding">
<doc>
In order to ensure a canonical wire representation, the value cumulative-execution-mark +
1 must not be covered by the ranged-execution-set.
</doc>
</rule>
<chassis name="server" implement="MUST"/>
<chassis name="client" implement="MUST"/>
<field name="cumulative-execution-mark" domain="rfc1982-long"
label="Low-water mark for command ids">
<doc>
The low-water mark for executed command-ids. All ids below this mark have been executed;
above this mark, there are gaps containing unexecuted command ids (i.e. discontinuous). By
definition, the first id above this mark (if it exists) is an unexecuted command-id.
</doc>
</field>
<field name="ranged-execution-set" domain="rfc1982-long-set"
label="Set of discontinuous command ids above cumulative-execution-mark">
<doc>
This set contains a sequence of discontinuous executed command-ids above the low-water
mark (i.e. above the first gap of unexecuted command ids).
</doc>
</field>
</method>
<!-- - Method: execution.noop - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="noop" index="30" label="a command that does nothing">
<doc>
This command may be used when it is desirable to send a command that has no effect. This
situation can occur after issuing a number of commands with sync=False. If, after issuing
the commands, a peer wishes to receive confirmation of completion, the peer can do so by
sending an execution.noop command with sync=True.
</doc>
<chassis name="server" implement="MUST"/>
<chassis name="client" implement="MUST"/>
</method>
<!-- - Method: execution.result - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="result" index="40" label="carries execution results">
<doc>
This method carries data resulting from the execution of a command.
</doc>
<chassis name="server" implement="MUST"/>
<chassis name="client" implement="MUST"/>
<field name="command-id" domain="command-id"/>
<field name="data" domain="long-struct"/>
</method>
<!-- - Method: execution.sync - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<method name="sync" index="50" label="request notification of completion for issued commands">
<doc>
Requests notification (via execution.complete) when all commands issued prior to the sync
control are complete. If the recipient of this control has already notified the
sender that said commands are complete, it may safely ignore the control.
</doc>
<chassis name="server" implement="MUST"/>
<chassis name="client" implement="MUST"/>
</method>
</class>
</amqp>