diff options
Diffstat (limited to 'gentools/xml-src/amqp-0.8.test.xml')
| -rw-r--r-- | gentools/xml-src/amqp-0.8.test.xml | 3959 |
1 files changed, 0 insertions, 3959 deletions
diff --git a/gentools/xml-src/amqp-0.8.test.xml b/gentools/xml-src/amqp-0.8.test.xml deleted file mode 100644 index b0adf31828..0000000000 --- a/gentools/xml-src/amqp-0.8.test.xml +++ /dev/null @@ -1,3959 +0,0 @@ -<?xml version="1.0"?> - -<!-- - 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\ufffd 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, 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 - ---> - -<!-- -======================================================== -EDITORS: (PH) Pieter Hintjens <ph@imatix.com> - (KvdR) Kim van der Riet <kim.vdriet@redhat.com> - -NOTE: 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. -======================================================== - -Revision history: - 2006-06-07 (PH) - version number changed to 0.8 to conform to public - release documentation. - - 2006-05-15 (PH) - fixed comments on queue name in basic.get to clarify - use of current queue in this method. - - 2006-05-15 (PH) - fixed comments on routing key in queue.bind to clarify - how routing key is filled when empty (to allow asynch queue.declare). - - 2006-05-11 (PH) - reset version to 0.70 so that putatitive standards - group can release 2-3 major new versions before hitting 1.0 (again). - - 2006-05-11 (PH) - TODO in documentation: cycle field in frame header - has been removed. - - 2006-05-11 (PH) - added nowait option to exchange.declare, delete, - queue.declare, delete, bind, purge, basic.consume, cancel, - file.consume, cancel, stream.consume and cancel methods. - - 2006-05-11 (PH) - removed notnull rule and added explanations on queue - name in queue.bind, purge, delete, basic.consume, cancel, file.consume, - cancel, stream.consume and cancel methods. - - 2006-05-11 (PH) - added basic.qos, file.qos, and stream.qos methods that - regroup all prefetch options from the consume methods. Also removed the - prefetch option from channel.open. - - 2006-05-11 (PH) - renumbered method indexes to show request-response - nature of methods; requests are 10, 20, 30 while responses are 11, 21, - etc. - - 2006-05-11 (PH) - removed OpenAMQ extension methods from this definition - since these are maintained seperately. - - 2006-05-26 (RG) - added Basic.Recover method to allow replay of - unacknowledged messages on a channel. - - 2006-07-03 (PH) - cosmetic clean-up of Basic.Recover comments. ---> - -<amqp major="8" minor="0" port="5672" comment="AMQ protocol 0.80"> - AMQ Protocol 0.80 - -<!-- -====================================================== -== CONSTANTS -====================================================== ---> - <constant name="frame method" value="1"/> - <constant name="frame header" value="2"/> - <constant name="frame body" value="3"/> - <constant name="frame oob method" value="4"/> - <constant name="frame oob header" value="5"/> - <constant name="frame oob body" value="6"/> - <constant name="frame trace" value="7"/> - <constant name="frame heartbeat" value="8"/> - <constant name="frame min size" value="4096"/> - <constant name="frame end" value="206"/> - <constant name="reply success" value="200"> - 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. -</constant> - <constant name="not delivered" value="310" class="soft error"> - 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. -</constant> - <constant name="content too large" value="311" class="soft error"> - The client attempted to transfer content larger than the server - could accept at the present time. The client may retry at a later - time. -</constant> - <constant name="connection forced" value="320" class="hard error"> - An operator intervened to close the connection for some reason. - The client may retry at some later date. -</constant> - <constant name="invalid path" value="402" class="hard error"> - The client tried to work with an unknown virtual host or cluster. -</constant> - <constant name="access refused" value="403" class="soft error"> - The client attempted to work with a server entity to which it has - no due to security settings. -</constant> - <constant name="not found" value="404" class="soft error"> - The client attempted to work with a server entity that does not exist. -</constant> - <constant name="resource locked" value="405" class="soft error"> - The client attempted to work with a server entity to which it has - no access because another client is working with it. -</constant> - <constant name="frame error" value="501" class="hard error"> - The client sent a malformed frame that the server could not decode. - This strongly implies a programming error in the client. -</constant> - <constant name="syntax error" value="502" class="hard error"> - The client sent a frame that contained illegal values for one or more - fields. This strongly implies a programming error in the client. -</constant> - <constant name="command invalid" value="503" class="hard error"> - 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. -</constant> - <constant name="channel error" value="504" class="hard error"> - The client attempted to work with a channel that had not been - correctly opened. This most likely indicates a fault in the client - layer. -</constant> - <constant name="resource error" value="506" class="hard error"> - 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. -</constant> - <constant name="not allowed" value="530" class="hard error"> - 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. -</constant> - <constant name="not implemented" value="540" class="hard error"> - The client tried to use functionality that is not implemented in the - server. -</constant> - <constant name="internal error" value="541" class="hard error"> - 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. -</constant> - <!-- -====================================================== -== DOMAIN TYPES -====================================================== ---> - <domain name="access ticket" type="short"> - 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 - channel where they were created, and expire when the channel closes. - </doc> - <assert check="ne" value="0"/> - </domain> - <domain name="class id" type="short"/> - <domain name="consumer tag" type="shortstr"> - consumer tag - <doc> - Identifier for the consumer, valid within the current connection. - </doc> - <rule implement="MUST"> - The consumer tag is valid only within the channel from which the - consumer was created. I.e. a client MUST NOT create a consumer in - one channel and then use it in another. - </rule> - </domain> - <domain name="delivery tag" type="longlong"> - server-assigned delivery tag - <doc> - The server-assigned and channel-specific delivery tag - </doc> - <rule implement="MUST"> - The delivery tag is valid only within the channel from which the - message was received. I.e. a client MUST NOT receive a message on - one channel and then acknowledge it on another. - </rule> - <rule implement="MUST"> - The server MUST NOT use a zero value for delivery tags. Zero is - reserved for client use, meaning "all messages so far received". - </rule> - </domain> - <domain name="exchange name" type="shortstr"> - 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="length" value="127"/> - </domain> - <domain name="known hosts" type="shortstr"> -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. -</doc> - <rule implement="MAY"> -The server MAY leave this field empty if it knows of no other -hosts than itself. -</rule> - </domain> - <domain name="method id" type="short"/> - <domain name="no ack" type="bit"> - no acknowledgement needed - <doc> - If this field is set the server does not expect acknowledgments - 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"> - do not deliver own messages - <doc> - If the no-local field is set the server will not send messages to - the client 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> - <rule implement="SHOULD"> -The properties SHOULD contain these fields: -"product", giving the name of the peer product, "version", giving -the name of the peer version, "platform", giving the name of the -operating system, "copyright", if appropriate, and "information", -giving other general information. -</rule> - </domain> - <domain name="queue name" type="shortstr"> - queue name - <doc> - The queue name identifies the queue within the vhost. Queue - names may consist of any mixture of digits, letters, and - underscores. - </doc> - <assert check="length" value="127"/> - </domain> - <domain name="redelivered" type="bit"> - message is being redelivered - <doc> - This indicates that the message has been previously delivered to - this or another client. - </doc> - <rule implement="SHOULD"> - 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. - </rule> - <rule implement="MUST"> - The client MUST NOT rely on the redelivered field but MUST 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 channels. - </rule> - </domain> - <domain name="reply code" type="short"> -reply code from server -<doc> - The reply code. The AMQ reply codes are defined in AMQ RFC 011. -</doc> - <assert check="notnull"/> - </domain> - <domain name="reply text" type="shortstr"> -localised reply text -<doc> - The localised reply text. This text can be logged as an aid to - resolving issues. -</doc> - <assert check="notnull"/> - </domain> - <class name="connection" handler="connection" index="10"> - <!-- -====================================================== -== CONNECTION -====================================================== ---> - 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 name="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 name="start" synchronous="1" index="10"> - 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 implement="MUST"> - If the client cannot handle the protocol version suggested by the - server it MUST close the socket connection. - </rule> - <rule implement="MUST"> - The server MUST provide a protocol version that is lower than or - equal to that requested by the client in the protocol header. If - the server cannot support the specified protocol it MUST NOT send - this method, but MUST close the socket connection. - </rule> - <chassis name="client" implement="MUST"/> - <response name="start-ok"/> - <field name="version major" type="octet"> - protocol major version - <doc> - The protocol major version that the server agrees to use, which - cannot be higher than the client's major version. - </doc> - </field> - <field name="version minor" type="octet"> - protocol major version - <doc> - The protocol minor version that the server agrees to use, which - cannot be higher than the client's minor version. - </doc> - </field> - <field name="server properties" domain="peer properties"> - server properties - </field> - <field name="mechanisms" type="longstr"> - available security mechanisms - <doc> - A list of the security mechanisms that the server supports, delimited - by spaces. Currently ASL supports these mechanisms: PLAIN. - </doc> - <see name="security mechanisms"/> - <assert check="notnull"/> - </field> - <field name="locales" type="longstr"> - 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 implement="MUST"> - All servers MUST support at least the en_US locale. - </rule> - <assert check="notnull"/> - </field> - </method> - <method name="start-ok" synchronous="1" index="11"> - select security mechanism and locale - <doc> - This method selects a SASL security mechanism. ASL uses SASL - (RFC2222) to negotiate authentication and encryption. - </doc> - <chassis name="server" implement="MUST"/> - <field name="client properties" domain="peer properties"> - client properties - </field> - <field name="mechanism" type="shortstr"> - selected security mechanism - <doc> - A single security mechanisms selected by the client, which must be - one of those specified by the server. - </doc> - <rule implement="SHOULD"> - The client SHOULD authenticate using the highest-level security - profile it can handle from the list provided by the server. - </rule> - <rule implement="MUST"> - The mechanism field MUST contain one of the security mechanisms - proposed by the server in the Start method. If it doesn't, the - server MUST close the socket. - </rule> - <assert check="notnull"/> - </field> - <field name="response" type="longstr"> - 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. For the - PLAIN security mechanism this is defined as a field table holding - two fields, LOGIN and PASSWORD. - </doc> - <assert check="notnull"/> - </field> - <field name="locale" type="shortstr"> - selected message locale - <doc> - A single message local selected by the client, which must be one - of those specified by the server. - </doc> - <assert check="notnull"/> - </field> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="secure" synchronous="1" index="20"> - 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" type="longstr"> - security challenge data - <doc> - Challenge information, a block of opaque binary data passed to - the security mechanism. - </doc> - <see name="security mechanisms"/> - </field> - </method> - <method name="secure-ok" synchronous="1" index="21"> - 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" type="longstr"> - 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 name="tune" synchronous="1" index="30"> - 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" type="short"> - 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" type="long"> - 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 implement="MUST"> - Until the frame-max has been negotiated, both peers MUST accept - frames of up to 4096 octets large. The minimum non-zero value for - the frame-max field is 4096. - </rule> - </field> - <field name="heartbeat" type="short"> - desired heartbeat delay - <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 name="tune-ok" synchronous="1" index="31"> - 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" type="short"> - negotiated maximum channels - <doc> - The maximum total number of channels that the client will use - per connection. May not be higher than the value specified by - the server. - </doc> - <rule implement="MAY"> - The server MAY ignore the channel-max value or MAY use it for - tuning its resource allocation. - </rule> - <assert check="notnull"/> - <assert check="le" method="tune" field="channel max"/> - </field> - <field name="frame max" type="long"> - 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 implement="MUST"> - Until the frame-max has been negotiated, both peers must accept - frames of up to 4096 octets large. The minimum non-zero value for - the frame-max field is 4096. - </rule> - </field> - <field name="heartbeat" type="short"> - 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 name="open" synchronous="1" index="40"> - 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. - </doc> - <rule implement="MUST"> - The client MUST open the context before doing any work on the - connection. - </rule> - <chassis name="server" implement="MUST"/> - <response name="open-ok"/> - <response name="redirect"/> - <field name="virtual host" domain="path"> - virtual host name - <assert check="regexp" value="^[a-zA-Z0-9/-_]+$"/> - <doc> - The name of the virtual host to work with. - </doc> - <rule implement="MUST"> - 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. - </rule> - <rule implement="SHOULD"> - The server SHOULD verify that the client has permission to access - the specified virtual host. - </rule> - <rule implement="MAY"> - The server MAY configure arbitrary limits per virtual host, such - as the number of each type of entity that may be used, per - connection and/or in total. - </rule> - </field> - <field name="capabilities" type="shortstr"> - required capabilities - <doc> - The client may specify a number of 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" type="bit"> - insist on connecting to server - <doc> - In a configuration with multiple load-sharing 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 implement="SHOULD"> - When the client uses the insist option, the server SHOULD accept - the client connection unless it is technically unable to do so. - </rule> - </field> - </method> - <method name="open-ok" synchronous="1" index="41"> - signal that the 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 name="redirect" synchronous="1" index="50"> - asks the client to use a different server - <doc> - This method redirects the client to another server, based on the - requested virtual host and/or capabilities. - </doc> - <rule implement="SHOULD"> - 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. - </rule> - <chassis name="client" implement="MAY"/> - <field name="host" type="shortstr"> - 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 name="close" synchronous="1" index="60"> - 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> - <rule implement="MUST"> - After sending this method any received method except the Close-OK - method MUST be discarded. - </rule> - <rule implement="MAY"> - The peer sending this method MAY use a counter or timeout to - detect failure of the other peer to respond correctly with - the Close-OK method. - </rule> - <rule implement="MUST"> - When a server receives the Close method from a client it MUST - delete all server-side resources associated with the client's - context. A client CANNOT reconnect to a context after sending - or receiving a Close method. - </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"> - 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="class id"> - failing method ID - <doc> - When the close is provoked by a method exception, this is the - ID of the method. - </doc> - </field> - </method> - <method name="close-ok" synchronous="1" index="61"> - 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 implement="SHOULD"> - A peer that detects a socket closure without having received a - Close-Ok handshake method SHOULD log the error. - </rule> - <chassis name="client" implement="MUST"/> - <chassis name="server" implement="MUST"/> - </method> - </class> - <class name="channel" handler="channel" index="20"> - <!-- -====================================================== -== CHANNEL -====================================================== ---> - work with channels -<doc> - The channel class provides methods for a client to establish a virtual - connection - a channel - to a server and for both peers to operate the - virtual connection thereafter. -</doc> - <doc name="grammar"> - channel = open-channel *use-channel close-channel - open-channel = C:OPEN S:OPEN-OK - use-channel = C:FLOW S:FLOW-OK - / S:FLOW C:FLOW-OK - / S:ALERT - / functional-class - close-channel = C:CLOSE S:CLOSE-OK - / S:CLOSE C:CLOSE-OK -</doc> - <chassis name="server" implement="MUST"/> - <chassis name="client" implement="MUST"/> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="open" synchronous="1" index="10"> - open a channel for use - <doc> - This method opens a virtual connection (a channel). - </doc> - <rule implement="MUST"> - This method MUST NOT be called when the channel is already open. - </rule> - <chassis name="server" implement="MUST"/> - <response name="open-ok"/> - <field name="out of band" type="shortstr"> - out-of-band settings - <doc> - Configures out-of-band transfers on this channel. The syntax and - meaning of this field will be formally defined at a later date. - </doc> - <assert check="null"/> - </field> - </method> - <method name="open-ok" synchronous="1" index="11"> - signal that the channel is ready - <doc> - This method signals to the client that the channel is ready for use. - </doc> - <chassis name="client" implement="MUST"/> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="flow" synchronous="1" index="20"> - 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 oveflowing 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 request to - stop sending content should finish sending the current content, if - any, and then wait until it receives a Flow restart method. - </doc> - <rule implement="MAY"> - When a new channel is opened, it is active. Some applications - assume that channels are inactive until started. To emulate this - behaviour a client MAY open the channel, then pause it. - </rule> - <rule implement="SHOULD"> - When sending content data in multiple frames, a peer SHOULD monitor - the channel for incoming methods and respond to a Channel.Flow as - rapidly as possible. - </rule> - <rule implement="MAY"> - A peer MAY use the Channel.Flow method to throttle incoming content - data for internal reasons, for example, when exchangeing data over a - slower connection. - </rule> - <rule implement="MAY"> - The peer that requests a Channel.Flow method MAY disconnect and/or - ban a peer that does not respect the request. - </rule> - <chassis name="server" implement="MUST"/> - <chassis name="client" implement="MUST"/> - <response name="flow-ok"/> - <field name="active" type="bit"> - start/stop content frames - <doc> - If 1, the peer starts sending content frames. If 0, the peer - stops sending content frames. - </doc> - </field> - </method> - <method name="flow-ok" index="21"> - 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" type="bit"> - current flow setting - <doc> - Confirms the setting of the processed flow method: 1 means the - peer will start sending or continue to send content frames; 0 - means it will not. - </doc> - </field> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="alert" index="30"> - send a non-fatal warning message - <doc> - This method allows the server to send a non-fatal warning to the - client. This is used for methods that are normally asynchronous - and thus do not have confirmations, and for which the server may - detect errors that need to be reported. Fatal errors are handled - as channel or connection exceptions; non-fatal errors are sent - through this method. - </doc> - <chassis name="client" implement="MUST"/> - <field name="reply code" domain="reply code"/> - <field name="reply text" domain="reply text"/> - <field name="details" type="table"> - detailed information for warning - <doc> - A set of fields that provide more information about the - problem. The meaning of these fields are defined on a - per-reply-code basis (TO BE DEFINED). - </doc> - </field> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="close" synchronous="1" index="40"> - request a channel close - <doc> - This method indicates that the sender wants to close the channel. - 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> - <rule implement="MUST"> - After sending this method any received method except - Channel.Close-OK MUST be discarded. - </rule> - <rule implement="MAY"> - The peer sending this method MAY use a counter or timeout to detect - failure of the other peer to respond correctly with Channel.Close-OK.. - </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"> - 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"> - failing method ID - <doc> - When the close is provoked by a method exception, this is the - ID of the method. - </doc> - </field> - </method> - <method name="close-ok" synchronous="1" index="41"> - confirm a channel close - <doc> - This method confirms a Channel.Close method and tells the recipient - that it is safe to release resources for the channel and close the - socket. - </doc> - <rule implement="SHOULD"> - A peer that detects a socket closure without having received a - Channel.Close-Ok handshake method SHOULD log the error. - </rule> - <chassis name="client" implement="MUST"/> - <chassis name="server" implement="MUST"/> - </method> - </class> - <class name="access" handler="connection" index="30"> - <!-- -====================================================== -== ACCESS CONTROL -====================================================== ---> - 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 name="grammar"> - access = C:REQUEST S:REQUEST-OK -</doc> - <chassis name="server" implement="MUST"/> - <chassis name="client" implement="MUST"/> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="request" synchronous="1" index="10"> - 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-channel resource. - </doc> - <rule implement="MUST"> - The realm name MUST start with either "/data" (for application - resources) or "/admin" (for server administration resources). - If the realm starts with any other path, the server MUST raise - a connection exception with reply code 403 (access refused). - </rule> - <rule implement="MUST"> - The server MUST implement the /data realm and MAY implement the - /admin realm. The mapping of resources to realms is not - defined in the protocol - this is a server-side configuration - issue. - </rule> - <chassis name="server" implement="MUST"/> - <response name="request-ok"/> - <field name="realm" domain="path"> - name of requested realm - <rule implement="MUST"> - If the specified realm is not known to the server, the server - must raise a channel exception with reply code 402 (invalid - path). - </rule> - </field> - <field name="exclusive" type="bit"> - request exclusive access - <doc> - Request exclusive access to the realm. If the server cannot grant - this - because there are other active tickets for the realm - it - raises a channel exception. - </doc> - </field> - <field name="passive" type="bit"> - 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" type="bit"> - request active access - <doc> - Request message active access to the specified access realm. - Acvtive access lets a client get create and delete resources in - the realm. - </doc> - </field> - <field name="write" type="bit"> - 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" type="bit"> - 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 name="request-ok" synchronous="1" index="11"> - grant access to server resources - <doc> - This method provides the client with an access ticket. The access - ticket is valid within the current channel and for the lifespan of - the channel. - </doc> - <rule implement="MUST"> - The client MUST NOT use access tickets except within the same - channel as originally granted. - </rule> - <rule implement="MUST"> - The server MUST isolate access tickets per channel and treat an - attempt by a client to mix these as a connection exception. - </rule> - <chassis name="client" implement="MUST"/> - <field name="ticket" domain="access ticket"/> - </method> - </class> - <class name="exchange" handler="channel" index="40"> - <!-- -====================================================== -== EXCHANGES (or "routers", if you prefer) -== (Or matchers, plugins, extensions, agents,... Routing is just one of -== the many fun things an exchange can do.) -====================================================== ---> - work with exchanges -<doc> - Exchanges match and distribute messages across queues. Exchanges can be - configured in the server or created at runtime. -</doc> - <doc name="grammar"> - exchange = C:DECLARE S:DECLARE-OK - / C:DELETE S:DELETE-OK -</doc> - <chassis name="server" implement="MUST"/> - <chassis name="client" implement="MUST"/> - <rule implement="MUST"> - <test>amq_exchange_19</test> - The server MUST implement the direct and fanout exchange types, and - predeclare the corresponding exchanges named amq.direct and amq.fanout - in each virtual host. The server MUST also predeclare a direct - exchange to act as the default exchange for content Publish methods - and for default queue bindings. -</rule> - <rule implement="SHOULD"> - <test>amq_exchange_20</test> - The server SHOULD implement the topic exchange type, and predeclare - the corresponding exchange named amq.topic in each virtual host. -</rule> - <rule implement="MAY"> - <test>amq_exchange_21</test> - The server MAY implement the system exchange type, and predeclare the - corresponding exchanges named amq.system in each virtual host. If the - client attempts to bind a queue to the system exchange, the server - MUST raise a connection exception with reply code 507 (not allowed). -</rule> - <rule implement="MUST"> - <test>amq_exchange_22</test> - The default exchange MUST be defined as internal, and be inaccessible - to the client except by specifying an empty exchange name in a content - Publish method. That is, the server MUST NOT let clients make explicit - bindings to this exchange. -</rule> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="declare" synchronous="1" index="10"> - declare exchange, 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 implement="SHOULD"> - <test>amq_exchange_23</test> - The server SHOULD support a minimum of 16 exchanges per virtual host - and ideally, impose no limit except as defined by available resources. - </rule> - <chassis name="server" implement="MUST"/> - <response name="declare-ok"/> - <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 implement="MUST"> - 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. - </rule> - </field> - <field name="exchange" domain="exchange name"> - <rule implement="MUST"> - <test>amq_exchange_15</test> - Exchange names starting with "amq." are reserved for predeclared - and standardised exchanges. If the client attempts to create an - exchange starting with "amq.", the server MUST raise a channel - exception with reply code 403 (access refused). - </rule> - <assert check="regexp" value="^[a-zA-Z0-9-_.:]+$"/> - </field> - <field name="type" type="shortstr"> - 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 implement="MUST"> - <test>amq_exchange_16</test> - If the exchange already exists with a different type, the server - MUST raise a connection exception with a reply code 507 (not allowed). - </rule> - <rule implement="MUST"> - <test>amq_exchange_18</test> - If the server does not support the requested exchange type it MUST - raise a connection exception with a reply code 503 (command invalid). - </rule> - <assert check="regexp" value="^[a-zA-Z0-9-_.:]+$"/> - </field> - <field name="passive" type="bit"> - 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 implement="MUST"> - <test>amq_exchange_05</test> - If set, and the exchange does not already exist, the server MUST - raise a channel exception with reply code 404 (not found). - </rule> - </field> - <field name="durable" type="bit"> - 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 implement="MUST"> - <test>amq_exchange_24</test> - The server MUST support both durable and transient exchanges. - </rule> - <rule implement="MUST"> - The server MUST ignore the durable field if the exchange already - exists. - </rule> - </field> - <field name="auto delete" type="bit"> - auto-delete when unused - <doc> - If set, the exchange is deleted when all queues have finished - using it. - </doc> - <rule implement="SHOULD"> - <test>amq_exchange_02</test> - The server SHOULD allow for a reasonable delay between the point - when it determines that an exchange is not being used (or no longer - used), and the point when it deletes the exchange. At the least it - must allow a client to create an exchange and then bind a queue to - it, with a small but non-zero delay between these two actions. - </rule> - <rule implement="MUST"> - <test>amq_exchange_25</test> - The server MUST ignore the auto-delete field if the exchange already - exists. - </rule> - </field> - <field name="internal" type="bit"> - create internal exchange - <doc> - If set, the exchange may not be used directly by publishers, but - only when bound to other exchanges. Internal exchanges are used to - construct wiring that is not visible to applications. - </doc> - </field> - - <field name = "nowait" type = "bit"> - 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" type="table"> - 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 name="declare-ok" synchronous="1" index="11"> - confirms an exchange declaration - <doc> - This method confirms a Declare method and confirms the name of the - exchange, essential for automatically-named exchanges. - </doc> - <chassis name="client" implement="MUST"/> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="delete" synchronous="1" index="20"> - 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"/> - <response name="delete-ok"/> - <field name="ticket" domain="access ticket"> - <rule implement="MUST"> - The client MUST provide a valid access ticket giving "active" - access rights to the exchange's access realm. - </rule> - </field> - <field name="exchange" domain="exchange name"> - <rule implement="MUST"> - <test>amq_exchange_11</test> - The exchange MUST exist. Attempting to delete a non-existing exchange - causes a channel exception. - </rule> - <assert check="notnull"/> - </field> - <field name="if unused" type="bit"> - 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> - <rule implement="SHOULD"> - <test>amq_exchange_12</test> - If set, the server SHOULD delete the exchange but only if it has - no queue bindings. - </rule> - <rule implement="SHOULD"> - <test>amq_exchange_13</test> - If set, the server SHOULD raise a channel exception if the exchange is in - use. - </rule> - </field> - - <field name = "nowait" type = "bit"> - 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> - - </method> - <method name="delete-ok" synchronous="1" index="21"> - confirm deletion of an exchange - <doc> - This method confirms the deletion of an exchange. - </doc> - <chassis name="client" implement="MUST"/> - </method> - </class> - <class name="queue" handler="channel" index="50"> - <!-- -====================================================== -== QUEUES -====================================================== ---> - 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 name="grammar"> - queue = C:DECLARE S:DECLARE-OK - / C:BIND S:BIND-OK - / C:PURGE S:PURGE-OK - / C:DELETE S:DELETE-OK -</doc> - <chassis name="server" implement="MUST"/> - <chassis name="client" implement="MUST"/> - <rule implement="MUST"> - <test>amq_queue_33</test> - A server MUST allow any content class to be sent to any queue, in any - mix, and queue and delivery these content classes independently. Note - that all methods that fetch content off queues are specific to a given - content class. -</rule> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="declare" synchronous="1" index="10"> - 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 implement="MUST"> - <test>amq_queue_34</test> - The server MUST create a default binding for a newly-created queue - to the default exchange, which is an exchange of type 'direct'. - </rule> - <rule implement="SHOULD"> - <test>amq_queue_35</test> - The server SHOULD support a minimum of 256 queues per virtual host - and ideally, impose no limit except as defined by available resources. - </rule> - <chassis name="server" implement="MUST"/> - <response name="declare-ok"/> - <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> - <doc> - The client provides a valid access ticket giving "active" access - to the realm in which the queue exists or will be created, or - "passive" access if the if-exists flag is set. - </doc> - </field> - <field name="queue" domain="queue name"> - <rule implement="MAY"> - <test>amq_queue_10</test> - The queue name MAY be empty, in which case the server MUST create - a new queue with a unique generated name and return this to the - client in the Declare-Ok method. - </rule> - <rule implement="MUST"> - <test>amq_queue_32</test> - Queue names starting with "amq." are reserved for predeclared and - standardised server queues. If the queue name starts with "amq." - and the passive option is zero, the server MUST raise a connection - exception with reply code 403 (access refused). - </rule> - <assert check="regexp" value="^[a-zA-Z0-9-_.:]*$"/> - </field> - <field name="passive" type="bit"> - do not create queue - <doc> - If set, the server will not create the queue. The client can use - this to check whether a queue exists without modifying the server - state. - </doc> - <rule implement="MUST"> - <test>amq_queue_05</test> - If set, and the queue does not already exist, the server MUST - respond with a reply code 404 (not found) and raise a channel - exception. - </rule> - </field> - <field name="durable" type="bit"> - 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 implement="MUST"> - <test>amq_queue_03</test> - The server MUST recreate the durable queue after a restart. - </rule> - <rule implement="MUST"> - <test>amq_queue_36</test> - The server MUST support both durable and transient queues. - </rule> - <rule implement="MUST"> - <test>amq_queue_37</test> - The server MUST ignore the durable field if the queue already - exists. - </rule> - </field> - <field name="exclusive" type="bit"> - request an exclusive queue - <doc> - Exclusive queues may only be consumed from by the current connection. - Setting the 'exclusive' flag always implies 'auto-delete'. - </doc> - <rule implement="MUST"> - <test>amq_queue_38</test> - The server MUST support both exclusive (private) and non-exclusive - (shared) queues. - </rule> - <rule implement="MUST"> - <test>amq_queue_04</test> - The server MUST raise a channel exception if 'exclusive' is specified - and the queue already exists and is owned by a different connection. - </rule> - </field> - <field name="auto delete" type="bit"> - auto-delete queue when unused - <doc> - If set, the queue is deleted when all 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 implement="SHOULD"> - <test>amq_queue_02</test> - The server SHOULD allow for a reasonable delay between the point - when it determines that a queue is not being used (or no longer - used), and the point when it deletes the queue. At the least it - must allow a client to create a queue and then create a consumer - to read from it, with a small but non-zero delay between these - two actions. The server should equally allow for clients that may - be disconnected prematurely, and wish to re-consume from the same - queue without losing messages. We would recommend a configurable - timeout, with a suitable default value being one minute. - </rule> - <rule implement="MUST"> - <test>amq_queue_31</test> - The server MUST ignore the auto-delete field if the queue already - exists. - </rule> - </field> - <field name = "nowait" type = "bit"> - 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" type="table"> - 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 name="declare-ok" synchronous="1" index="11"> - confirms a queue definition - <doc> - This method confirms a Declare method and confirms the name of the - queue, essential for automatically-named queues. - </doc> - <chassis name="client" implement="MUST"/> - <field name="queue" domain="queue name"> - <doc> - Reports the name of the queue. If the server generated a queue - name, this field contains that name. - </doc> - <assert check="notnull"/> - </field> - <field name="message count" type="long"> - number of messages in queue - <doc> - Reports the number of messages in the queue, which will be zero - for newly-created queues. - </doc> - </field> - <field name="consumer count" type="long"> - number of consumers - <doc> - Reports the number of active consumers for the queue. Note that - consumers can suspend activity (Channel.Flow) in which case they - do not appear in this count. - </doc> - </field> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="bind" synchronous="1" index="20"> - 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 dest exchange - and subscription queues are bound to a dest_wild exchange. - </doc> - <rule implement="MUST"> - <test>amq_queue_25</test> - 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. - </rule> - <rule implement="MUST"> - <test>amq_queue_39</test> - If a bind fails, the server MUST raise a connection exception. - </rule> - <rule implement="MUST"> - <test>amq_queue_12</test> - The server MUST NOT allow a durable queue to bind to a transient - exchange. If the client attempts this the server MUST raise a - channel exception. - </rule> - <rule implement="SHOULD"> - <test>amq_queue_13</test> - Bindings for durable queues are automatically durable and the - server SHOULD restore such bindings after a server restart. - </rule> - <rule implement="MUST"> - <test>amq_queue_17</test> - If the client attempts to an exchange that was declared as internal, - the server MUST raise a connection exception with reply code 530 - (not allowed). - </rule> - <rule implement="SHOULD"> - <test>amq_queue_40</test> - The server SHOULD support at least 4 bindings per queue, and - ideally, impose no limit except as defined by available resources. - </rule> - <chassis name="server" implement="MUST"/> - <response name="bind-ok"/> - <field name="ticket" domain="access ticket"> - <doc> - The client provides a valid access ticket giving "active" - access rights to the queue's access realm. - </doc> - </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 channel, which is - the last declared queue. - </doc> - <doc name = "rule"> - 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> - <doc name = "rule" test = "amq_queue_26"> - If the queue does not exist the server MUST raise a channel exception - with reply code 404 (not found). - </doc> - </field> - - <field name="exchange" domain="exchange name"> - The name of the exchange to bind to. - <rule implement="MUST"> - <test>amq_queue_14</test> - If the exchange does not exist the server MUST raise a channel - exception with reply code 404 (not found). - </rule> - </field> - <field name="routing key" type="shortstr"> - 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 routing key is empty and the queue - name is empty, the routing key will be the current queue for the - channel, which is the last declared queue. - </doc> - </field> - - <field name = "nowait" type = "bit"> - 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" type="table"> - 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 name="bind-ok" synchronous="1" index="21"> - confirm bind successful - <doc> - This method confirms that the bind was successful. - </doc> - <chassis name="client" implement="MUST"/> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="purge" synchronous="1" index="30"> - 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 implement="MUST"> - <test>amq_queue_15</test> - A call to purge MUST result in an empty queue. - </rule> - <rule implement="MUST"> - <test>amq_queue_41</test> - On transacted channels the server MUST not purge messages that have - already been sent to a client but not yet acknowledged. - </rule> - <rule implement="MAY"> - <test>amq_queue_42</test> - 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. - </rule> - <chassis name="server" implement="MUST"/> - <response name="purge-ok"/> - <field name="ticket" domain="access ticket"> - <doc> - The access ticket must be for the access realm that holds the - queue. - </doc> - <rule implement="MUST"> - 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. - </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 channel, which is - the last declared queue. - </doc> - <doc name = "rule"> - 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> - <doc name = "rule" test = "amq_queue_16"> - The queue must exist. Attempting to purge a non-existing queue - causes a channel exception. - </doc> - </field> - - <field name = "nowait" type = "bit"> - 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> - </method> - <method name="purge-ok" synchronous="1" index="31"> - confirms a queue purge - <doc> - This method confirms the purge of a queue. - </doc> - <chassis name="client" implement="MUST"/> - <field name="message count" type="long"> - number of messages purged - <doc> - Reports the number of messages purged. - </doc> - </field> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="delete" synchronous="1" index="40"> - 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 implement="SHOULD"> - <test>amq_queue_43</test> - 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. - </rule> - <chassis name="server" implement="MUST"/> - <response name="delete-ok"/> - <field name="ticket" domain="access ticket"> - <doc> - The client provides a valid access ticket giving "active" - access rights to the queue's access realm. - </doc> - </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 channel, which is the - last declared queue. - </doc> - <doc name = "rule"> - 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> - <doc name = "rule" test = "amq_queue_21"> - The queue must exist. Attempting to delete a non-existing queue - causes a channel exception. - </doc> - </field> - - <field name="if unused" type="bit"> - 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 implement="MUST"> - <test>amq_queue_29</test> - <test>amq_queue_30</test> - The server MUST respect the if-unused flag when deleting a queue. - </rule> - </field> - <field name="if empty" type="bit"> - delete only if empty - <test>amq_queue_27</test> - <doc> - If set, the server will only delete the queue if it has no - messages. If the queue is not empty the server raises a channel - exception. - </doc> - </field> - <field name = "nowait" type = "bit"> - 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> - </method> - - <method name="delete-ok" synchronous="1" index="41"> - confirm deletion of a queue - <doc> - This method confirms the deletion of a queue. - </doc> - <chassis name="client" implement="MUST"/> - <field name="message count" type="long"> - number of messages purged - <doc> - Reports the number of messages purged. - </doc> - </field> - </method> - </class> - <class name="basic" handler="channel" index="60"> - <!-- -====================================================== -== BASIC MIDDLEWARE -====================================================== ---> - work with basic content -<doc> - The Basic class provides methods that support an industry-standard - messaging model. -</doc> - -<doc name = "grammar"> - basic = C:QOS S:QOS-OK - / C:CONSUME S:CONSUME-OK - / C:CANCEL S:CANCEL-OK - / C:PUBLISH content - / S:RETURN content - / S:DELIVER content - / C:GET ( S:GET-OK content / S:GET-EMPTY ) - / C:ACK - / C:REJECT -</doc> - -<chassis name = "server" implement = "MUST" /> -<chassis name = "client" implement = "MAY" /> - -<doc name = "rule" test = "amq_basic_08"> - 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 name = "rule" test = "amq_basic_09"> - The server MUST NOT discard a persistent basic message in case of a - queue overflow. The server MAY use the Channel.Flow method to slow - or stop a basic message publisher when necessary. -</doc> -<doc name = "rule" test = "amq_basic_10"> - The server MAY overflow non-persistent basic messages to persistent - storage and MAY discard or dead-letter non-persistent basic messages - on a priority basis if the queue size exceeds some configured limit. -</doc> -<doc name = "rule" test = "amq_basic_11"> - 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. The server MAY implement up to 10 priority levels. -</doc> -<doc name = "rule" test = "amq_basic_12"> - The server MUST deliver messages of the same priority in order - irrespective of their individual persistence. -</doc> -<doc name = "rule" test = "amq_basic_13"> - The server MUST support both automatic and explicit acknowledgements - on Basic content. -</doc> - -<!-- These are the properties for a Basic content --> - -<field name = "content type" type = "shortstr"> - MIME content type -</field> -<field name = "content encoding" type = "shortstr"> - MIME content encoding -</field> -<field name = "headers" type = "table"> - Message header field table -</field> -<field name = "delivery mode" type = "octet"> - Non-persistent (1) or persistent (2) -</field> -<field name = "priority" type = "octet"> - The message priority, 0 to 9 -</field> -<field name = "correlation id" type = "shortstr"> - The application correlation identifier -</field> -<field name = "reply to" type = "shortstr"> - The destination to reply to -</field> -<field name = "expiration" type = "shortstr"> - Message expiration specification -</field> -<field name = "message id" type = "shortstr"> - The application message identifier -</field> -<field name = "timestamp" type = "timestamp"> - The message timestamp -</field> -<field name = "type" type = "shortstr"> - The message type name -</field> -<field name = "user id" type = "shortstr"> - The creating user id -</field> -<field name = "app id" type = "shortstr"> - The creating application id -</field> -<field name = "cluster id" type = "shortstr"> - Intra-cluster routing identifier -</field> - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "qos" synchronous = "1" index = "10"> - specify quality of service - <doc> - This method requests a specific quality of service. The QoS can - be specified for the current channel or for all channels 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" type = "long"> - 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 - down the channel. 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> - <doc name = "rule" test = "amq_basic_17"> - 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> - </field> - - <field name = "prefetch count" type = "short"> - 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 channel and connection level) allow it. - The prefetch-count is ignored if the no-ack option is set. - </doc> - <doc name = "rule" test = "amq_basic_18"> - The server MAY send less data in advance than allowed by the - client's specified prefetch windows but it MUST NOT send more. - </doc> - </field> - - <field name = "global" type = "bit"> - apply to entire connection - <doc> - By default the QoS settings apply to the current channel only. If - this field is set, they are applied to the entire connection. - </doc> - </field> -</method> - -<method name = "qos-ok" synchronous = "1" index = "11"> - 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 name = "consume" synchronous = "1" index = "20"> - 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 channel they were created on, or until the - client cancels them. - </doc> - <doc name = "rule" test = "amq_basic_01"> - 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> - <chassis name = "server" implement = "MUST" /> - <response name = "consume-ok" /> - - <field name = "ticket" domain = "access ticket"> - <doc name = "rule"> - The client MUST provide a valid access ticket giving "read" access - rights to the realm for the queue. - </doc> - </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 channel, which is the - last declared queue. - </doc> - <doc name = "rule"> - 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> - </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> - <doc name = "rule" test = "todo"> - 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> - </field> - - <field name = "no local" domain = "no local" /> - - <field name = "no ack" domain = "no ack" /> - - <field name = "exclusive" type = "bit"> - request exclusive access - <doc> - Request exclusive consumer access, meaning only this consumer can - access the queue. - </doc> - <doc name = "rule" test = "amq_basic_02"> - 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 403 (access refused). - </doc> - </field> - - <field name = "nowait" type = "bit"> - 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> -</method> - -<method name = "consume-ok" synchronous = "1" index = "21"> - confirm a new consumer - <doc> - 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 name = "cancel" synchronous = "1" index = "30"> - end a queue consumer - <doc test = "amq_basic_04"> - 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 - abitrary number of messages in between sending the cancel method - and receiving the cancel-ok reply. - </doc> - <doc name = "rule" test = "todo"> - If the queue no longer exists when the client sends a cancel command, - or the consumer has been cancelled for other reasons, this command - has no effect. - </doc> - <chassis name = "server" implement = "MUST" /> - <response name = "cancel-ok" /> - - <field name = "consumer tag" domain = "consumer tag" /> - - <field name = "nowait" type = "bit"> - 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> -</method> - -<method name = "cancel-ok" synchronous = "1" index = "31"> - confirm a cancelled consumer - <doc> - This method confirms that the cancellation was completed. - </doc> - <chassis name = "client" implement = "MUST" /> - - <field name = "consumer tag" domain = "consumer tag" /> -</method> - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "publish" content = "1" index = "40"> - 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 when the transaction, if any, - is committed. - </doc> - <chassis name = "server" implement = "MUST" /> - - <field name = "ticket" domain = "access ticket"> - <doc name = "rule"> - The client MUST provide a valid access ticket giving "write" - access rights to the access realm for the exchange. - </doc> - </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> - <doc name = "rule" test = "amq_basic_06"> - The server MUST accept a blank exchange name to mean the default - exchange. - </doc> - <doc name = "rule" test = "amq_basic_14"> - If the exchange was declared as an internal exchange, the server - MUST raise a channel exception with a reply code 403 (access - refused). - </doc> - <doc name = "rule" test = "amq_basic_15"> - The exchange MAY refuse basic content in which case it MUST raise - a channel exception with reply code 540 (not implemented). - </doc> - </field> - - <field name = "routing key" type = "shortstr"> - 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" type = "bit"> - 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> - <doc name = "rule" test = "amq_basic_07"> - The server SHOULD implement the mandatory flag. - </doc> - </field> - - <field name = "immediate" type = "bit"> - 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> - <doc name = "rule" test = "amq_basic_16"> - The server SHOULD implement the immediate flag. - </doc> - </field> -</method> - -<method name = "return" content = "1" index = "50"> - 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" type = "shortstr"> - Message routing key - <doc> - Specifies the routing key name specified when the message was - published. - </doc> - </field> -</method> - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "deliver" content = "1" index = "60"> - 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> - <doc name = "rule" test = "amq_basic_19"> - 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> - <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" type = "shortstr"> - Message routing key - <doc> - Specifies the routing key name specified when the message was - published. - </doc> - </field> -</method> - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "get" synchronous = "1" index = "70"> - 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> - <response name = "get-ok" /> - <response name = "get-empty" /> - <chassis name = "server" implement = "MUST" /> - - <field name = "ticket" domain = "access ticket"> - <doc name = "rule"> - The client MUST provide a valid access ticket giving "read" - access rights to the realm for the queue. - </doc> - </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 channel, which is the - last declared queue. - </doc> - <doc name = "rule"> - 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> - </field> - - <field name = "no ack" domain = "no ack" /> -</method> - -<method name = "get-ok" synchronous = "1" content = "1" index = "71"> - provide client with a message - <doc> - 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" type = "shortstr"> - Message routing key - <doc> - Specifies the routing key name specified when the message was - published. - </doc> - </field> - - <field name = "message count" type = "long" > - 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 name = "get-empty" synchronous = "1" index = "72"> - indicate no messages available - <doc> - This method tells the client that the queue has no messages - available for the client. - </doc> - <chassis name = "client" implement = "MAY" /> - - <field name = "cluster id" type = "shortstr"> - Cluster id - <doc> - For use by cluster applications, should not be used by - client applications. - </doc> - </field> -</method> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "ack" index = "80"> - acknowledge one or more messages - <doc> - 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" type = "bit"> - 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 mesages. - </doc> - <doc name = "rule" test = "amq_basic_20"> - 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> - </field> -</method> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "reject" index = "90"> - reject an incoming message - <doc> - 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> - <doc name = "rule" test = "amq_basic_21"> - The server SHOULD be capable of accepting and process 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> - <doc name = "rule" test = "amq_basic_22"> - The server SHOULD interpret this method as meaning that the client - is unable to process the message at this time. - </doc> - <doc name = "rule"> - 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> - <chassis name = "server" implement = "MUST" /> - - <field name = "delivery tag" domain = "delivery tag" /> - - <field name = "requeue" type = "bit"> - 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> - <doc name = "rule" test = "amq_basic_23"> - The server MUST NOT deliver the message to the same client within - the context of the current channel. 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> - </field> -</method> - -<method name = "recover" index = "100"> - redeliver unacknowledged messages - <doc> - This method asks the broker to redeliver all unacknowledged messages on a - specified channel. Zero or more messages may be redelivered. This method - is only allowed on non-transacted channels. - </doc> - <chassis name = "server" implement = "MUST" /> - - <field name = "requeue" type = "bit"> - 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> - <doc name="rule"> - The server MUST set the redelivered flag on all messages that are resent. - </doc> - <doc name="rule"> - The server MUST raise a channel exception if this is called on a - transacted channel. - </doc> -</method> - -</class> - - - <class name="file" handler="channel" index="70"> - <!-- -====================================================== -== FILE TRANSFER -====================================================== ---> - 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 channel 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 name = "grammar"> - file = C:QOS S:QOS-OK - / C:CONSUME S:CONSUME-OK - / C:CANCEL S:CANCEL-OK - / 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> - -<chassis name = "server" implement = "MAY" /> -<chassis name = "client" implement = "MAY" /> - -<doc name = "rule"> - The server MUST make a best-effort to hold file messages on a - reliable storage mechanism. -</doc> -<doc name = "rule"> - The server MUST NOT discard a file message in case of a queue - overflow. The server MUST use the Channel.Flow method to slow or stop - a file message publisher when necessary. -</doc> -<doc name = "rule"> - 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> -<doc name = "rule"> - The server MUST support both automatic and explicit acknowledgements - on file content. -</doc> - -<!-- These are the properties for a File content --> - -<field name = "content type" type = "shortstr"> - MIME content type -</field> -<field name = "content encoding" type = "shortstr"> - MIME content encoding -</field> -<field name = "headers" type = "table"> - Message header field table -</field> -<field name = "priority" type = "octet"> - The message priority, 0 to 9 -</field> -<field name = "reply to" type = "shortstr"> - The destination to reply to -</field> -<field name = "message id" type = "shortstr"> - The application message identifier -</field> -<field name = "filename" type = "shortstr"> - The message filename -</field> -<field name = "timestamp" type = "timestamp"> - The message timestamp -</field> -<field name = "cluster id" type = "shortstr"> - Intra-cluster routing identifier -</field> - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "qos" synchronous = "1" index = "10"> - specify quality of service - <doc> - This method requests a specific quality of service. The QoS can - be specified for the current channel or for all channels 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" type = "long"> - 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 - down the channel. 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" type = "short"> - 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 channel and connection level) allow it. - The prefetch-count is ignored if the no-ack option is set. - </doc> - <doc name = "rule"> - The server MAY send less data in advance than allowed by the - client's specified prefetch windows but it MUST NOT send more. - </doc> - </field> - - <field name = "global" type = "bit"> - apply to entire connection - <doc> - By default the QoS settings apply to the current channel only. If - this field is set, they are applied to the entire connection. - </doc> - </field> -</method> - -<method name = "qos-ok" synchronous = "1" index = "11"> - 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 name = "consume" synchronous = "1" index = "20"> - 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 channel they were created on, or until the - client cancels them. - </doc> - <doc name = "rule"> - 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> - <chassis name = "server" implement = "MUST" /> - <response name = "consume-ok" /> - - <field name = "ticket" domain = "access ticket"> - <doc name = "rule"> - The client MUST provide a valid access ticket giving "read" access - rights to the realm for the queue. - </doc> - </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 channel, which is the - last declared queue. - </doc> - <doc name = "rule"> - 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> - </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> - <doc name = "rule" test = "todo"> - 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> - </field> - - <field name = "no local" domain = "no local" /> - - <field name = "no ack" domain = "no ack" /> - - <field name = "exclusive" type = "bit"> - request exclusive access - <doc> - Request exclusive consumer access, meaning only this consumer can - access the queue. - </doc> - <doc name = "rule" test = "amq_file_00"> - 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> - </field> - - <field name = "nowait" type = "bit"> - 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> -</method> - -<method name = "consume-ok" synchronous = "1" index = "21"> - 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 name = "cancel" synchronous = "1" index = "30"> - 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" /> - <response name = "cancel-ok" /> - - <field name = "consumer tag" domain = "consumer tag" /> - - <field name = "nowait" type = "bit"> - 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> -</method> - -<method name = "cancel-ok" synchronous = "1" index = "31"> - confirm a cancelled consumer - <doc> - This method confirms that the cancellation was completed. - </doc> - <chassis name = "client" implement = "MUST" /> - - <field name = "consumer tag" domain = "consumer tag" /> -</method> - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "open" synchronous = "1" index = "40"> - 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> - <response name = "open-ok" /> - <chassis name = "server" implement = "MUST" /> - <chassis name = "client" implement = "MUST" /> - - <field name = "identifier" type = "shortstr"> - 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" type = "longlong"> - 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> - <doc name = "rule"> - The sender MUST accurately fill the content-size field. - Zero-length content is permitted. - </doc> - </field> -</method> - -<method name = "open-ok" synchronous = "1" index = "41"> - 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> - <response name = "stage" /> - <chassis name = "server" implement = "MUST" /> - <chassis name = "client" implement = "MUST" /> - - <field name = "staged size" type = "longlong"> - already staged amount - <doc> - The amount of previously-staged content in octets. For a new - message this will be zero. - </doc> - <doc name = "rule"> - The sender MUST start sending data from this octet offset in the - message, counting from zero. - </doc> - <doc name = "rule"> - 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> - </field> -</method> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "stage" content = "1" index = "50"> - 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 name = "publish" index = "60"> - 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"> - <doc name = "rule"> - The client MUST provide a valid access ticket giving "write" - access rights to the access realm for the exchange. - </doc> - </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> - <doc name = "rule"> - The server MUST accept a blank exchange name to mean the default - exchange. - </doc> - <doc name = "rule"> - 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> - <doc name = "rule"> - 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> - </field> - - <field name = "routing key" type = "shortstr"> - 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" type = "bit"> - 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> - <doc name = "rule" test = "amq_file_00"> - The server SHOULD implement the mandatory flag. - </doc> - </field> - - <field name = "immediate" type = "bit"> - 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> - <doc name = "rule" test = "amq_file_00"> - The server SHOULD implement the immediate flag. - </doc> - </field> - - <field name = "identifier" type = "shortstr"> - 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 name = "return" content = "1" index = "70"> - 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" type = "shortstr"> - Message routing key - <doc> - Specifies the routing key name specified when the message was - published. - </doc> - </field> -</method> - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "deliver" index = "80"> - 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> - <doc name = "rule"> - 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> - <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" type = "shortstr"> - Message routing key - <doc> - Specifies the routing key name specified when the message was - published. - </doc> - </field> - - <field name = "identifier" type = "shortstr"> - 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 name = "ack" index = "90"> - 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" type = "bit"> - 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 mesages. - </doc> - <doc name = "rule"> - 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> - </field> -</method> - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "reject" index = "100"> - 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> - <doc name = "rule"> - The server SHOULD interpret this method as meaning that the client - is unable to process the message at this time. - </doc> - <doc name = "rule"> - 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> - <chassis name = "server" implement = "MUST" /> - - <field name = "delivery tag" domain = "delivery tag" /> - - <field name = "requeue" type = "bit"> - 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> - <doc name = "rule"> - The server MUST NOT deliver the message to the same client within - the context of the current channel. 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> - </field> -</method> - -</class> - - <class name="stream" handler="channel" index="80"> - <!-- -====================================================== -== STREAMING -====================================================== ---> - 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 unacknowleged 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 name = "grammar"> - stream = C:QOS S:QOS-OK - / C:CONSUME S:CONSUME-OK - / C:CANCEL S:CANCEL-OK - / C:PUBLISH content - / S:RETURN - / S:DELIVER content -</doc> - -<chassis name = "server" implement = "MAY" /> -<chassis name = "client" implement = "MAY" /> - -<doc name = "rule"> - The server SHOULD discard stream messages on a priority basis if - the queue size exceeds some configured limit. -</doc> -<doc name = "rule"> - 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> -<doc name = "rule"> - 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> - - -<!-- These are the properties for a Stream content --> - -<field name = "content type" type = "shortstr"> - MIME content type -</field> -<field name = "content encoding" type = "shortstr"> - MIME content encoding -</field> -<field name = "headers" type = "table"> - Message header field table -</field> -<field name = "priority" type = "octet"> - The message priority, 0 to 9 -</field> -<field name = "timestamp" type = "timestamp"> - The message timestamp -</field> - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "qos" synchronous = "1" index = "10"> - specify quality of service - <doc> - This method requests a specific quality of service. The QoS can - be specified for the current channel or for all channels 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" type = "long"> - 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 - down the channel. 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" type = "short"> - 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 channel and connection level) allow it. - </doc> - </field> - - <field name = "consume rate" type = "long"> - 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> - <doc name = "rule"> - 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. The server MAY drop low-priority - messages in favour of high-priority messages. - </doc> - </field> - - <field name = "global" type = "bit"> - apply to entire connection - <doc> - By default the QoS settings apply to the current channel only. If - this field is set, they are applied to the entire connection. - </doc> - </field> -</method> - -<method name = "qos-ok" synchronous = "1" index = "11"> - 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 name = "consume" synchronous = "1" index = "20"> - 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 channel they were created on, or until the - client cancels them. - </doc> - <doc name = "rule"> - 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> - <doc name = "rule"> - Streaming applications SHOULD use different channels 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> - <chassis name = "server" implement = "MUST" /> - <response name = "consume-ok" /> - - <field name = "ticket" domain = "access ticket"> - <doc name = "rule"> - The client MUST provide a valid access ticket giving "read" access - rights to the realm for the queue. - </doc> - </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 channel, which is the - last declared queue. - </doc> - <doc name = "rule"> - 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> - </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> - <doc name = "rule" test = "todo"> - 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> - </field> - - <field name = "no local" domain = "no local" /> - - <field name = "exclusive" type = "bit"> - request exclusive access - <doc> - Request exclusive consumer access, meaning only this consumer can - access the queue. - </doc> - <doc name = "rule" test = "amq_file_00"> - 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> - </field> - - <field name = "nowait" type = "bit"> - 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> -</method> - - -<method name = "consume-ok" synchronous = "1" index = "21"> - 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 name = "cancel" synchronous = "1" index = "30"> - 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 canceling a consumer. It may process or - discard these as appropriate. - </doc> - <chassis name = "server" implement = "MUST" /> - <response name = "cancel-ok" /> - - <field name = "consumer tag" domain = "consumer tag" /> - - <field name = "nowait" type = "bit"> - 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> -</method> - -<method name = "cancel-ok" synchronous = "1" index = "31"> - confirm a cancelled consumer - <doc> - This method confirms that the cancellation was completed. - </doc> - <chassis name = "client" implement = "MUST" /> - - <field name = "consumer tag" domain = "consumer tag" /> -</method> - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "publish" content = "1" index = "40"> - 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"> - <doc name = "rule"> - The client MUST provide a valid access ticket giving "write" - access rights to the access realm for the exchange. - </doc> - </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> - <doc name = "rule"> - The server MUST accept a blank exchange name to mean the default - exchange. - </doc> - <doc name = "rule"> - 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> - <doc name = "rule"> - 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> - </field> - - <field name = "routing key" type = "shortstr"> - 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" type = "bit"> - 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> - <doc name = "rule" test = "amq_stream_00"> - The server SHOULD implement the mandatory flag. - </doc> - </field> - - <field name = "immediate" type = "bit"> - 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> - <doc name = "rule" test = "amq_stream_00"> - The server SHOULD implement the immediate flag. - </doc> - </field> -</method> - -<method name = "return" content = "1" index = "50"> - 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" type = "shortstr"> - Message routing key - <doc> - Specifies the routing key name specified when the message was - published. - </doc> - </field> -</method> - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - -<method name = "deliver" content = "1" index = "60"> - 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 channel can start many consumers on different - queues. - </doc> - <assert check = "notnull" /> - </field> -</method> - </class> - - <class name="tx" handler="channel" index="90"> - <!-- -====================================================== -== TRANSACTIONS -====================================================== ---> - 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> - <rule implement="SHOULD"> - 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. -</rule> - <doc name="grammar"> - tx = C:SELECT S:SELECT-OK - / C:COMMIT S:COMMIT-OK - / C:ROLLBACK S:ROLLBACK-OK -</doc> - <chassis name="server" implement="SHOULD"/> - <chassis name="client" implement="MAY"/> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="select" synchronous="1" index="10"> -select standard transaction mode - <doc> - This method sets the channel to use standard transactions. The - client must use this method at least once on a channel before - using the Commit or Rollback methods. - </doc> - <chassis name="server" implement="MUST"/> - <response name="select-ok"/> - </method> - <method name="select-ok" synchronous="1" index="11"> -confirm transaction mode - <doc> - This method confirms to the client that the channel was successfully - set to use standard transactions. - </doc> - <chassis name="client" implement="MUST"/> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="commit" synchronous="1" index="20"> -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"/> - <response name="commit-ok"/> - </method> - <method name="commit-ok" synchronous="1" index="21"> -confirm a successful commit - <doc> - This method confirms to the client that the commit succeeded. - Note that if a commit fails, the server raises a channel exception. - </doc> - <chassis name="client" implement="MUST"/> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="rollback" synchronous="1" index="30"> -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"/> - <response name="rollback-ok"/> - </method> - <method name="rollback-ok" synchronous="1" index="31"> -confirm a successful rollback - <doc> - This method confirms to the client that the rollback succeeded. - Note that if an rollback fails, the server raises a channel exception. - </doc> - <chassis name="client" implement="MUST"/> - </method> - </class> - <class name="dtx" handler="channel" index="100"> - <!-- -====================================================== -== DISTRIBUTED TRANSACTIONS -====================================================== ---> - work with distributed transactions - -<doc> - Distributed transactions provide so-called "2-phase commit". The - AMQP distributed transaction model supports the X-Open XA - architecture and other distributed transaction implementations. - The Dtx class assumes that the server has a private communications - channel (not AMQP) to a distributed transaction coordinator. -</doc> - <doc name="grammar"> - dtx = C:SELECT S:SELECT-OK - C:START S:START-OK -</doc> - <chassis name="server" implement="MAY"/> - <chassis name="client" implement="MAY"/> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="select" synchronous="1" index="10"> -select standard transaction mode - <doc> - This method sets the channel to use distributed transactions. The - client must use this method at least once on a channel before - using the Start method. - </doc> - <chassis name="server" implement="MUST"/> - <response name="select-ok"/> - </method> - <method name="select-ok" synchronous="1" index="11"> -confirm transaction mode - <doc> - This method confirms to the client that the channel was successfully - set to use distributed transactions. - </doc> - <chassis name="client" implement="MUST"/> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="start" synchronous="1" index="20"> - start a new distributed transaction - <doc> - This method starts a new distributed transaction. This must be - the first method on a new channel that uses the distributed - transaction mode, before any methods that publish or consume - messages. - </doc> - <chassis name="server" implement="MAY"/> - <response name="start-ok"/> - <field name="dtx identifier" type="shortstr"> - transaction identifier - <doc> - The distributed transaction key. This identifies the transaction - so that the AMQP server can coordinate with the distributed - transaction coordinator. - </doc> - <assert check="notnull"/> - </field> - </method> - <method name="start-ok" synchronous="1" index="21"> - confirm the start of a new distributed transaction - <doc> - This method confirms to the client that the transaction started. - Note that if a start fails, the server raises a channel exception. - </doc> - <chassis name="client" implement="MUST"/> - </method> - </class> - <class name="tunnel" handler="tunnel" index="110"> - <!-- -====================================================== -== TUNNEL -====================================================== ---> - methods for protocol tunneling. - -<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 name="grammar"> - tunnel = C:REQUEST - / S:REQUEST -</doc> - <chassis name="server" implement="MAY"/> - <chassis name="client" implement="MAY"/> - <field name="headers" type="table"> - Message header field table -</field> - <field name="proxy name" type="shortstr"> - The identity of the tunnelling proxy -</field> - <field name="data name" type="shortstr"> - The name or type of the message being tunnelled -</field> - <field name="durable" type="octet"> - The message durability indicator -</field> - <field name="broadcast" type="octet"> - The message broadcast mode -</field> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="request" content="1" index="10"> - 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" type="table"> - 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 name="test" handler="channel" index="120"> - <!-- -====================================================== -== TEST - CHECK FUNCTIONAL CAPABILITIES OF AN IMPLEMENTATION -====================================================== ---> - test functional primitives of the implementation - -<doc> - The test class provides methods for a peer to test the basic - operational correctness of another peer. The test methods are - intended to ensure that all peers respect at least the basic - elements of the protocol, such as frame and content organisation - and field types. We assume that a specially-designed peer, a - "monitor client" would perform such tests. -</doc> - <doc name="grammar"> - test = C:INTEGER S:INTEGER-OK - / S:INTEGER C:INTEGER-OK - / C:STRING S:STRING-OK - / S:STRING C:STRING-OK - / C:TABLE S:TABLE-OK - / S:TABLE C:TABLE-OK - / C:CONTENT S:CONTENT-OK - / S:CONTENT C:CONTENT-OK -</doc> - <chassis name="server" implement="MUST"/> - <chassis name="client" implement="SHOULD"/> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="integer" synchronous="1" index="10"> - test integer handling - <doc> - This method tests the peer's capability to correctly marshal integer - data. - </doc> - <chassis name="client" implement="MUST"/> - <chassis name="server" implement="MUST"/> - <response name="integer-ok"/> - <field name="integer 1" type="octet"> - octet test value - <doc> - An octet integer test value. - </doc> - </field> - <field name="integer 2" type="short"> - short test value - <doc> - A short integer test value. - </doc> - </field> - <field name="integer 3" type="long"> - long test value - <doc> - A long integer test value. - </doc> - </field> - <field name="integer 4" type="longlong"> - long-long test value - <doc> - A long long integer test value. - </doc> - </field> - <field name="operation" type="octet"> - operation to test - <doc> - The client must execute this operation on the provided integer - test fields and return the result. - </doc> - <assert check="enum"> - <value name="add">return sum of test values</value> - <value name="min">return lowest of test values</value> - <value name="max">return highest of test values</value> - </assert> - </field> - </method> - <method name="integer-ok" synchronous="1" index="11"> - report integer test result - <doc> - This method reports the result of an Integer method. - </doc> - <chassis name="client" implement="MUST"/> - <chassis name="server" implement="MUST"/> - <field name="result" type="longlong"> - result value - <doc> - The result of the tested operation. - </doc> - </field> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="string" synchronous="1" index="20"> - test string handling - <doc> - This method tests the peer's capability to correctly marshal string - data. - </doc> - <chassis name="client" implement="MUST"/> - <chassis name="server" implement="MUST"/> - <response name="string-ok"/> - <field name="string 1" type="shortstr"> - short string test value - <doc> - An short string test value. - </doc> - </field> - <field name="string 2" type="longstr"> - long string test value - <doc> - A long string test value. - </doc> - </field> - <field name="operation" type="octet"> - operation to test - <doc> - The client must execute this operation on the provided string - test fields and return the result. - </doc> - <assert check="enum"> - <value name="add">return concatentation of test strings</value> - <value name="min">return shortest of test strings</value> - <value name="max">return longest of test strings</value> - </assert> - </field> - </method> - <method name="string-ok" synchronous="1" index="21"> - report string test result - <doc> - This method reports the result of a String method. - </doc> - <chassis name="client" implement="MUST"/> - <chassis name="server" implement="MUST"/> - <field name="result" type="longstr"> - result value - <doc> - The result of the tested operation. - </doc> - </field> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="table" synchronous="1" index="30"> - test field table handling - <doc> - This method tests the peer's capability to correctly marshal field - table data. - </doc> - <chassis name="client" implement="MUST"/> - <chassis name="server" implement="MUST"/> - <response name="table-ok"/> - <field name="table" type="table"> - field table of test values - <doc> - A field table of test values. - </doc> - </field> - <field name="integer op" type="octet"> - operation to test on integers - <doc> - The client must execute this operation on the provided field - table integer values and return the result. - </doc> - <assert check="enum"> - <value name="add">return sum of numeric field values</value> - <value name="min">return min of numeric field values</value> - <value name="max">return max of numeric field values</value> - </assert> - </field> - <field name="string op" type="octet"> - operation to test on strings - <doc> - The client must execute this operation on the provided field - table string values and return the result. - </doc> - <assert check="enum"> - <value name="add">return concatenation of string field values</value> - <value name="min">return shortest of string field values</value> - <value name="max">return longest of string field values</value> - </assert> - </field> - </method> - <method name="table-ok" synchronous="1" index="31"> - report table test result - <doc> - This method reports the result of a Table method. - </doc> - <chassis name="client" implement="MUST"/> - <chassis name="server" implement="MUST"/> - <field name="integer result" type="longlong"> - integer result value - <doc> - The result of the tested integer operation. - </doc> - </field> - <field name="string result" type="longstr"> - string result value - <doc> - The result of the tested string operation. - </doc> - </field> - </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name="content" synchronous="1" content="1" index="40"> - test content handling - <doc> - This method tests the peer's capability to correctly marshal content. - </doc> - <chassis name="client" implement="MUST"/> - <chassis name="server" implement="MUST"/> - <response name="content-ok"/> - </method> - <method name="content-ok" synchronous="1" content="1" index="41"> - report content test result - <doc> - This method reports the result of a Content method. It contains the - content checksum and echoes the original content as provided. - </doc> - <chassis name="client" implement="MUST"/> - <chassis name="server" implement="MUST"/> - <field name="content checksum" type="long"> - content hash - <doc> - The 32-bit checksum of the content, calculated by adding the - content into a 32-bit accumulator. - </doc> - </field> - </method> - </class> -</amqp> |