mcs/class/RabbitMQ.Client/docs/specs/qpid-amqp.0-8.xml

   1 <?xml version="1.0"?>
   2
   3 <!--
   4         Copyright Notice
   5         ================
   6         (c) Copyright JPMorgan Chase Bank & Co., Cisco Systems, Inc., Envoy Technologies Inc.,
   7         iMatix Corporation, IONA\ufffd Technologies, Red Hat, Inc.,
   8         TWIST Process Innovations, and 29West Inc. 2006. All rights reserved.
   9
  10         License
  11         =======
  12         JPMorgan Chase Bank & Co., Cisco Systems, Inc., Envoy Technologies Inc., iMatix
  13         Corporation, IONA Technologies, Red Hat, Inc., TWIST Process Innovations, and
  14         29West Inc. (collectively, the "Authors") each hereby grants to you a worldwide,
  15         perpetual, royalty-free, nontransferable, nonexclusive license to
  16         (i) copy, display, distribute and implement the Advanced Messaging Queue Protocol
  17         ("AMQP") Specification and (ii) the Licensed Claims that are held by
  18         the Authors, all for the purpose of implementing the Advanced Messaging
  19         Queue Protocol Specification. Your license and any rights under this
  20         Agreement will terminate immediately without notice from
  21         any Author if you bring any claim, suit, demand, or action related to
  22         the Advanced Messaging Queue Protocol Specification against any Author.
  23         Upon termination, you shall destroy all copies of the Advanced Messaging
  24         Queue Protocol Specification in your possession or control.
  25
  26         As used hereunder, "Licensed Claims" means those claims of a patent or
  27         patent application, throughout the world, excluding design patents and
  28         design registrations, owned or controlled, or that can be sublicensed
  29         without fee and in compliance with the requirements of this
  30         Agreement, by an Author or its affiliates now or at any
  31         future time and which would necessarily be infringed by implementation
  32         of the Advanced Messaging Queue Protocol Specification. A claim is
  33         necessarily infringed hereunder only when it is not possible to avoid
  34         infringing it because there is no plausible non-infringing alternative
  35         for implementing the required portions of the Advanced Messaging Queue
  36         Protocol Specification. Notwithstanding the foregoing, Licensed Claims
  37         shall not include any claims other than as set forth above even if
  38         contained in the same patent as Licensed Claims; or that read solely
  39         on any implementations of any portion of the Advanced Messaging Queue
  40         Protocol Specification that are not required by the Advanced Messaging
  41         Queue Protocol Specification, or that, if licensed, would require a
  42         payment of royalties by the licensor to unaffiliated third parties.
  43         Moreover, Licensed Claims shall not include (i) any enabling technologies
  44         that may be necessary to make or use any Licensed Product but are not
  45         themselves expressly set forth in the Advanced Messaging Queue Protocol
  46         Specification (e.g., semiconductor manufacturing technology, compiler
  47         technology, object oriented technology, networking technology, operating
  48         system technology, and the like); or (ii) the implementation of other
  49         published standards developed elsewhere and merely referred to in the
  50         body of the Advanced Messaging Queue Protocol Specification, or
  51         (iii) any Licensed Product and any combinations thereof the purpose or
  52         function of which is not required for compliance with the Advanced
  53         Messaging Queue Protocol Specification. For purposes of this definition,
  54         the Advanced Messaging Queue Protocol Specification shall be deemed to
  55         include both architectural and interconnection requirements essential
  56         for interoperability and may also include supporting source code artifacts
  57         where such architectural, interconnection requirements and source code
  58         artifacts are expressly identified as being required or documentation to
  59         achieve compliance with the Advanced Messaging Queue Protocol Specification.
  60
  61         As used hereunder, "Licensed Products" means only those specific portions
  62         of products (hardware, software or combinations thereof) that implement
  63         and are compliant with all relevant portions of the Advanced Messaging
  64         Queue Protocol Specification.
  65
  66         The following disclaimers, which you hereby also acknowledge as to any
  67         use you may make of the Advanced Messaging Queue Protocol Specification:
  68
  69         THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION IS PROVIDED "AS IS,"
  70         AND THE AUTHORS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
  71         IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY,
  72         FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE
  73         CONTENTS OF THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION ARE
  74         SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF THE ADVANCED
  75         MESSAGING QUEUE PROTOCOL SPECIFICATION WILL NOT INFRINGE ANY THIRD PARTY
  76         PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
  77
  78         THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL,
  79         INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATING TO ANY
  80         USE, IMPLEMENTATION OR DISTRIBUTION OF THE ADVANCED MESSAGING QUEUE
  81         PROTOCOL SPECIFICATION.
  82
  83         The name and trademarks of the Authors may NOT be used in any manner,
  84         including advertising or publicity pertaining to the Advanced Messaging
  85         Queue Protocol Specification or its contents without specific, written
  86         prior permission. Title to copyright in the Advanced Messaging Queue
  87         Protocol Specification will at all times remain with the Authors.
  88
  89         No other rights are granted by implication, estoppel or otherwise.
  90
  91         Upon termination of your license or rights under this Agreement, you
  92         shall destroy all copies of the Advanced Messaging Queue Protocol
  93         Specification in your possession or control.
  94
  95         Trademarks
  96         ==========
  97         "JPMorgan", "JPMorgan Chase", "Chase", the JPMorgan Chase logo and the
  98         Octagon Symbol are trademarks of JPMorgan Chase & Co.
  99
 100         IMATIX and the iMatix logo are trademarks of iMatix Corporation sprl.
 101
 102         IONA, IONA Technologies, and the IONA logos are trademarks of IONA
 103         Technologies PLC and/or its subsidiaries.
 104
 105         LINUX is a trademark of Linus Torvalds. RED HAT and JBOSS are registered
 106         trademarks of Red Hat, Inc. in the US and other countries.
 107
 108         Java, all Java-based trademarks and OpenOffice.org are trademarks of
 109         Sun Microsystems, Inc. in the United States, other countries, or both.
 110
 111         Other company, product, or service names may be trademarks or service
 112         marks of others.
 113
 114         Links to full AMQP specification:
 115         =================================
 116         http://www.envoytech.org/spec/amq/
 117         http://www.iona.com/opensource/amqp/
 118         http://www.redhat.com/solutions/specifications/amqp/
 119         http://www.twiststandards.org/tiki-index.php?page=AMQ
 120         http://www.imatix.com/amqp
 121
 122 -->
 123
 124 <!--
 125 ========================================================
 126 EDITORS: (PH)   Pieter Hintjens <ph@imatix.com>
 127          (KvdR) Kim van der Riet <kim.vdriet@redhat.com>
 128
 129 NOTE: These editors have been assigned by the AMQP working group. Please do not
 130 edit/commit this file without consulting with one of the above editors.
 131 ========================================================
 132
 133 Revision history:
 134     2006-06-07 (PH) - version number changed to 0.8 to conform to public
 135     release documentation.
 136
 137     2006-05-15 (PH) - fixed comments on queue name in basic.get to clarify
 138     use of current queue in this method.
 139
 140     2006-05-15 (PH) - fixed comments on routing key in queue.bind to clarify
 141     how routing key is filled when empty (to allow asynch queue.declare).
 142
 143     2006-05-11 (PH) - reset version to 0.70 so that putatitive standards
 144     group can release 2-3 major new versions before hitting 1.0 (again).
 145
 146     2006-05-11 (PH) - TODO in documentation: cycle field in frame header
 147     has been removed.
 148
 149     2006-05-11 (PH) - added nowait option to exchange.declare, delete,
 150     queue.declare, delete, bind, purge, basic.consume, cancel,
 151     file.consume, cancel, stream.consume and cancel methods.
 152
 153     2006-05-11 (PH) - removed notnull rule and added explanations on queue
 154     name in queue.bind, purge, delete, basic.consume, cancel, file.consume,
 155     cancel, stream.consume and cancel methods.
 156
 157     2006-05-11 (PH) - added basic.qos, file.qos, and stream.qos methods that
 158     regroup all prefetch options from the consume methods.  Also removed the
 159     prefetch option from channel.open.
 160
 161     2006-05-11 (PH) - renumbered method indexes to show request-response
 162     nature of methods; requests are 10, 20, 30 while responses are 11, 21,
 163     etc.
 164
 165     2006-05-11 (PH) - removed OpenAMQ extension methods from this definition
 166     since these are maintained seperately.
 167
 168     2006-05-26 (RG) - added Basic.Recover method to allow replay of
 169     unacknowledged messages on a channel.
 170
 171     2006-07-03 (PH) - cosmetic clean-up of Basic.Recover comments.
 172 -->
 173
 174 <amqp major="8" minor="0" port="5672" comment="AMQ protocol 0.80">
 175     AMQ Protocol 0.80
 176
 177 <!--
 178 ======================================================
 179 ==       CONSTANTS
 180 ======================================================
 181 -->
 182   <constant name="frame method" value="1"/>
 183   <constant name="frame header" value="2"/>
 184   <constant name="frame body" value="3"/>
 185   <constant name="frame oob method" value="4"/>
 186   <constant name="frame oob header" value="5"/>
 187   <constant name="frame oob body" value="6"/>
 188   <constant name="frame trace" value="7"/>
 189   <constant name="frame heartbeat" value="8"/>
 190   <constant name="frame min size" value="4096"/>
 191   <constant name="frame end" value="206"/>
 192   <constant name="reply success" value="200">
 193   Indicates that the method completed successfully. This reply code is
 194   reserved for future use - the current protocol design does not use
 195   positive confirmation and reply codes are sent only in case of an
 196   error.
 197 </constant>
 198   <constant name="not delivered" value="310" class="soft error">
 199   The client asked for a specific message that is no longer available.
 200   The message was delivered to another client, or was purged from the
 201   queue for some other reason.
 202 </constant>
 203   <constant name="content too large" value="311" class="soft error">
 204   The client attempted to transfer content larger than the server
 205   could accept at the present time.  The client may retry at a later
 206   time.
 207 </constant>
 208   <constant name="connection forced" value="320" class="hard error">
 209   An operator intervened to close the connection for some reason.
 210   The client may retry at some later date.
 211 </constant>
 212   <constant name="invalid path" value="402" class="hard error">
 213   The client tried to work with an unknown virtual host or cluster.
 214 </constant>
 215   <constant name="access refused" value="403" class="soft error">
 216   The client attempted to work with a server entity to which it has
 217   no  due to security settings.
 218 </constant>
 219   <constant name="not found" value="404" class="soft error">
 220   The client attempted to work with a server entity that does not exist.
 221 </constant>
 222   <constant name="resource locked" value="405" class="soft error">
 223   The client attempted to work with a server entity to which it has
 224   no access because another client is working with it.
 225 </constant>
 226   <constant name="frame error" value="501" class="hard error">
 227   The client sent a malformed frame that the server could not decode.
 228   This strongly implies a programming error in the client.
 229 </constant>
 230   <constant name="syntax error" value="502" class="hard error">
 231   The client sent a frame that contained illegal values for one or more
 232   fields.  This strongly implies a programming error in the client.
 233 </constant>
 234   <constant name="command invalid" value="503" class="hard error">
 235   The client sent an invalid sequence of frames, attempting to perform
 236   an operation that was considered invalid by the server. This usually
 237   implies a programming error in the client.
 238 </constant>
 239   <constant name="channel error" value="504" class="hard error">
 240   The client attempted to work with a channel that had not been
 241   correctly opened.  This most likely indicates a fault in the client
 242   layer.
 243 </constant>
 244   <constant name="resource error" value="506" class="hard error">
 245   The server could not complete the method because it lacked sufficient
 246   resources. This may be due to the client creating too many of some
 247   type of entity.
 248 </constant>
 249   <constant name="not allowed" value="530" class="hard error">
 250   The client tried to work with some entity in a manner that is
 251   prohibited by the server, due to security settings or by some other
 252   criteria.
 253 </constant>
 254   <constant name="not implemented" value="540" class="hard error">
 255   The client tried to use functionality that is not implemented in the
 256   server.
 257 </constant>
 258   <constant name="internal error" value="541" class="hard error">
 259   The server could not complete the method because of an internal error.
 260   The server may require intervention by an operator in order to resume
 261   normal operations.
 262 </constant>
 263   <!--
 264 ======================================================
 265 ==       DOMAIN TYPES
 266 ======================================================
 267 -->
 268   <domain name="access ticket" type="short">
 269     access ticket granted by server
 270     <doc>
 271     An access ticket granted by the server for a certain set of access
 272     rights within a specific realm. Access tickets are valid within the
 273     channel where they were created, and expire when the channel closes.
 274     </doc>
 275     <assert check="ne" value="0"/>
 276   </domain>
 277   <domain name="class id" type="short"/>
 278   <domain name="consumer tag" type="shortstr">
 279     consumer tag
 280     <doc>
 281       Identifier for the consumer, valid within the current connection.
 282     </doc>
 283     <rule implement="MUST">
 284       The consumer tag is valid only within the channel from which the
 285       consumer was created. I.e. a client MUST NOT create a consumer in
 286       one channel and then use it in another.
 287     </rule>
 288   </domain>
 289   <domain name="delivery tag" type="longlong">
 290     server-assigned delivery tag
 291     <doc>
 292       The server-assigned and channel-specific delivery tag
 293     </doc>
 294     <rule implement="MUST">
 295       The delivery tag is valid only within the channel from which the
 296       message was received.  I.e. a client MUST NOT receive a message on
 297       one channel and then acknowledge it on another.
 298     </rule>
 299     <rule implement="MUST">
 300       The server MUST NOT use a zero value for delivery tags.  Zero is
 301       reserved for client use, meaning "all messages so far received".
 302     </rule>
 303   </domain>
 304   <domain name="exchange name" type="shortstr">
 305     exchange name
 306     <doc>
 307       The exchange name is a client-selected string that identifies
 308       the exchange for publish methods.  Exchange names may consist
 309       of any mixture of digits, letters, and underscores.  Exchange
 310       names are scoped by the virtual host.
 311     </doc>
 312     <assert check="length" value="127"/>
 313   </domain>
 314   <domain name="known hosts" type="shortstr">
 315 list of known hosts
 316 <doc>
 317 Specifies the list of equivalent or alternative hosts that the server
 318 knows about, which will normally include the current server itself.
 319 Clients can cache this information and use it when reconnecting to a
 320 server after a failure.
 321 </doc>
 322     <rule implement="MAY">
 323 The server MAY leave this field empty if it knows of no other
 324 hosts than itself.
 325 </rule>
 326   </domain>
 327   <domain name="method id" type="short"/>
 328   <domain name="no ack" type="bit">
 329     no acknowledgement needed
 330     <doc>
 331       If this field is set the server does not expect acknowledgments
 332       for messages.  That is, when a message is delivered to the client
 333       the server automatically and silently acknowledges it on behalf
 334       of the client.  This functionality increases performance but at
 335       the cost of reliability.  Messages can get lost if a client dies
 336       before it can deliver them to the application.
 337     </doc>
 338   </domain>
 339   <domain name="no local" type="bit">
 340     do not deliver own messages
 341     <doc>
 342     If the no-local field is set the server will not send messages to
 343     the client that published them.
 344     </doc>
 345   </domain>
 346   <domain name="path" type="shortstr">
 347     <doc>
 348   Must start with a slash "/" and continue with path names
 349   separated by slashes. A path name consists of any combination
 350   of at least one of [A-Za-z0-9] plus zero or more of [.-_+!=:].
 351 </doc>
 352     <assert check="notnull"/>
 353     <assert check="syntax" rule="path"/>
 354     <assert check="length" value="127"/>
 355   </domain>
 356   <domain name="peer properties" type="table">
 357     <doc>
 358 This string provides a set of peer properties, used for
 359 identification, debugging, and general information.
 360 </doc>
 361     <rule implement="SHOULD">
 362 The properties SHOULD contain these fields:
 363 "product", giving the name of the peer product, "version", giving
 364 the name of the peer version, "platform", giving the name of the
 365 operating system, "copyright", if appropriate, and "information",
 366 giving other general information.
 367 </rule>
 368   </domain>
 369   <domain name="queue name" type="shortstr">
 370     queue name
 371     <doc>
 372     The queue name identifies the queue within the vhost.  Queue
 373     names may consist of any mixture of digits, letters, and
 374     underscores.
 375     </doc>
 376     <assert check="length" value="127"/>
 377   </domain>
 378   <domain name="redelivered" type="bit">
 379     message is being redelivered
 380     <doc>
 381       This indicates that the message has been previously delivered to
 382       this or another client.
 383     </doc>
 384     <rule implement="SHOULD">
 385       The server SHOULD try to signal redelivered messages when it can.
 386       When redelivering a message that was not successfully acknowledged,
 387       the server SHOULD deliver it to the original client if possible.
 388     </rule>
 389     <rule implement="MUST">
 390       The client MUST NOT rely on the redelivered field but MUST take it
 391       as a hint that the message may already have been processed.  A
 392       fully robust client must be able to track duplicate received messages
 393       on non-transacted, and locally-transacted channels.
 394     </rule>
 395   </domain>
 396   <domain name="reply code" type="short">
 397 reply code from server
 398 <doc>
 399   The reply code. The AMQ reply codes are defined in AMQ RFC 011.
 400 </doc>
 401     <assert check="notnull"/>
 402   </domain>
 403   <domain name="reply text" type="shortstr">
 404 localised reply text
 405 <doc>
 406   The localised reply text.  This text can be logged as an aid to
 407   resolving issues.
 408 </doc>
 409     <assert check="notnull"/>
 410   </domain>
 411   <class name="connection" handler="connection" index="10">
 412     <!--
 413 ======================================================
 414 ==       CONNECTION
 415 ======================================================
 416 -->
 417   work with socket connections
 418 <doc>
 419   The connection class provides methods for a client to establish a
 420   network connection to a server, and for both peers to operate the
 421   connection thereafter.
 422 </doc>
 423     <doc name="grammar">
 424     connection          = open-connection *use-connection close-connection
 425     open-connection     = C:protocol-header
 426                           S:START C:START-OK
 427                           *challenge
 428                           S:TUNE C:TUNE-OK
 429                           C:OPEN S:OPEN-OK | S:REDIRECT
 430     challenge           = S:SECURE C:SECURE-OK
 431     use-connection      = *channel
 432     close-connection    = C:CLOSE S:CLOSE-OK
 433                         / S:CLOSE C:CLOSE-OK
 434 </doc>
 435     <chassis name="server" implement="MUST"/>
 436     <chassis name="client" implement="MUST"/>
 437     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 438     <method name="start" synchronous="1" index="10">
 439   start connection negotiation
 440   <doc>
 441     This method starts the connection negotiation process by telling
 442     the client the protocol version that the server proposes, along
 443     with a list of security mechanisms which the client can use for
 444     authentication.
 445   </doc>
 446       <rule implement="MUST">
 447     If the client cannot handle the protocol version suggested by the
 448     server it MUST close the socket connection.
 449   </rule>
 450       <rule implement="MUST">
 451     The server MUST provide a protocol version that is lower than or
 452     equal to that requested by the client in the protocol header. If
 453     the server cannot support the specified protocol it MUST NOT send
 454     this method, but MUST close the socket connection.
 455   </rule>
 456       <chassis name="client" implement="MUST"/>
 457       <response name="start-ok"/>
 458       <field name="version major" type="octet">
 459     protocol major version
 460     <doc>
 461       The protocol major version that the server agrees to use, which
 462       cannot be higher than the client's major version.
 463     </doc>
 464       </field>
 465       <field name="version minor" type="octet">
 466     protocol major version
 467     <doc>
 468       The protocol minor version that the server agrees to use, which
 469       cannot be higher than the client's minor version.
 470     </doc>
 471       </field>
 472       <field name="server properties" domain="peer properties">
 473     server properties
 474   </field>
 475       <field name="mechanisms" type="longstr">
 476     available security mechanisms
 477     <doc>
 478       A list of the security mechanisms that the server supports, delimited
 479       by spaces.  Currently ASL supports these mechanisms: PLAIN.
 480     </doc>
 481         <see name="security mechanisms"/>
 482         <assert check="notnull"/>
 483       </field>
 484       <field name="locales" type="longstr">
 485     available message locales
 486     <doc>
 487       A list of the message locales that the server supports, delimited
 488       by spaces.  The locale defines the language in which the server
 489       will send reply texts.
 490     </doc>
 491         <rule implement="MUST">
 492       All servers MUST support at least the en_US locale.
 493     </rule>
 494         <assert check="notnull"/>
 495       </field>
 496     </method>
 497     <method name="start-ok" synchronous="1" index="11">
 498   select security mechanism and locale
 499   <doc>
 500     This method selects a SASL security mechanism. ASL uses SASL
 501     (RFC2222) to negotiate authentication and encryption.
 502   </doc>
 503       <chassis name="server" implement="MUST"/>
 504       <field name="client properties" domain="peer properties">
 505     client properties
 506   </field>
 507       <field name="mechanism" type="shortstr">
 508     selected security mechanism
 509     <doc>
 510       A single security mechanisms selected by the client, which must be
 511       one of those specified by the server.
 512     </doc>
 513         <rule implement="SHOULD">
 514       The client SHOULD authenticate using the highest-level security
 515       profile it can handle from the list provided by the server.
 516     </rule>
 517         <rule implement="MUST">
 518     The mechanism field MUST contain one of the security mechanisms
 519     proposed by the server in the Start method. If it doesn't, the
 520     server MUST close the socket.
 521     </rule>
 522         <assert check="notnull"/>
 523       </field>
 524       <field name="response" type="longstr">
 525     security response data
 526     <doc>
 527       A block of opaque data passed to the security mechanism. The contents
 528       of this data are defined by the SASL security mechanism.  For the
 529       PLAIN security mechanism this is defined as a field table holding
 530       two fields, LOGIN and PASSWORD.
 531     </doc>
 532         <assert check="notnull"/>
 533       </field>
 534       <field name="locale" type="shortstr">
 535     selected message locale
 536     <doc>
 537       A single message local selected by the client, which must be one
 538       of those specified by the server.
 539     </doc>
 540         <assert check="notnull"/>
 541       </field>
 542     </method>
 543     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 544     <method name="secure" synchronous="1" index="20">
 545   security mechanism challenge
 546   <doc>
 547     The SASL protocol works by exchanging challenges and responses until
 548     both peers have received sufficient information to authenticate each
 549     other.  This method challenges the client to provide more information.
 550   </doc>
 551       <chassis name="client" implement="MUST"/>
 552       <response name="secure-ok"/>
 553       <field name="challenge" type="longstr">
 554     security challenge data
 555     <doc>
 556       Challenge information, a block of opaque binary data passed to
 557       the security mechanism.
 558     </doc>
 559         <see name="security mechanisms"/>
 560       </field>
 561     </method>
 562     <method name="secure-ok" synchronous="1" index="21">
 563   security mechanism response
 564   <doc>
 565     This method attempts to authenticate, passing a block of SASL data
 566     for the security mechanism at the server side.
 567   </doc>
 568       <chassis name="server" implement="MUST"/>
 569       <field name="response" type="longstr">
 570     security response data
 571     <doc>
 572       A block of opaque data passed to the security mechanism.  The contents
 573       of this data are defined by the SASL security mechanism.
 574     </doc>
 575         <assert check="notnull"/>
 576       </field>
 577     </method>
 578     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 579     <method name="tune" synchronous="1" index="30">
 580   propose connection tuning parameters
 581   <doc>
 582     This method proposes a set of connection configuration values
 583     to the client.  The client can accept and/or adjust these.
 584   </doc>
 585       <chassis name="client" implement="MUST"/>
 586       <response name="tune-ok"/>
 587       <field name="channel max" type="short">
 588     proposed maximum channels
 589     <doc>
 590       The maximum total number of channels that the server allows
 591       per connection. Zero means that the server does not impose a
 592       fixed limit, but the number of allowed channels may be limited
 593       by available server resources.
 594     </doc>
 595       </field>
 596       <field name="frame max" type="long">
 597     proposed maximum frame size
 598     <doc>
 599       The largest frame size that the server proposes for the
 600       connection. The client can negotiate a lower value.  Zero means
 601       that the server does not impose any specific limit but may reject
 602       very large frames if it cannot allocate resources for them.
 603     </doc>
 604         <rule implement="MUST">
 605       Until the frame-max has been negotiated, both peers MUST accept
 606       frames of up to 4096 octets large. The minimum non-zero value for
 607       the frame-max field is 4096.
 608     </rule>
 609       </field>
 610       <field name="heartbeat" type="short">
 611     desired heartbeat delay
 612     <doc>
 613       The delay, in seconds, of the connection heartbeat that the server
 614       wants.  Zero means the server does not want a heartbeat.
 615     </doc>
 616       </field>
 617     </method>
 618     <method name="tune-ok" synchronous="1" index="31">
 619   negotiate connection tuning parameters
 620   <doc>
 621     This method sends the client's connection tuning parameters to the
 622     server. Certain fields are negotiated, others provide capability
 623     information.
 624   </doc>
 625       <chassis name="server" implement="MUST"/>
 626       <field name="channel max" type="short">
 627     negotiated maximum channels
 628     <doc>
 629       The maximum total number of channels that the client will use
 630       per connection.  May not be higher than the value specified by
 631       the server.
 632     </doc>
 633         <rule implement="MAY">
 634       The server MAY ignore the channel-max value or MAY use it for
 635       tuning its resource allocation.
 636     </rule>
 637         <assert check="notnull"/>
 638         <assert check="le" method="tune" field="channel max"/>
 639       </field>
 640       <field name="frame max" type="long">
 641     negotiated maximum frame size
 642     <doc>
 643       The largest frame size that the client and server will use for
 644       the connection.  Zero means that the client does not impose any
 645       specific limit but may reject very large frames if it cannot
 646       allocate resources for them.  Note that the frame-max limit
 647       applies principally to content frames, where large contents
 648       can be broken into frames of arbitrary size.
 649     </doc>
 650         <rule implement="MUST">
 651       Until the frame-max has been negotiated, both peers must accept
 652       frames of up to 4096 octets large. The minimum non-zero value for
 653       the frame-max field is 4096.
 654     </rule>
 655       </field>
 656       <field name="heartbeat" type="short">
 657     desired heartbeat delay
 658     <doc>
 659       The delay, in seconds, of the connection heartbeat that the client
 660       wants. Zero means the client does not want a heartbeat.
 661     </doc>
 662       </field>
 663     </method>
 664     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 665     <method name="open" synchronous="1" index="40">
 666   open connection to virtual host
 667   <doc>
 668     This method opens a connection to a virtual host, which is a
 669     collection of resources, and acts to separate multiple application
 670     domains within a server.
 671   </doc>
 672       <rule implement="MUST">
 673     The client MUST open the context before doing any work on the
 674     connection.
 675   </rule>
 676       <chassis name="server" implement="MUST"/>
 677       <response name="open-ok"/>
 678       <response name="redirect"/>
 679       <field name="virtual host" domain="path">
 680     virtual host name
 681     <assert check="regexp" value="^[a-zA-Z0-9/-_]+$"/>
 682         <doc>
 683       The name of the virtual host to work with.
 684     </doc>
 685         <rule implement="MUST">
 686       If the server supports multiple virtual hosts, it MUST enforce a
 687       full separation of exchanges, queues, and all associated entities
 688       per virtual host. An application, connected to a specific virtual
 689       host, MUST NOT be able to access resources of another virtual host.
 690     </rule>
 691         <rule implement="SHOULD">
 692       The server SHOULD verify that the client has permission to access
 693       the specified virtual host.
 694     </rule>
 695         <rule implement="MAY">
 696       The server MAY configure arbitrary limits per virtual host, such
 697       as the number of each type of entity that may be used, per
 698       connection and/or in total.
 699     </rule>
 700       </field>
 701       <field name="capabilities" type="shortstr">
 702     required capabilities
 703     <doc>
 704       The client may specify a number of capability names, delimited by
 705       spaces.  The server can use this string to how to process the
 706       client's connection request.
 707     </doc>
 708       </field>
 709       <field name="insist" type="bit">
 710     insist on connecting to server
 711     <doc>
 712       In a configuration with multiple load-sharing servers, the server
 713       may respond to a Connection.Open method with a Connection.Redirect.
 714       The insist option tells the server that the client is insisting on
 715       a connection to the specified server.
 716     </doc>
 717         <rule implement="SHOULD">
 718       When the client uses the insist option, the server SHOULD accept
 719       the client connection unless it is technically unable to do so.
 720     </rule>
 721       </field>
 722     </method>
 723     <method name="open-ok" synchronous="1" index="41">
 724   signal that the connection is ready
 725   <doc>
 726     This method signals to the client that the connection is ready for
 727     use.
 728   </doc>
 729       <chassis name="client" implement="MUST"/>
 730       <field name="known hosts" domain="known hosts"/>
 731     </method>
 732     <method name="redirect" synchronous="1" index="50">
 733   asks the client to use a different server
 734   <doc>
 735     This method redirects the client to another server, based on the
 736     requested virtual host and/or capabilities.
 737   </doc>
 738       <rule implement="SHOULD">
 739     When getting the Connection.Redirect method, the client SHOULD
 740     reconnect to the host specified, and if that host is not present,
 741     to any of the hosts specified in the known-hosts list.
 742   </rule>
 743       <chassis name="client" implement="MAY"/>
 744       <field name="host" type="shortstr">
 745     server to connect to
 746     <doc>
 747       Specifies the server to connect to.  This is an IP address or a
 748       DNS name, optionally followed by a colon and a port number. If
 749       no port number is specified, the client should use the default
 750       port number for the protocol.
 751     </doc>
 752         <assert check="notnull"/>
 753       </field>
 754       <field name="known hosts" domain="known hosts"/>
 755     </method>
 756     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 757     <method name="close" synchronous="1" index="60">
 758   request a connection close
 759   <doc>
 760     This method indicates that the sender wants to close the connection.
 761     This may be due to internal conditions (e.g. a forced shut-down) or
 762     due to an error handling a specific method, i.e. an exception.  When
 763     a close is due to an exception, the sender provides the class and
 764     method id of the method which caused the exception.
 765   </doc>
 766       <rule implement="MUST">
 767     After sending this method any received method except the Close-OK
 768     method MUST be discarded.
 769   </rule>
 770       <rule implement="MAY">
 771     The peer sending this method MAY use a counter or timeout to
 772     detect failure of the other peer to respond correctly with
 773     the Close-OK method.
 774   </rule>
 775       <rule implement="MUST">
 776     When a server receives the Close method from a client it MUST
 777     delete all server-side resources associated with the client's
 778     context.  A client CANNOT reconnect to a context after sending
 779     or receiving a Close method.
 780   </rule>
 781       <chassis name="client" implement="MUST"/>
 782       <chassis name="server" implement="MUST"/>
 783       <response name="close-ok"/>
 784       <field name="reply code" domain="reply code"/>
 785       <field name="reply text" domain="reply text"/>
 786       <field name="class id" domain="class id">
 787     failing method class
 788     <doc>
 789       When the close is provoked by a method exception, this is the
 790       class of the method.
 791     </doc>
 792       </field>
 793       <field name="method id" domain="class id">
 794     failing method ID
 795     <doc>
 796       When the close is provoked by a method exception, this is the
 797       ID of the method.
 798     </doc>
 799       </field>
 800     </method>
 801     <method name="close-ok" synchronous="1" index="61">
 802   confirm a connection close
 803   <doc>
 804     This method confirms a Connection.Close method and tells the
 805     recipient that it is safe to release resources for the connection
 806     and close the socket.
 807   </doc>
 808       <rule implement="SHOULD">
 809     A peer that detects a socket closure without having received a
 810     Close-Ok handshake method SHOULD log the error.
 811   </rule>
 812       <chassis name="client" implement="MUST"/>
 813       <chassis name="server" implement="MUST"/>
 814     </method>
 815   </class>
 816   <class name="channel" handler="channel" index="20">
 817     <!--
 818 ======================================================
 819 ==       CHANNEL
 820 ======================================================
 821 -->
 822   work with channels
 823 <doc>
 824   The channel class provides methods for a client to establish a virtual
 825   connection - a channel - to a server and for both peers to operate the
 826   virtual connection thereafter.
 827 </doc>
 828     <doc name="grammar">
 829     channel             = open-channel *use-channel close-channel
 830     open-channel        = C:OPEN S:OPEN-OK
 831     use-channel         = C:FLOW S:FLOW-OK
 832                         / S:FLOW C:FLOW-OK
 833                         / S:ALERT
 834                         / functional-class
 835     close-channel       = C:CLOSE S:CLOSE-OK
 836                         / S:CLOSE C:CLOSE-OK
 837 </doc>
 838     <chassis name="server" implement="MUST"/>
 839     <chassis name="client" implement="MUST"/>
 840     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 841     <method name="open" synchronous="1" index="10">
 842   open a channel for use
 843   <doc>
 844     This method opens a virtual connection (a channel).
 845   </doc>
 846       <rule implement="MUST">
 847     This method MUST NOT be called when the channel is already open.
 848   </rule>
 849       <chassis name="server" implement="MUST"/>
 850       <response name="open-ok"/>
 851       <field name="out of band" type="shortstr">
 852     out-of-band settings
 853     <doc>
 854       Configures out-of-band transfers on this channel.  The syntax and
 855       meaning of this field will be formally defined at a later date.
 856     </doc>
 857         <assert check="null"/>
 858       </field>
 859     </method>
 860     <method name="open-ok" synchronous="1" index="11">
 861   signal that the channel is ready
 862   <doc>
 863     This method signals to the client that the channel is ready for use.
 864   </doc>
 865       <chassis name="client" implement="MUST"/>
 866     </method>
 867     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 868     <method name="flow" synchronous="1" index="20">
 869   enable/disable flow from peer
 870   <doc>
 871     This method asks the peer to pause or restart the flow of content
 872     data. This is a simple flow-control mechanism that a peer can use
 873     to avoid oveflowing its queues or otherwise finding itself receiving
 874     more messages than it can process.  Note that this method is not
 875     intended for window control.  The peer that receives a request to
 876     stop sending content should finish sending the current content, if
 877     any, and then wait until it receives a Flow restart method.
 878   </doc>
 879       <rule implement="MAY">
 880     When a new channel is opened, it is active.  Some applications
 881     assume that channels are inactive until started.  To emulate this
 882     behaviour a client MAY open the channel, then pause it.
 883   </rule>
 884       <rule implement="SHOULD">
 885     When sending content data in multiple frames, a peer SHOULD monitor
 886     the channel for incoming methods and respond to a Channel.Flow as
 887     rapidly as possible.
 888   </rule>
 889       <rule implement="MAY">
 890     A peer MAY use the Channel.Flow method to throttle incoming content
 891     data for internal reasons, for example, when exchangeing data over a
 892     slower connection.
 893   </rule>
 894       <rule implement="MAY">
 895     The peer that requests a Channel.Flow method MAY disconnect and/or
 896     ban a peer that does not respect the request.
 897   </rule>
 898       <chassis name="server" implement="MUST"/>
 899       <chassis name="client" implement="MUST"/>
 900       <response name="flow-ok"/>
 901       <field name="active" type="bit">
 902     start/stop content frames
 903     <doc>
 904       If 1, the peer starts sending content frames.  If 0, the peer
 905       stops sending content frames.
 906     </doc>
 907       </field>
 908     </method>
 909     <method name="flow-ok" index="21">
 910   confirm a flow method
 911   <doc>
 912     Confirms to the peer that a flow command was received and processed.
 913   </doc>
 914       <chassis name="server" implement="MUST"/>
 915       <chassis name="client" implement="MUST"/>
 916       <field name="active" type="bit">
 917     current flow setting
 918     <doc>
 919       Confirms the setting of the processed flow method: 1 means the
 920       peer will start sending or continue to send content frames; 0
 921       means it will not.
 922     </doc>
 923       </field>
 924     </method>
 925     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 926     <method name="alert" index="30">
 927   send a non-fatal warning message
 928   <doc>
 929     This method allows the server to send a non-fatal warning to the
 930     client.  This is used for methods that are normally asynchronous
 931     and thus do not have confirmations, and for which the server may
 932     detect errors that need to be reported.  Fatal errors are handled
 933     as channel or connection exceptions; non-fatal errors are sent
 934     through this method.
 935   </doc>
 936       <chassis name="client" implement="MUST"/>
 937       <field name="reply code" domain="reply code"/>
 938       <field name="reply text" domain="reply text"/>
 939       <field name="details" type="table">
 940     detailed information for warning
 941     <doc>
 942       A set of fields that provide more information about the
 943       problem.  The meaning of these fields are defined on a
 944       per-reply-code basis (TO BE DEFINED).
 945     </doc>
 946       </field>
 947     </method>
 948     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 949     <method name="close" synchronous="1" index="40">
 950   request a channel close
 951   <doc>
 952     This method indicates that the sender wants to close the channel.
 953     This may be due to internal conditions (e.g. a forced shut-down) or
 954     due to an error handling a specific method, i.e. an exception.  When
 955     a close is due to an exception, the sender provides the class and
 956     method id of the method which caused the exception.
 957   </doc>
 958       <rule implement="MUST">
 959     After sending this method any received method except
 960     Channel.Close-OK MUST be discarded.
 961   </rule>
 962       <rule implement="MAY">
 963     The peer sending this method MAY use a counter or timeout to detect
 964     failure of the other peer to respond correctly with Channel.Close-OK..
 965   </rule>
 966       <chassis name="client" implement="MUST"/>
 967       <chassis name="server" implement="MUST"/>
 968       <response name="close-ok"/>
 969       <field name="reply code" domain="reply code"/>
 970       <field name="reply text" domain="reply text"/>
 971       <field name="class id" domain="class id">
 972     failing method class
 973     <doc>
 974       When the close is provoked by a method exception, this is the
 975       class of the method.
 976     </doc>
 977       </field>
 978       <field name="method id" domain="method id">
 979     failing method ID
 980     <doc>
 981       When the close is provoked by a method exception, this is the
 982       ID of the method.
 983     </doc>
 984       </field>
 985     </method>
 986     <method name="close-ok" synchronous="1" index="41">
 987   confirm a channel close
 988   <doc>
 989     This method confirms a Channel.Close method and tells the recipient
 990     that it is safe to release resources for the channel and close the
 991     socket.
 992   </doc>
 993       <rule implement="SHOULD">
 994     A peer that detects a socket closure without having received a
 995     Channel.Close-Ok handshake method SHOULD log the error.
 996   </rule>
 997       <chassis name="client" implement="MUST"/>
 998       <chassis name="server" implement="MUST"/>
 999     </method>
1000   </class>
1001   <class name="access" handler="connection" index="30">
1002     <!--
1003 ======================================================
1004 ==      ACCESS CONTROL
1005 ======================================================
1006 -->
1007   work with access tickets
1008 <doc>
1009   The protocol control access to server resources using access tickets.
1010   A client must explicitly request access tickets before doing work.
1011   An access ticket grants a client the right to use a specific set of
1012   resources - called a "realm" - in specific ways.
1013 </doc>
1014     <doc name="grammar">
1015     access              = C:REQUEST S:REQUEST-OK
1016 </doc>
1017     <chassis name="server" implement="MUST"/>
1018     <chassis name="client" implement="MUST"/>
1019     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1020     <method name="request" synchronous="1" index="10">
1021   request an access ticket
1022   <doc>
1023     This method requests an access ticket for an access realm.
1024     The server responds by granting the access ticket.  If the
1025     client does not have access rights to the requested realm
1026     this causes a connection exception.  Access tickets are a
1027     per-channel resource.
1028   </doc>
1029       <rule implement="MUST">
1030     The realm name MUST start with either "/data" (for application
1031     resources) or "/admin" (for server administration resources).
1032     If the realm starts with any other path, the server MUST raise
1033     a connection exception with reply code 403 (access refused).
1034   </rule>
1035       <rule implement="MUST">
1036     The server MUST implement the /data realm and MAY implement the
1037     /admin realm.  The mapping of resources to realms is not
1038     defined in the protocol - this is a server-side configuration
1039     issue.
1040   </rule>
1041       <chassis name="server" implement="MUST"/>
1042       <response name="request-ok"/>
1043       <field name="realm" domain="path">
1044     name of requested realm
1045     <rule implement="MUST">
1046       If the specified realm is not known to the server, the server
1047       must raise a channel exception with reply code 402 (invalid
1048       path).
1049     </rule>
1050       </field>
1051       <field name="exclusive" type="bit">
1052     request exclusive access
1053     <doc>
1054       Request exclusive access to the realm. If the server cannot grant
1055       this - because there are other active tickets for the realm - it
1056       raises a channel exception.
1057     </doc>
1058       </field>
1059       <field name="passive" type="bit">
1060     request passive access
1061     <doc>
1062       Request message passive access to the specified access realm.
1063       Passive access lets a client get information about resources in
1064       the realm but not to make any changes to them.
1065     </doc>
1066       </field>
1067       <field name="active" type="bit">
1068     request active access
1069     <doc>
1070       Request message active access to the specified access realm.
1071       Acvtive access lets a client get create and delete resources in
1072       the realm.
1073     </doc>
1074       </field>
1075       <field name="write" type="bit">
1076     request write access
1077     <doc>
1078       Request write access to the specified access realm.  Write access
1079       lets a client publish messages to all exchanges in the realm.
1080     </doc>
1081       </field>
1082       <field name="read" type="bit">
1083     request read access
1084     <doc>
1085       Request read access to the specified access realm.  Read access
1086       lets a client consume messages from queues in the realm.
1087     </doc>
1088       </field>
1089     </method>
1090     <method name="request-ok" synchronous="1" index="11">
1091   grant access to server resources
1092   <doc>
1093     This method provides the client with an access ticket. The access
1094     ticket is valid within the current channel and for the lifespan of
1095     the channel.
1096   </doc>
1097       <rule implement="MUST">
1098     The client MUST NOT use access tickets except within the same
1099     channel as originally granted.
1100   </rule>
1101       <rule implement="MUST">
1102     The server MUST isolate access tickets per channel and treat an
1103     attempt by a client to mix these as a connection exception.
1104   </rule>
1105       <chassis name="client" implement="MUST"/>
1106       <field name="ticket" domain="access ticket"/>
1107     </method>
1108   </class>
1109   <class name="exchange" handler="channel" index="40">
1110     <!--
1111 ======================================================
1112 ==       EXCHANGES (or "routers", if you prefer)
1113 ==       (Or matchers, plugins, extensions, agents,... Routing is just one of
1114 ==        the many fun things an exchange can do.)
1115 ======================================================
1116 -->
1117   work with exchanges
1118 <doc>
1119   Exchanges match and distribute messages across queues.  Exchanges can be
1120   configured in the server or created at runtime.
1121 </doc>
1122     <doc name="grammar">
1123     exchange            = C:DECLARE  S:DECLARE-OK
1124                         / C:DELETE   S:DELETE-OK
1125 </doc>
1126     <chassis name="server" implement="MUST"/>
1127     <chassis name="client" implement="MUST"/>
1128     <rule implement="MUST">
1129       <test>amq_exchange_19</test>
1130   The server MUST implement the direct and fanout exchange types, and
1131   predeclare the corresponding exchanges named amq.direct and amq.fanout
1132   in each virtual host. The server MUST also predeclare a direct
1133   exchange to act as the default exchange for content Publish methods
1134   and for default queue bindings.
1135 </rule>
1136     <rule implement="SHOULD">
1137       <test>amq_exchange_20</test>
1138   The server SHOULD implement the topic exchange type, and predeclare
1139   the corresponding exchange named amq.topic in each virtual host.
1140 </rule>
1141     <rule implement="MAY">
1142       <test>amq_exchange_21</test>
1143   The server MAY implement the system exchange type, and predeclare the
1144   corresponding exchanges named amq.system in each virtual host. If the
1145   client attempts to bind a queue to the system exchange, the server
1146   MUST raise a connection exception with reply code 507 (not allowed).
1147 </rule>
1148     <rule implement="MUST">
1149       <test>amq_exchange_22</test>
1150   The default exchange MUST be defined as internal, and be inaccessible
1151   to the client except by specifying an empty exchange name in a content
1152   Publish method. That is, the server MUST NOT let clients make explicit
1153   bindings to this exchange.
1154 </rule>
1155     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1156     <method name="declare" synchronous="1" index="10">
1157   declare exchange, create if needed
1158   <doc>
1159     This method creates an exchange if it does not already exist, and if the
1160     exchange exists, verifies that it is of the correct and expected class.
1161   </doc>
1162       <rule implement="SHOULD">
1163         <test>amq_exchange_23</test>
1164     The server SHOULD support a minimum of 16 exchanges per virtual host
1165     and ideally, impose no limit except as defined by available resources.
1166   </rule>
1167       <chassis name="server" implement="MUST"/>
1168       <response name="declare-ok"/>
1169       <field name="ticket" domain="access ticket">
1170         <doc>
1171       When a client defines a new exchange, this belongs to the access realm
1172       of the ticket used.  All further work done with that exchange must be
1173       done with an access ticket for the same realm.
1174     </doc>
1175         <rule implement="MUST">
1176       The client MUST provide a valid access ticket giving "active" access
1177       to the realm in which the exchange exists or will be created, or
1178       "passive" access if the if-exists flag is set.
1179     </rule>
1180       </field>
1181       <field name="exchange" domain="exchange name">
1182         <rule implement="MUST">
1183           <test>amq_exchange_15</test>
1184       Exchange names starting with "amq." are reserved for predeclared
1185       and standardised exchanges.  If the client attempts to create an
1186       exchange starting with "amq.", the server MUST raise a channel
1187       exception with reply code 403 (access refused).
1188     </rule>
1189         <assert check="regexp" value="^[a-zA-Z0-9-_.:]+$"/>
1190       </field>
1191       <field name="type" type="shortstr">
1192     exchange type
1193     <doc>
1194       Each exchange belongs to one of a set of exchange types implemented
1195       by the server.  The exchange types define the functionality of the
1196       exchange - i.e. how messages are routed through it.  It is not valid
1197       or meaningful to attempt to change the type of an existing exchange.
1198     </doc>
1199         <rule implement="MUST">
1200           <test>amq_exchange_16</test>
1201       If the exchange already exists with a different type, the server
1202       MUST raise a connection exception with a reply code 507 (not allowed).
1203     </rule>
1204         <rule implement="MUST">
1205           <test>amq_exchange_18</test>
1206       If the server does not support the requested exchange type it MUST
1207       raise a connection exception with a reply code 503 (command invalid).
1208     </rule>
1209         <assert check="regexp" value="^[a-zA-Z0-9-_.:]+$"/>
1210       </field>
1211       <field name="passive" type="bit">
1212     do not create exchange
1213     <doc>
1214     If set, the server will not create the exchange.  The client can use
1215     this to check whether an exchange exists without modifying the server
1216     state.
1217     </doc>
1218         <rule implement="MUST">
1219           <test>amq_exchange_05</test>
1220       If set, and the exchange does not already exist, the server MUST
1221       raise a channel exception with reply code 404 (not found).
1222     </rule>
1223       </field>
1224       <field name="durable" type="bit">
1225     request a durable exchange
1226     <doc>
1227       If set when creating a new exchange, the exchange will be marked as
1228       durable.  Durable exchanges remain active when a server restarts.
1229       Non-durable exchanges (transient exchanges) are purged if/when a
1230       server restarts.
1231     </doc>
1232         <rule implement="MUST">
1233           <test>amq_exchange_24</test>
1234       The server MUST support both durable and transient exchanges.
1235     </rule>
1236         <rule implement="MUST">
1237       The server MUST ignore the durable field if the exchange already
1238       exists.
1239     </rule>
1240       </field>
1241       <field name="auto delete" type="bit">
1242     auto-delete when unused
1243     <doc>
1244       If set, the exchange is deleted when all queues have finished
1245       using it.
1246     </doc>
1247         <rule implement="SHOULD">
1248           <test>amq_exchange_02</test>
1249       The server SHOULD allow for a reasonable delay between the point
1250       when it determines that an exchange is not being used (or no longer
1251       used), and the point when it deletes the exchange.  At the least it
1252       must allow a client to create an exchange and then bind a queue to
1253       it, with a small but non-zero delay between these two actions.
1254     </rule>
1255         <rule implement="MUST">
1256           <test>amq_exchange_25</test>
1257       The server MUST ignore the auto-delete field if the exchange already
1258       exists.
1259     </rule>
1260       </field>
1261       <field name="internal" type="bit">
1262     create internal exchange
1263     <doc>
1264       If set, the exchange may not be used directly by publishers, but
1265       only when bound to other exchanges. Internal exchanges are used to
1266       construct wiring that is not visible to applications.
1267     </doc>
1268       </field>
1269
1270   <field name = "nowait" type = "bit">
1271     do not send a reply method
1272     <doc>
1273     If set, the server will not respond to the method. The client should
1274     not wait for a reply method.  If the server could not complete the
1275     method it will raise a channel or connection exception.
1276     </doc>
1277   </field>
1278
1279       <field name="arguments" type="table">
1280     arguments for declaration
1281     <doc>
1282       A set of arguments for the declaration. The syntax and semantics
1283       of these arguments depends on the server implementation.  This
1284       field is ignored if passive is 1.
1285     </doc>
1286       </field>
1287     </method>
1288     <method name="declare-ok" synchronous="1" index="11">
1289   confirms an exchange declaration
1290   <doc>
1291     This method confirms a Declare method and confirms the name of the
1292     exchange, essential for automatically-named exchanges.
1293   </doc>
1294       <chassis name="client" implement="MUST"/>
1295     </method>
1296     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1297     <method name="delete" synchronous="1" index="20">
1298   delete an exchange
1299   <doc>
1300     This method deletes an exchange.  When an exchange is deleted all queue
1301     bindings on the exchange are cancelled.
1302   </doc>
1303       <chassis name="server" implement="MUST"/>
1304       <response name="delete-ok"/>
1305       <field name="ticket" domain="access ticket">
1306         <rule implement="MUST">
1307       The client MUST provide a valid access ticket giving "active"
1308       access rights to the exchange's access realm.
1309     </rule>
1310       </field>
1311       <field name="exchange" domain="exchange name">
1312         <rule implement="MUST">
1313           <test>amq_exchange_11</test>
1314       The exchange MUST exist. Attempting to delete a non-existing exchange
1315       causes a channel exception.
1316     </rule>
1317         <assert check="notnull"/>
1318       </field>
1319       <field name="if unused" type="bit">
1320     delete only if unused
1321     <doc>
1322       If set, the server will only delete the exchange if it has no queue
1323       bindings. If the exchange has queue bindings the server does not
1324       delete it but raises a channel exception instead.
1325     </doc>
1326         <rule implement="SHOULD">
1327           <test>amq_exchange_12</test>
1328       If set, the server SHOULD delete the exchange but only if it has
1329       no queue bindings.
1330     </rule>
1331         <rule implement="SHOULD">
1332           <test>amq_exchange_13</test>
1333       If set, the server SHOULD raise a channel exception if the exchange is in
1334       use.
1335     </rule>
1336       </field>
1337
1338   <field name = "nowait" type = "bit">
1339     do not send a reply method
1340     <doc>
1341     If set, the server will not respond to the method. The client should
1342     not wait for a reply method.  If the server could not complete the
1343     method it will raise a channel or connection exception.
1344     </doc>
1345   </field>
1346
1347     </method>
1348     <method name="delete-ok" synchronous="1" index="21">
1349   confirm deletion of an exchange
1350   <doc>
1351     This method confirms the deletion of an exchange.
1352   </doc>
1353       <chassis name="client" implement="MUST"/>
1354     </method>
1355
1356     <method name="bound" synchronous="1" index="22">
1357         <field name="exchange" domain="exchange name"/>
1358         <field name = "routing key" type = "shortstr">
1359             Message routing key
1360             <doc>
1361               Specifies the routing key for the message.  The routing key is
1362               used for routing messages depending on the exchange configuration.
1363             </doc>
1364         </field>
1365         <field name = "queue" domain = "queue name"/>
1366     </method>
1367
1368     <method name="bound-ok" synchronous="1" index="23">
1369         <field name="reply code" domain="reply code"/>
1370         <field name="reply text" domain="reply text"/>
1371     </method>
1372
1373   </class>
1374
1375
1376   <class name="queue" handler="channel" index="50">
1377     <!--
1378 ======================================================
1379 ==       QUEUES
1380 ======================================================
1381 -->
1382   work with queues
1383
1384 <doc>
1385   Queues store and forward messages.  Queues can be configured in the server
1386   or created at runtime.  Queues must be attached to at least one exchange
1387   in order to receive messages from publishers.
1388 </doc>
1389     <doc name="grammar">
1390     queue               = C:DECLARE  S:DECLARE-OK
1391                         / C:BIND     S:BIND-OK
1392                         / C:PURGE    S:PURGE-OK
1393                         / C:DELETE   S:DELETE-OK
1394 </doc>
1395     <chassis name="server" implement="MUST"/>
1396     <chassis name="client" implement="MUST"/>
1397     <rule implement="MUST">
1398       <test>amq_queue_33</test>
1399   A server MUST allow any content class to be sent to any queue, in any
1400   mix, and queue and delivery these content classes independently. Note
1401   that all methods that fetch content off queues are specific to a given
1402   content class.
1403 </rule>
1404     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1405     <method name="declare" synchronous="1" index="10">
1406   declare queue, create if needed
1407   <doc>
1408     This method creates or checks a queue.  When creating a new queue
1409     the client can specify various properties that control the durability
1410     of the queue and its contents, and the level of sharing for the queue.
1411   </doc>
1412       <rule implement="MUST">
1413         <test>amq_queue_34</test>
1414     The server MUST create a default binding for a newly-created queue
1415     to the default exchange, which is an exchange of type 'direct'.
1416   </rule>
1417       <rule implement="SHOULD">
1418         <test>amq_queue_35</test>
1419     The server SHOULD support a minimum of 256 queues per virtual host
1420     and ideally, impose no limit except as defined by available resources.
1421   </rule>
1422       <chassis name="server" implement="MUST"/>
1423       <response name="declare-ok"/>
1424       <field name="ticket" domain="access ticket">
1425         <doc>
1426       When a client defines a new queue, this belongs to the access realm
1427       of the ticket used.  All further work done with that queue must be
1428       done with an access ticket for the same realm.
1429     </doc>
1430         <doc>
1431       The client provides a valid access ticket giving "active" access
1432       to the realm in which the queue exists or will be created, or
1433       "passive" access if the if-exists flag is set.
1434     </doc>
1435       </field>
1436       <field name="queue" domain="queue name">
1437         <rule implement="MAY">
1438           <test>amq_queue_10</test>
1439       The queue name MAY be empty, in which case the server MUST create
1440       a new queue with a unique generated name and return this to the
1441       client in the Declare-Ok method.
1442     </rule>
1443         <rule implement="MUST">
1444           <test>amq_queue_32</test>
1445       Queue names starting with "amq." are reserved for predeclared and
1446       standardised server queues.  If the queue name starts with "amq."
1447       and the passive option is zero, the server MUST raise a connection
1448       exception with reply code 403 (access refused).
1449     </rule>
1450         <assert check="regexp" value="^[a-zA-Z0-9-_.:]*$"/>
1451       </field>
1452       <field name="passive" type="bit">
1453     do not create queue
1454     <doc>
1455     If set, the server will not create the queue.  The client can use
1456     this to check whether a queue exists without modifying the server
1457     state.
1458     </doc>
1459         <rule implement="MUST">
1460           <test>amq_queue_05</test>
1461       If set, and the queue does not already exist, the server MUST
1462       respond with a reply code 404 (not found) and raise a channel
1463       exception.
1464     </rule>
1465       </field>
1466       <field name="durable" type="bit">
1467     request a durable queue
1468     <doc>
1469       If set when creating a new queue, the queue will be marked as
1470       durable.  Durable queues remain active when a server restarts.
1471       Non-durable queues (transient queues) are purged if/when a
1472       server restarts.  Note that durable queues do not necessarily
1473       hold persistent messages, although it does not make sense to
1474       send persistent messages to a transient queue.
1475     </doc>
1476         <rule implement="MUST">
1477           <test>amq_queue_03</test>
1478       The server MUST recreate the durable queue after a restart.
1479     </rule>
1480         <rule implement="MUST">
1481           <test>amq_queue_36</test>
1482       The server MUST support both durable and transient queues.
1483     </rule>
1484         <rule implement="MUST">
1485           <test>amq_queue_37</test>
1486       The server MUST ignore the durable field if the queue already
1487       exists.
1488     </rule>
1489       </field>
1490       <field name="exclusive" type="bit">
1491     request an exclusive queue
1492     <doc>
1493       Exclusive queues may only be consumed from by the current connection.
1494       Setting the 'exclusive' flag always implies 'auto-delete'.
1495     </doc>
1496         <rule implement="MUST">
1497           <test>amq_queue_38</test>
1498       The server MUST support both exclusive (private) and non-exclusive
1499       (shared) queues.
1500     </rule>
1501         <rule implement="MUST">
1502           <test>amq_queue_04</test>
1503       The server MUST raise a channel exception if 'exclusive' is specified
1504       and the queue already exists and is owned by a different connection.
1505     </rule>
1506       </field>
1507       <field name="auto delete" type="bit">
1508     auto-delete queue when unused
1509     <doc>
1510       If set, the queue is deleted when all consumers have finished
1511       using it. Last consumer can be cancelled either explicitly or because
1512       its channel is closed. If there was no consumer ever on the queue, it
1513       won't be deleted.
1514     </doc>
1515         <rule implement="SHOULD">
1516           <test>amq_queue_02</test>
1517       The server SHOULD allow for a reasonable delay between the point
1518       when it determines that a queue is not being used (or no longer
1519       used), and the point when it deletes the queue.  At the least it
1520       must allow a client to create a queue and then create a consumer
1521       to read from it, with a small but non-zero delay between these
1522       two actions.  The server should equally allow for clients that may
1523       be disconnected prematurely, and wish to re-consume from the same
1524       queue without losing messages.  We would recommend a configurable
1525       timeout, with a suitable default value being one minute.
1526     </rule>
1527         <rule implement="MUST">
1528           <test>amq_queue_31</test>
1529       The server MUST ignore the auto-delete field if the queue already
1530       exists.
1531     </rule>
1532       </field>
1533   <field name = "nowait" type = "bit">
1534     do not send a reply method
1535     <doc>
1536     If set, the server will not respond to the method. The client should
1537     not wait for a reply method.  If the server could not complete the
1538     method it will raise a channel or connection exception.
1539     </doc>
1540   </field>
1541
1542       <field name="arguments" type="table">
1543     arguments for declaration
1544     <doc>
1545       A set of arguments for the declaration. The syntax and semantics
1546       of these arguments depends on the server implementation.  This
1547       field is ignored if passive is 1.
1548     </doc>
1549       </field>
1550     </method>
1551     <method name="declare-ok" synchronous="1" index="11">
1552   confirms a queue definition
1553   <doc>
1554     This method confirms a Declare method and confirms the name of the
1555     queue, essential for automatically-named queues.
1556   </doc>
1557       <chassis name="client" implement="MUST"/>
1558       <field name="queue" domain="queue name">
1559         <doc>
1560       Reports the name of the queue. If the server generated a queue
1561       name, this field contains that name.
1562     </doc>
1563         <assert check="notnull"/>
1564       </field>
1565       <field name="message count" type="long">
1566     number of messages in queue
1567     <doc>
1568       Reports the number of messages in the queue, which will be zero
1569       for newly-created queues.
1570     </doc>
1571       </field>
1572       <field name="consumer count" type="long">
1573     number of consumers
1574     <doc>
1575       Reports the number of active consumers for the queue. Note that
1576       consumers can suspend activity (Channel.Flow) in which case they
1577       do not appear in this count.
1578     </doc>
1579       </field>
1580     </method>
1581     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1582     <method name="bind" synchronous="1" index="20">
1583   bind queue to an exchange
1584   <doc>
1585     This method binds a queue to an exchange.  Until a queue is
1586     bound it will not receive any messages.  In a classic messaging
1587     model, store-and-forward queues are bound to a dest exchange
1588     and subscription queues are bound to a dest_wild exchange.
1589   </doc>
1590       <rule implement="MUST">
1591         <test>amq_queue_25</test>
1592     A server MUST allow ignore duplicate bindings - that is, two or
1593     more bind methods for a specific queue, with identical arguments
1594     - without treating these as an error.
1595   </rule>
1596       <rule implement="MUST">
1597         <test>amq_queue_39</test>
1598     If a bind fails, the server MUST raise a connection exception.
1599   </rule>
1600       <rule implement="MUST">
1601         <test>amq_queue_12</test>
1602     The server MUST NOT allow a durable queue to bind to a transient
1603     exchange. If the client attempts this the server MUST raise a
1604     channel exception.
1605   </rule>
1606       <rule implement="SHOULD">
1607         <test>amq_queue_13</test>
1608     Bindings for durable queues are automatically durable and the
1609     server SHOULD restore such bindings after a server restart.
1610   </rule>
1611       <rule implement="MUST">
1612         <test>amq_queue_17</test>
1613     If the client attempts to an exchange that was declared as internal,
1614     the server MUST raise a connection exception with reply code 530
1615     (not allowed).
1616   </rule>
1617       <rule implement="SHOULD">
1618         <test>amq_queue_40</test>
1619     The server SHOULD support at least 4 bindings per queue, and
1620     ideally, impose no limit except as defined by available resources.
1621   </rule>
1622       <chassis name="server" implement="MUST"/>
1623       <response name="bind-ok"/>
1624       <field name="ticket" domain="access ticket">
1625         <doc>
1626       The client provides a valid access ticket giving "active"
1627       access rights to the queue's access realm.
1628     </doc>
1629       </field>
1630
1631   <field name = "queue" domain = "queue name">
1632     <doc>
1633       Specifies the name of the queue to bind.  If the queue name is
1634       empty, refers to the current queue for the channel, which is
1635       the last declared queue.
1636     </doc>
1637     <doc name = "rule">
1638       If the client did not previously declare a queue, and the queue
1639       name in this method is empty, the server MUST raise a connection
1640       exception with reply code 530 (not allowed).
1641     </doc>
1642     <doc name = "rule" test = "amq_queue_26">
1643       If the queue does not exist the server MUST raise a channel exception
1644       with reply code 404 (not found).
1645     </doc>
1646   </field>
1647
1648   <field name="exchange" domain="exchange name">
1649           The name of the exchange to bind to.
1650           <rule implement="MUST">
1651           <test>amq_queue_14</test>
1652       If the exchange does not exist the server MUST raise a channel
1653       exception with reply code 404 (not found).
1654     </rule>
1655       </field>
1656       <field name="routing key" type="shortstr">
1657      message routing key
1658     <doc>
1659       Specifies the routing key for the binding.  The routing key is
1660       used for routing messages depending on the exchange configuration.
1661       Not all exchanges use a routing key - refer to the specific
1662       exchange documentation.  If the routing key is empty and the queue
1663       name is empty, the routing key will be the current queue for the
1664       channel, which is the last declared queue.
1665     </doc>
1666   </field>
1667
1668   <field name = "nowait" type = "bit">
1669     do not send a reply method
1670     <doc>
1671     If set, the server will not respond to the method. The client should
1672     not wait for a reply method.  If the server could not complete the
1673     method it will raise a channel or connection exception.
1674     </doc>
1675   </field>
1676
1677   <field name="arguments" type="table">
1678     arguments for binding
1679     <doc>
1680       A set of arguments for the binding.  The syntax and semantics of
1681       these arguments depends on the exchange class.
1682     </doc>
1683       </field>
1684     </method>
1685     <method name="bind-ok" synchronous="1" index="21">
1686   confirm bind successful
1687   <doc>
1688     This method confirms that the bind was successful.
1689   </doc>
1690       <chassis name="client" implement="MUST"/>
1691     </method>
1692     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1693     <method name="purge" synchronous="1" index="30">
1694   purge a queue
1695   <doc>
1696     This method removes all messages from a queue.  It does not cancel
1697     consumers.  Purged messages are deleted without any formal "undo"
1698     mechanism.
1699   </doc>
1700       <rule implement="MUST">
1701         <test>amq_queue_15</test>
1702     A call to purge MUST result in an empty queue.
1703   </rule>
1704       <rule implement="MUST">
1705         <test>amq_queue_41</test>
1706     On transacted channels the server MUST not purge messages that have
1707     already been sent to a client but not yet acknowledged.
1708   </rule>
1709       <rule implement="MAY">
1710         <test>amq_queue_42</test>
1711     The server MAY implement a purge queue or log that allows system
1712     administrators to recover accidentally-purged messages.  The server
1713     SHOULD NOT keep purged messages in the same storage spaces as the
1714     live messages since the volumes of purged messages may get very
1715     large.
1716   </rule>
1717       <chassis name="server" implement="MUST"/>
1718       <response name="purge-ok"/>
1719       <field name="ticket" domain="access ticket">
1720         <doc>
1721       The access ticket must be for the access realm that holds the
1722       queue.
1723     </doc>
1724         <rule implement="MUST">
1725       The client MUST provide a valid access ticket giving "read" access
1726       rights to the queue's access realm.  Note that purging a queue is
1727       equivalent to reading all messages and discarding them.
1728     </rule>
1729       </field>
1730   <field name = "queue" domain = "queue name">
1731     <doc>
1732       Specifies the name of the queue to purge.  If the queue name is
1733       empty, refers to the current queue for the channel, which is
1734       the last declared queue.
1735     </doc>
1736     <doc name = "rule">
1737       If the client did not previously declare a queue, and the queue
1738       name in this method is empty, the server MUST raise a connection
1739       exception with reply code 530 (not allowed).
1740     </doc>
1741     <doc name = "rule" test = "amq_queue_16">
1742       The queue must exist. Attempting to purge a non-existing queue
1743       causes a channel exception.
1744     </doc>
1745   </field>
1746
1747   <field name = "nowait" type = "bit">
1748     do not send a reply method
1749     <doc>
1750     If set, the server will not respond to the method. The client should
1751     not wait for a reply method.  If the server could not complete the
1752     method it will raise a channel or connection exception.
1753     </doc>
1754   </field>
1755     </method>
1756     <method name="purge-ok" synchronous="1" index="31">
1757   confirms a queue purge
1758   <doc>
1759     This method confirms the purge of a queue.
1760   </doc>
1761       <chassis name="client" implement="MUST"/>
1762       <field name="message count" type="long">
1763     number of messages purged
1764     <doc>
1765       Reports the number of messages purged.
1766     </doc>
1767       </field>
1768     </method>
1769     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1770     <method name="delete" synchronous="1" index="40">
1771   delete a queue
1772   <doc>
1773     This method deletes a queue.  When a queue is deleted any pending
1774     messages are sent to a dead-letter queue if this is defined in the
1775     server configuration, and all consumers on the queue are cancelled.
1776   </doc>
1777       <rule implement="SHOULD">
1778         <test>amq_queue_43</test>
1779     The server SHOULD use a dead-letter queue to hold messages that
1780     were pending on a deleted queue, and MAY provide facilities for
1781     a system administrator to move these messages back to an active
1782     queue.
1783   </rule>
1784       <chassis name="server" implement="MUST"/>
1785       <response name="delete-ok"/>
1786       <field name="ticket" domain="access ticket">
1787         <doc>
1788       The client provides a valid access ticket giving "active"
1789       access rights to the queue's access realm.
1790     </doc>
1791       </field>
1792
1793   <field name = "queue" domain = "queue name">
1794     <doc>
1795       Specifies the name of the queue to delete. If the queue name is
1796       empty, refers to the current queue for the channel, which is the
1797       last declared queue.
1798     </doc>
1799     <doc name = "rule">
1800       If the client did not previously declare a queue, and the queue
1801       name in this method is empty, the server MUST raise a connection
1802       exception with reply code 530 (not allowed).
1803     </doc>
1804     <doc name = "rule" test = "amq_queue_21">
1805       The queue must exist. Attempting to delete a non-existing queue
1806       causes a channel exception.
1807     </doc>
1808   </field>
1809
1810       <field name="if unused" type="bit">
1811     delete only if unused
1812     <doc>
1813       If set, the server will only delete the queue if it has no
1814       consumers. If the queue has consumers the server does does not
1815       delete it but raises a channel exception instead.
1816     </doc>
1817         <rule implement="MUST">
1818           <test>amq_queue_29</test>
1819           <test>amq_queue_30</test>
1820       The server MUST respect the if-unused flag when deleting a queue.
1821     </rule>
1822       </field>
1823       <field name="if empty" type="bit">
1824     delete only if empty
1825         <test>amq_queue_27</test>
1826         <doc>
1827       If set, the server will only delete the queue if it has no
1828       messages. If the queue is not empty the server raises a channel
1829       exception.
1830     </doc>
1831       </field>
1832   <field name = "nowait" type = "bit">
1833     do not send a reply method
1834     <doc>
1835     If set, the server will not respond to the method. The client should
1836     not wait for a reply method.  If the server could not complete the
1837     method it will raise a channel or connection exception.
1838     </doc>
1839   </field>
1840     </method>
1841
1842     <method name="delete-ok" synchronous="1" index="41">
1843   confirm deletion of a queue
1844   <doc>
1845     This method confirms the deletion of a queue.
1846   </doc>
1847       <chassis name="client" implement="MUST"/>
1848       <field name="message count" type="long">
1849     number of messages purged
1850     <doc>
1851       Reports the number of messages purged.
1852     </doc>
1853       </field>
1854     </method>
1855   </class>
1856   <class name="basic" handler="channel" index="60">
1857     <!--
1858 ======================================================
1859 ==       BASIC MIDDLEWARE
1860 ======================================================
1861 -->
1862   work with basic content
1863 <doc>
1864   The Basic class provides methods that support an industry-standard
1865   messaging model.
1866 </doc>
1867
1868 <doc name = "grammar">
1869     basic               = C:QOS S:QOS-OK
1870                         / C:CONSUME S:CONSUME-OK
1871                         / C:CANCEL S:CANCEL-OK
1872                         / C:PUBLISH content
1873                         / S:RETURN content
1874                         / S:DELIVER content
1875                         / C:GET ( S:GET-OK content / S:GET-EMPTY )
1876                         / C:ACK
1877                         / C:REJECT
1878 </doc>
1879
1880 <chassis name = "server" implement = "MUST" />
1881 <chassis name = "client" implement = "MAY"  />
1882
1883 <doc name = "rule" test = "amq_basic_08">
1884   The server SHOULD respect the persistent property of basic messages
1885   and SHOULD make a best-effort to hold persistent basic messages on a
1886   reliable storage mechanism.
1887 </doc>
1888 <doc name = "rule" test = "amq_basic_09">
1889   The server MUST NOT discard a persistent basic message in case of a
1890   queue overflow. The server MAY use the Channel.Flow method to slow
1891   or stop a basic message publisher when necessary.
1892 </doc>
1893 <doc name = "rule" test = "amq_basic_10">
1894   The server MAY overflow non-persistent basic messages to persistent
1895   storage and MAY discard or dead-letter non-persistent basic messages
1896   on a priority basis if the queue size exceeds some configured limit.
1897 </doc>
1898 <doc name = "rule" test = "amq_basic_11">
1899   The server MUST implement at least 2 priority levels for basic
1900   messages, where priorities 0-4 and 5-9 are treated as two distinct
1901   levels. The server MAY implement up to 10 priority levels.
1902 </doc>
1903 <doc name = "rule" test = "amq_basic_12">
1904   The server MUST deliver messages of the same priority in order
1905   irrespective of their individual persistence.
1906 </doc>
1907 <doc name = "rule" test = "amq_basic_13">
1908   The server MUST support both automatic and explicit acknowledgements
1909   on Basic content.
1910 </doc>
1911
1912 <!--  These are the properties for a Basic content  -->
1913
1914 <field name = "content type" type = "shortstr">
1915     MIME content type
1916 </field>
1917 <field name = "content encoding" type = "shortstr">
1918     MIME content encoding
1919 </field>
1920 <field name = "headers" type = "table">
1921     Message header field table
1922 </field>
1923 <field name = "delivery mode" type = "octet">
1924     Non-persistent (1) or persistent (2)
1925 </field>
1926 <field name = "priority" type = "octet">
1927     The message priority, 0 to 9
1928 </field>
1929 <field name = "correlation id" type = "shortstr">
1930     The application correlation identifier
1931 </field>
1932 <field name = "reply to" type = "shortstr">
1933     The destination to reply to
1934 </field>
1935 <field name = "expiration" type = "shortstr">
1936     Message expiration specification
1937 </field>
1938 <field name = "message id" type = "shortstr">
1939     The application message identifier
1940 </field>
1941 <field name = "timestamp" type = "timestamp">
1942     The message timestamp
1943 </field>
1944 <field name = "type" type = "shortstr">
1945     The message type name
1946 </field>
1947 <field name = "user id" type = "shortstr">
1948     The creating user id
1949 </field>
1950 <field name = "app id" type = "shortstr">
1951     The creating application id
1952 </field>
1953 <field name = "cluster id" type = "shortstr">
1954     Intra-cluster routing identifier
1955 </field>
1956
1957
1958 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1959
1960 <method name = "qos" synchronous = "1" index = "10">
1961   specify quality of service
1962   <doc>
1963     This method requests a specific quality of service.  The QoS can
1964     be specified for the current channel or for all channels on the
1965     connection.  The particular properties and semantics of a qos method
1966     always depend on the content class semantics.  Though the qos method
1967     could in principle apply to both peers, it is currently meaningful
1968     only for the server.
1969   </doc>
1970   <chassis name = "server" implement = "MUST" />
1971   <response name = "qos-ok" />
1972
1973   <field name = "prefetch size" type = "long">
1974     prefetch window in octets
1975     <doc>
1976       The client can request that messages be sent in advance so that
1977       when the client finishes processing a message, the following
1978       message is already held locally, rather than needing to be sent
1979       down the channel.  Prefetching gives a performance improvement.
1980       This field specifies the prefetch window size in octets.  The
1981       server will send a message in advance if it is equal to or
1982       smaller in size than the available prefetch size (and also falls
1983       into other prefetch limits). May be set to zero, meaning "no
1984       specific limit", although other prefetch limits may still apply.
1985       The prefetch-size is ignored if the no-ack option is set.
1986     </doc>
1987     <doc name = "rule" test = "amq_basic_17">
1988       The server MUST ignore this setting when the client is not
1989       processing any messages - i.e. the prefetch size does not limit
1990       the transfer of single messages to a client, only the sending in
1991       advance of more messages while the client still has one or more
1992       unacknowledged messages.
1993    </doc>
1994   </field>
1995
1996   <field name = "prefetch count" type = "short">
1997     prefetch window in messages
1998     <doc>
1999       Specifies a prefetch window in terms of whole messages.  This
2000       field may be used in combination with the prefetch-size field;
2001       a message will only be sent in advance if both prefetch windows
2002       (and those at the channel and connection level) allow it.
2003       The prefetch-count is ignored if the no-ack option is set.
2004     </doc>
2005     <doc name = "rule" test = "amq_basic_18">
2006       The server MAY send less data in advance than allowed by the
2007       client's specified prefetch windows but it MUST NOT send more.
2008     </doc>
2009   </field>
2010
2011   <field name = "global" type = "bit">
2012     apply to entire connection
2013     <doc>
2014       By default the QoS settings apply to the current channel only.  If
2015       this field is set, they are applied to the entire connection.
2016     </doc>
2017   </field>
2018 </method>
2019
2020 <method name = "qos-ok" synchronous = "1" index = "11">
2021   confirm the requested qos
2022   <doc>
2023     This method tells the client that the requested QoS levels could
2024     be handled by the server.  The requested QoS applies to all active
2025     consumers until a new QoS is defined.
2026   </doc>
2027   <chassis name = "client" implement = "MUST" />
2028 </method>
2029
2030 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2031
2032 <method name = "consume" synchronous = "1" index = "20">
2033   start a queue consumer
2034   <doc>
2035     This method asks the server to start a "consumer", which is a
2036     transient request for messages from a specific queue. Consumers
2037     last as long as the channel they were created on, or until the
2038     client cancels them.
2039   </doc>
2040   <doc name = "rule" test = "amq_basic_01">
2041     The server SHOULD support at least 16 consumers per queue, unless
2042     the queue was declared as private, and ideally, impose no limit
2043     except as defined by available resources.
2044   </doc>
2045   <chassis name = "server" implement = "MUST" />
2046   <response name = "consume-ok" />
2047
2048   <field name = "ticket" domain = "access ticket">
2049     <doc name = "rule">
2050       The client MUST provide a valid access ticket giving "read" access
2051       rights to the realm for the queue.
2052     </doc>
2053   </field>
2054
2055   <field name = "queue" domain = "queue name">
2056     <doc>
2057       Specifies the name of the queue to consume from.  If the queue name
2058       is null, refers to the current queue for the channel, which is the
2059       last declared queue.
2060     </doc>
2061     <doc name = "rule">
2062       If the client did not previously declare a queue, and the queue name
2063       in this method is empty, the server MUST raise a connection exception
2064       with reply code 530 (not allowed).
2065     </doc>
2066   </field>
2067
2068   <field name = "consumer tag" domain = "consumer tag">
2069     <doc>
2070       Specifies the identifier for the consumer. The consumer tag is
2071       local to a connection, so two clients can use the same consumer
2072       tags. If this field is empty the server will generate a unique
2073       tag.
2074     </doc>
2075     <doc name = "rule" test = "todo">
2076       The tag MUST NOT refer to an existing consumer. If the client
2077       attempts to create two consumers with the same non-empty tag
2078       the server MUST raise a connection exception with reply code
2079       530 (not allowed).
2080     </doc>
2081   </field>
2082
2083   <field name = "no local" domain = "no local" />
2084
2085   <field name = "no ack" domain = "no ack" />
2086
2087   <field name = "exclusive" type = "bit">
2088     request exclusive access
2089     <doc>
2090       Request exclusive consumer access, meaning only this consumer can
2091       access the queue.
2092     </doc>
2093     <doc name = "rule" test = "amq_basic_02">
2094       If the server cannot grant exclusive access to the queue when asked,
2095       - because there are other consumers active - it MUST raise a channel
2096       exception with return code 403 (access refused).
2097     </doc>
2098   </field>
2099
2100   <field name = "nowait" type = "bit">
2101     do not send a reply method
2102     <doc>
2103     If set, the server will not respond to the method. The client should
2104     not wait for a reply method.  If the server could not complete the
2105     method it will raise a channel or connection exception.
2106     </doc>
2107   </field>
2108
2109     <field name="arguments" type="table" label="arguments for consuming">
2110   <doc>
2111     A set of arguments for the consume. The syntax and semantics
2112     of these arguments depends on the server implementation.  This
2113     field is ignored if passive is 1.
2114   </doc>
2115     </field>
2116 </method>
2117
2118 <method name = "consume-ok" synchronous = "1" index = "21">
2119   confirm a new consumer
2120   <doc>
2121     The server provides the client with a consumer tag, which is used
2122     by the client for methods called on the consumer at a later stage.
2123   </doc>
2124   <chassis name = "client" implement = "MUST" />
2125
2126   <field name = "consumer tag" domain = "consumer tag">
2127     <doc>
2128       Holds the consumer tag specified by the client or provided by
2129       the server.
2130     </doc>
2131   </field>
2132 </method>
2133
2134
2135 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2136
2137 <method name = "cancel" synchronous = "1" index = "30">
2138   end a queue consumer
2139   <doc test = "amq_basic_04">
2140     This method cancels a consumer. This does not affect already
2141     delivered messages, but it does mean the server will not send any
2142     more messages for that consumer.  The client may receive an
2143     abitrary number of messages in between sending the cancel method
2144     and receiving the cancel-ok reply.
2145   </doc>
2146   <doc name = "rule" test = "todo">
2147     If the queue no longer exists when the client sends a cancel command,
2148     or the consumer has been cancelled for other reasons, this command
2149     has no effect.
2150   </doc>
2151   <chassis name = "server" implement = "MUST" />
2152   <response name = "cancel-ok" />
2153
2154   <field name = "consumer tag" domain = "consumer tag" />
2155
2156   <field name = "nowait" type = "bit">
2157     do not send a reply method
2158     <doc>
2159     If set, the server will not respond to the method. The client should
2160     not wait for a reply method.  If the server could not complete the
2161     method it will raise a channel or connection exception.
2162     </doc>
2163   </field>
2164 </method>
2165
2166 <method name = "cancel-ok" synchronous = "1" index = "31">
2167   confirm a cancelled consumer
2168   <doc>
2169     This method confirms that the cancellation was completed.
2170   </doc>
2171   <chassis name = "client" implement = "MUST" />
2172
2173   <field name = "consumer tag" domain = "consumer tag" />
2174 </method>
2175
2176
2177 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2178
2179 <method name = "publish" content = "1" index = "40">
2180   publish a message
2181   <doc>
2182     This method publishes a message to a specific exchange. The message
2183     will be routed to queues as defined by the exchange configuration
2184     and distributed to any active consumers when the transaction, if any,
2185     is committed.
2186   </doc>
2187   <chassis name = "server" implement = "MUST" />
2188
2189   <field name = "ticket" domain = "access ticket">
2190     <doc name = "rule">
2191       The client MUST provide a valid access ticket giving "write"
2192       access rights to the access realm for the exchange.
2193     </doc>
2194   </field>
2195
2196   <field name = "exchange" domain = "exchange name">
2197     <doc>
2198       Specifies the name of the exchange to publish to.  The exchange
2199       name can be empty, meaning the default exchange.  If the exchange
2200       name is specified, and that exchange does not exist, the server
2201       will raise a channel exception.
2202     </doc>
2203     <doc name = "rule" test = "amq_basic_06">
2204       The server MUST accept a blank exchange name to mean the default
2205       exchange.
2206     </doc>
2207     <doc name = "rule" test = "amq_basic_14">
2208       If the exchange was declared as an internal exchange, the server
2209       MUST raise a channel exception with a reply code 403 (access
2210       refused).
2211     </doc>
2212     <doc name = "rule" test = "amq_basic_15">
2213       The exchange MAY refuse basic content in which case it MUST raise
2214       a channel exception with reply code 540 (not implemented).
2215     </doc>
2216   </field>
2217
2218   <field name = "routing key" type = "shortstr">
2219      Message routing key
2220     <doc>
2221       Specifies the routing key for the message.  The routing key is
2222       used for routing messages depending on the exchange configuration.
2223     </doc>
2224   </field>
2225
2226   <field name = "mandatory" type = "bit">
2227     indicate mandatory routing
2228     <doc>
2229       This flag tells the server how to react if the message cannot be
2230       routed to a queue.  If this flag is set, the server will return an
2231       unroutable message with a Return method.  If this flag is zero, the
2232       server silently drops the message.
2233     </doc>
2234     <doc name = "rule" test = "amq_basic_07">
2235       The server SHOULD implement the mandatory flag.
2236     </doc>
2237   </field>
2238
2239   <field name = "immediate" type = "bit">
2240     request immediate delivery
2241     <doc>
2242       This flag tells the server how to react if the message cannot be
2243       routed to a queue consumer immediately.  If this flag is set, the
2244       server will return an undeliverable message with a Return method.
2245       If this flag is zero, the server will queue the message, but with
2246       no guarantee that it will ever be consumed.
2247     </doc>
2248     <doc name = "rule" test = "amq_basic_16">
2249       The server SHOULD implement the immediate flag.
2250     </doc>
2251   </field>
2252 </method>
2253
2254 <method name = "return" content = "1" index = "50">
2255   return a failed message
2256   <doc>
2257     This method returns an undeliverable message that was published
2258     with the "immediate" flag set, or an unroutable message published
2259     with the "mandatory" flag set. The reply code and text provide
2260     information about the reason that the message was undeliverable.
2261   </doc>
2262   <chassis name = "client" implement = "MUST" />
2263
2264   <field name = "reply code" domain = "reply code" />
2265   <field name = "reply text" domain = "reply text" />
2266
2267   <field name = "exchange" domain = "exchange name">
2268     <doc>
2269       Specifies the name of the exchange that the message was
2270       originally published to.
2271     </doc>
2272   </field>
2273
2274   <field name = "routing key" type = "shortstr">
2275      Message routing key
2276     <doc>
2277       Specifies the routing key name specified when the message was
2278       published.
2279     </doc>
2280   </field>
2281 </method>
2282
2283
2284 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2285
2286 <method name = "deliver" content = "1" index = "60">
2287   notify the client of a consumer message
2288   <doc>
2289     This method delivers a message to the client, via a consumer.  In
2290     the asynchronous message delivery model, the client starts a
2291     consumer using the Consume method, then the server responds with
2292     Deliver methods as and when messages arrive for that consumer.
2293   </doc>
2294   <doc name = "rule" test = "amq_basic_19">
2295     The server SHOULD track the number of times a message has been
2296     delivered to clients and when a message is redelivered a certain
2297     number of times - e.g. 5 times - without being acknowledged, the
2298     server SHOULD consider the message to be unprocessable (possibly
2299     causing client applications to abort), and move the message to a
2300     dead letter queue.
2301   </doc>
2302   <chassis name = "client" implement = "MUST" />
2303
2304   <field name = "consumer tag" domain = "consumer tag" />
2305
2306   <field name = "delivery tag" domain = "delivery tag" />
2307
2308   <field name = "redelivered" domain = "redelivered" />
2309
2310   <field name = "exchange" domain = "exchange name">
2311     <doc>
2312       Specifies the name of the exchange that the message was
2313       originally published to.
2314     </doc>
2315   </field>
2316
2317   <field name = "routing key" type = "shortstr">
2318      Message routing key
2319     <doc>
2320       Specifies the routing key name specified when the message was
2321       published.
2322     </doc>
2323   </field>
2324 </method>
2325
2326
2327 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2328
2329 <method name = "get" synchronous = "1" index = "70">
2330   direct access to a queue
2331   <doc>
2332     This method provides a direct access to the messages in a queue
2333     using a synchronous dialogue that is designed for specific types of
2334     application where synchronous functionality is more important than
2335     performance.
2336   </doc>
2337   <response name = "get-ok" />
2338   <response name = "get-empty" />
2339   <chassis name = "server" implement = "MUST" />
2340
2341   <field name = "ticket" domain = "access ticket">
2342     <doc name = "rule">
2343       The client MUST provide a valid access ticket giving "read"
2344       access rights to the realm for the queue.
2345     </doc>
2346   </field>
2347
2348   <field name = "queue" domain = "queue name">
2349     <doc>
2350       Specifies the name of the queue to consume from.  If the queue name
2351       is null, refers to the current queue for the channel, which is the
2352       last declared queue.
2353     </doc>
2354     <doc name = "rule">
2355       If the client did not previously declare a queue, and the queue name
2356       in this method is empty, the server MUST raise a connection exception
2357       with reply code 530 (not allowed).
2358     </doc>
2359   </field>
2360
2361   <field name = "no ack" domain = "no ack" />
2362 </method>
2363
2364 <method name = "get-ok" synchronous = "1" content = "1" index = "71">
2365   provide client with a message
2366   <doc>
2367     This method delivers a message to the client following a get
2368     method.  A message delivered by 'get-ok' must be acknowledged
2369     unless the no-ack option was set in the get method.
2370   </doc>
2371   <chassis name = "client" implement = "MAY" />
2372
2373   <field name = "delivery tag" domain = "delivery tag" />
2374
2375   <field name = "redelivered"  domain = "redelivered"  />
2376
2377   <field name = "exchange" domain = "exchange name">
2378     <doc>
2379       Specifies the name of the exchange that the message was originally
2380       published to.  If empty, the message was published to the default
2381       exchange.
2382     </doc>
2383   </field>
2384
2385   <field name = "routing key" type = "shortstr">
2386      Message routing key
2387     <doc>
2388       Specifies the routing key name specified when the message was
2389       published.
2390     </doc>
2391   </field>
2392
2393   <field name = "message count" type = "long" >
2394     number of messages pending
2395     <doc>
2396       This field reports the number of messages pending on the queue,
2397       excluding the message being delivered.  Note that this figure is
2398       indicative, not reliable, and can change arbitrarily as messages
2399       are added to the queue and removed by other clients.
2400     </doc>
2401   </field>
2402 </method>
2403
2404
2405 <method name = "get-empty" synchronous = "1" index = "72">
2406   indicate no messages available
2407   <doc>
2408     This method tells the client that the queue has no messages
2409     available for the client.
2410   </doc>
2411   <chassis name = "client" implement = "MAY" />
2412
2413   <field name = "cluster id" type = "shortstr">
2414      Cluster id
2415     <doc>
2416       For use by cluster applications, should not be used by
2417       client applications.
2418     </doc>
2419   </field>
2420 </method>
2421
2422 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2423
2424 <method name = "ack" index = "80">
2425   acknowledge one or more messages
2426   <doc>
2427     This method acknowledges one or more messages delivered via the
2428     Deliver or Get-Ok methods.  The client can ask to confirm a
2429     single message or a set of messages up to and including a specific
2430     message.
2431   </doc>
2432   <chassis name = "server" implement = "MUST" />
2433   <field name = "delivery tag" domain = "delivery tag" />
2434
2435   <field name = "multiple" type = "bit">
2436     acknowledge multiple messages
2437     <doc>
2438       If set to 1, the delivery tag is treated as "up to and including",
2439       so that the client can acknowledge multiple messages with a single
2440       method.  If set to zero, the delivery tag refers to a single
2441       message.  If the multiple field is 1, and the delivery tag is zero,
2442       tells the server to acknowledge all outstanding mesages.
2443     </doc>
2444     <doc name = "rule" test = "amq_basic_20">
2445       The server MUST validate that a non-zero delivery-tag refers to an
2446       delivered message, and raise a channel exception if this is not the
2447       case.
2448     </doc>
2449   </field>
2450 </method>
2451
2452 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2453
2454 <method name = "reject" index = "90">
2455   reject an incoming message
2456   <doc>
2457     This method allows a client to reject a message.  It can be used to
2458     interrupt and cancel large incoming messages, or return untreatable
2459     messages to their original queue.
2460   </doc>
2461   <doc name = "rule" test = "amq_basic_21">
2462     The server SHOULD be capable of accepting and process the Reject
2463     method while sending message content with a Deliver or Get-Ok
2464     method.  I.e. the server should read and process incoming methods
2465     while sending output frames.  To cancel a partially-send content,
2466     the server sends a content body frame of size 1 (i.e. with no data
2467     except the frame-end octet).
2468   </doc>
2469   <doc name = "rule" test = "amq_basic_22">
2470     The server SHOULD interpret this method as meaning that the client
2471     is unable to process the message at this time.
2472   </doc>
2473   <doc name = "rule">
2474     A client MUST NOT use this method as a means of selecting messages
2475     to process.  A rejected message MAY be discarded or dead-lettered,
2476     not necessarily passed to another client.
2477   </doc>
2478   <chassis name = "server" implement = "MUST" />
2479
2480   <field name = "delivery tag" domain = "delivery tag" />
2481
2482   <field name = "requeue" type = "bit">
2483     requeue the message
2484     <doc>
2485       If this field is zero, the message will be discarded.  If this bit
2486       is 1, the server will attempt to requeue the message.
2487     </doc>
2488     <doc name = "rule" test = "amq_basic_23">
2489       The server MUST NOT deliver the message to the same client within
2490       the context of the current channel.  The recommended strategy is
2491       to attempt to deliver the message to an alternative consumer, and
2492       if that is not possible, to move the message to a dead-letter
2493       queue.  The server MAY use more sophisticated tracking to hold
2494       the message on the queue and redeliver it to the same client at
2495       a later stage.
2496     </doc>
2497   </field>
2498 </method>
2499
2500 <method name = "recover" index = "100">
2501   redeliver unacknowledged messages
2502   <doc>
2503     This method asks the broker to redeliver all unacknowledged messages on a
2504     specified channel. Zero or more messages may be redelivered.  This method
2505     is only allowed on non-transacted channels.
2506   </doc>
2507   <chassis name = "server" implement = "MUST" />
2508
2509   <field name = "requeue" type = "bit">
2510     requeue the message
2511     <doc>
2512       If this field is zero, the message will be redelivered to the original
2513       recipient.  If this bit is 1, the server will attempt to requeue the
2514       message, potentially then delivering it to an alternative subscriber.
2515     </doc>
2516   </field>
2517   <doc name="rule">
2518     The server MUST set the redelivered flag on all messages that are resent.
2519   </doc>
2520   <doc name="rule">
2521     The server MUST raise a channel exception if this is called on a
2522     transacted channel.
2523   </doc>
2524     <response name="recover-ok"/>
2525   </method>
2526   <method name="recover-ok" synchronous="1" index="101">
2527         confirm a successful recover
2528         <doc>
2529           This method confirms to the client that the recover succeeded.
2530           Note that if an recover fails, the server raises a channel exception.
2531     </doc>
2532     <chassis name="client" implement="MUST"/>
2533   </method>
2534
2535 </class>
2536
2537
2538   <class name="file" handler="channel" index="70">
2539     <!--
2540 ======================================================
2541 ==      FILE TRANSFER
2542 ======================================================
2543 -->
2544   work with file content
2545 <doc>
2546   The file class provides methods that support reliable file transfer.
2547   File messages have a specific set of properties that are required for
2548   interoperability with file transfer applications. File messages and
2549   acknowledgements are subject to channel transactions.  Note that the
2550   file class does not provide message browsing methods; these are not
2551   compatible with the staging model.  Applications that need browsable
2552   file transfer should use Basic content and the Basic class.
2553 </doc>
2554
2555 <doc name = "grammar">
2556     file                = C:QOS S:QOS-OK
2557                         / C:CONSUME S:CONSUME-OK
2558                         / C:CANCEL S:CANCEL-OK
2559                         / C:OPEN S:OPEN-OK C:STAGE content
2560                         / S:OPEN C:OPEN-OK S:STAGE content
2561                         / C:PUBLISH
2562                         / S:DELIVER
2563                         / S:RETURN
2564                         / C:ACK
2565                         / C:REJECT
2566 </doc>
2567
2568 <chassis name = "server" implement = "MAY" />
2569 <chassis name = "client" implement = "MAY" />
2570
2571 <doc name = "rule">
2572   The server MUST make a best-effort to hold file messages on a
2573   reliable storage mechanism.
2574 </doc>
2575 <doc name = "rule">
2576   The server MUST NOT discard a file message in case of a queue
2577   overflow. The server MUST use the Channel.Flow method to slow or stop
2578   a file message publisher when necessary.
2579 </doc>
2580 <doc name = "rule">
2581   The server MUST implement at least 2 priority levels for file
2582   messages, where priorities 0-4 and 5-9 are treated as two distinct
2583   levels. The server MAY implement up to 10 priority levels.
2584 </doc>
2585 <doc name = "rule">
2586   The server MUST support both automatic and explicit acknowledgements
2587   on file content.
2588 </doc>
2589
2590 <!--  These are the properties for a File content  -->
2591
2592 <field name = "content type" type = "shortstr">
2593     MIME content type
2594 </field>
2595 <field name = "content encoding" type = "shortstr">
2596     MIME content encoding
2597 </field>
2598 <field name = "headers" type = "table">
2599     Message header field table
2600 </field>
2601 <field name = "priority" type = "octet">
2602     The message priority, 0 to 9
2603 </field>
2604 <field name = "reply to" type = "shortstr">
2605     The destination to reply to
2606 </field>
2607 <field name = "message id" type = "shortstr">
2608     The application message identifier
2609 </field>
2610 <field name = "filename" type = "shortstr">
2611     The message filename
2612 </field>
2613 <field name = "timestamp" type = "timestamp">
2614     The message timestamp
2615 </field>
2616 <field name = "cluster id" type = "shortstr">
2617     Intra-cluster routing identifier
2618 </field>
2619
2620
2621 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2622
2623 <method name = "qos" synchronous = "1" index = "10">
2624   specify quality of service
2625   <doc>
2626     This method requests a specific quality of service.  The QoS can
2627     be specified for the current channel or for all channels on the
2628     connection.  The particular properties and semantics of a qos method
2629     always depend on the content class semantics.  Though the qos method
2630     could in principle apply to both peers, it is currently meaningful
2631     only for the server.
2632   </doc>
2633   <chassis name = "server" implement = "MUST" />
2634   <response name = "qos-ok" />
2635
2636   <field name = "prefetch size" type = "long">
2637     prefetch window in octets
2638     <doc>
2639       The client can request that messages be sent in advance so that
2640       when the client finishes processing a message, the following
2641       message is already held locally, rather than needing to be sent
2642       down the channel.  Prefetching gives a performance improvement.
2643       This field specifies the prefetch window size in octets. May be
2644       set to zero, meaning "no specific limit".  Note that other
2645       prefetch limits may still apply. The prefetch-size is ignored
2646       if the no-ack option is set.
2647     </doc>
2648   </field>
2649
2650   <field name = "prefetch count" type = "short">
2651     prefetch window in messages
2652     <doc>
2653       Specifies a prefetch window in terms of whole messages.  This
2654       is compatible with some file API implementations.  This field
2655       may be used in combination with the prefetch-size field; a
2656       message will only be sent in advance if both prefetch windows
2657       (and those at the channel and connection level) allow it.
2658       The prefetch-count is ignored if the no-ack option is set.
2659     </doc>
2660     <doc name = "rule">
2661       The server MAY send less data in advance than allowed by the
2662       client's specified prefetch windows but it MUST NOT send more.
2663     </doc>
2664   </field>
2665
2666   <field name = "global" type = "bit">
2667     apply to entire connection
2668     <doc>
2669       By default the QoS settings apply to the current channel only.  If
2670       this field is set, they are applied to the entire connection.
2671     </doc>
2672   </field>
2673 </method>
2674
2675 <method name = "qos-ok" synchronous = "1" index = "11">
2676   confirm the requested qos
2677   <doc>
2678     This method tells the client that the requested QoS levels could
2679     be handled by the server.  The requested QoS applies to all active
2680     consumers until a new QoS is defined.
2681   </doc>
2682   <chassis name = "client" implement = "MUST" />
2683 </method>
2684
2685 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2686
2687 <method name = "consume" synchronous = "1" index = "20">
2688   start a queue consumer
2689   <doc>
2690     This method asks the server to start a "consumer", which is a
2691     transient request for messages from a specific queue. Consumers
2692     last as long as the channel they were created on, or until the
2693     client cancels them.
2694   </doc>
2695   <doc name = "rule">
2696     The server SHOULD support at least 16 consumers per queue, unless
2697     the queue was declared as private, and ideally, impose no limit
2698     except as defined by available resources.
2699   </doc>
2700   <chassis name = "server" implement = "MUST" />
2701   <response name = "consume-ok" />
2702
2703   <field name = "ticket" domain = "access ticket">
2704     <doc name = "rule">
2705       The client MUST provide a valid access ticket giving "read" access
2706       rights to the realm for the queue.
2707     </doc>
2708   </field>
2709
2710   <field name = "queue" domain = "queue name">
2711     <doc>
2712       Specifies the name of the queue to consume from.  If the queue name
2713       is null, refers to the current queue for the channel, which is the
2714       last declared queue.
2715     </doc>
2716     <doc name = "rule">
2717       If the client did not previously declare a queue, and the queue name
2718       in this method is empty, the server MUST raise a connection exception
2719       with reply code 530 (not allowed).
2720     </doc>
2721   </field>
2722
2723   <field name = "consumer tag" domain = "consumer tag">
2724     <doc>
2725       Specifies the identifier for the consumer. The consumer tag is
2726       local to a connection, so two clients can use the same consumer
2727       tags. If this field is empty the server will generate a unique
2728       tag.
2729     </doc>
2730     <doc name = "rule" test = "todo">
2731       The tag MUST NOT refer to an existing consumer. If the client
2732       attempts to create two consumers with the same non-empty tag
2733       the server MUST raise a connection exception with reply code
2734       530 (not allowed).
2735     </doc>
2736   </field>
2737
2738   <field name = "no local" domain = "no local" />
2739
2740   <field name = "no ack" domain = "no ack" />
2741
2742   <field name = "exclusive" type = "bit">
2743     request exclusive access
2744     <doc>
2745       Request exclusive consumer access, meaning only this consumer can
2746       access the queue.
2747     </doc>
2748     <doc name = "rule" test = "amq_file_00">
2749       If the server cannot grant exclusive access to the queue when asked,
2750       - because there are other consumers active - it MUST raise a channel
2751       exception with return code 405 (resource locked).
2752     </doc>
2753   </field>
2754
2755   <field name = "nowait" type = "bit">
2756     do not send a reply method
2757     <doc>
2758     If set, the server will not respond to the method. The client should
2759     not wait for a reply method.  If the server could not complete the
2760     method it will raise a channel or connection exception.
2761     </doc>
2762   </field>
2763 </method>
2764
2765 <method name = "consume-ok" synchronous = "1" index = "21">
2766   confirm a new consumer
2767   <doc>
2768     This method provides the client with a consumer tag which it MUST
2769     use in methods that work with the consumer.
2770   </doc>
2771   <chassis name = "client" implement = "MUST" />
2772
2773   <field name = "consumer tag" domain = "consumer tag">
2774     <doc>
2775       Holds the consumer tag specified by the client or provided by
2776       the server.
2777     </doc>
2778   </field>
2779 </method>
2780
2781
2782 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2783
2784 <method name = "cancel" synchronous = "1" index = "30">
2785   end a queue consumer
2786   <doc>
2787     This method cancels a consumer. This does not affect already
2788     delivered messages, but it does mean the server will not send any
2789     more messages for that consumer.
2790   </doc>
2791   <chassis name = "server" implement = "MUST" />
2792   <response name = "cancel-ok" />
2793
2794   <field name = "consumer tag" domain = "consumer tag" />
2795
2796   <field name = "nowait" type = "bit">
2797     do not send a reply method
2798     <doc>
2799     If set, the server will not respond to the method. The client should
2800     not wait for a reply method.  If the server could not complete the
2801     method it will raise a channel or connection exception.
2802     </doc>
2803   </field>
2804 </method>
2805
2806 <method name = "cancel-ok" synchronous = "1" index = "31">
2807   confirm a cancelled consumer
2808   <doc>
2809     This method confirms that the cancellation was completed.
2810   </doc>
2811   <chassis name = "client" implement = "MUST" />
2812
2813   <field name = "consumer tag" domain = "consumer tag" />
2814 </method>
2815
2816
2817 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2818
2819 <method name = "open" synchronous = "1" index = "40">
2820   request to start staging
2821   <doc>
2822     This method requests permission to start staging a message.  Staging
2823     means sending the message into a temporary area at the recipient end
2824     and then delivering the message by referring to this temporary area.
2825     Staging is how the protocol handles partial file transfers - if a
2826     message is partially staged and the connection breaks, the next time
2827     the sender starts to stage it, it can restart from where it left off.
2828   </doc>
2829   <response name = "open-ok" />
2830   <chassis name = "server" implement = "MUST" />
2831   <chassis name = "client" implement = "MUST" />
2832
2833   <field name = "identifier" type = "shortstr">
2834     staging identifier
2835     <doc>
2836       This is the staging identifier. This is an arbitrary string chosen
2837       by the sender.  For staging to work correctly the sender must use
2838       the same staging identifier when staging the same message a second
2839       time after recovery from a failure.  A good choice for the staging
2840       identifier would be the SHA1 hash of the message properties data
2841       (including the original filename, revised time, etc.).
2842     </doc>
2843   </field>
2844
2845   <field name = "content size" type = "longlong">
2846     message content size
2847     <doc>
2848       The size of the content in octets.  The recipient may use this
2849       information to allocate or check available space in advance, to
2850       avoid "disk full" errors during staging of very large messages.
2851     </doc>
2852     <doc name = "rule">
2853       The sender MUST accurately fill the content-size field.
2854       Zero-length content is permitted.
2855     </doc>
2856   </field>
2857 </method>
2858
2859 <method name = "open-ok" synchronous = "1" index = "41">
2860   confirm staging ready
2861   <doc>
2862     This method confirms that the recipient is ready to accept staged
2863     data.  If the message was already partially-staged at a previous
2864     time the recipient will report the number of octets already staged.
2865   </doc>
2866   <response name = "stage" />
2867   <chassis name = "server" implement = "MUST" />
2868   <chassis name = "client" implement = "MUST" />
2869
2870   <field name = "staged size" type = "longlong">
2871     already staged amount
2872     <doc>
2873       The amount of previously-staged content in octets.  For a new
2874       message this will be zero.
2875     </doc>
2876     <doc name = "rule">
2877       The sender MUST start sending data from this octet offset in the
2878       message, counting from zero.
2879     </doc>
2880     <doc name = "rule">
2881       The recipient MAY decide how long to hold partially-staged content
2882       and MAY implement staging by always discarding partially-staged
2883       content.  However if it uses the file content type it MUST support
2884       the staging methods.
2885     </doc>
2886   </field>
2887 </method>
2888
2889 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2890
2891 <method name = "stage" content = "1" index = "50">
2892   stage message content
2893   <doc>
2894     This method stages the message, sending the message content to the
2895     recipient from the octet offset specified in the Open-Ok method.
2896   </doc>
2897   <chassis name = "server" implement = "MUST" />
2898   <chassis name = "client" implement = "MUST" />
2899 </method>
2900
2901
2902 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2903
2904 <method name = "publish" index = "60">
2905   publish a message
2906   <doc>
2907     This method publishes a staged file message to a specific exchange.
2908     The file message will be routed to queues as defined by the exchange
2909     configuration and distributed to any active consumers when the
2910     transaction, if any, is committed.
2911   </doc>
2912   <chassis name = "server" implement = "MUST" />
2913
2914   <field name = "ticket" domain = "access ticket">
2915     <doc name = "rule">
2916       The client MUST provide a valid access ticket giving "write"
2917       access rights to the access realm for the exchange.
2918     </doc>
2919   </field>
2920
2921   <field name = "exchange" domain = "exchange name">
2922     <doc>
2923       Specifies the name of the exchange to publish to.  The exchange
2924       name can be empty, meaning the default exchange.  If the exchange
2925       name is specified, and that exchange does not exist, the server
2926       will raise a channel exception.
2927     </doc>
2928     <doc name = "rule">
2929       The server MUST accept a blank exchange name to mean the default
2930       exchange.
2931     </doc>
2932     <doc name = "rule">
2933       If the exchange was declared as an internal exchange, the server
2934       MUST respond with a reply code 403 (access refused) and raise a
2935       channel exception.
2936     </doc>
2937     <doc name = "rule">
2938       The exchange MAY refuse file content in which case it MUST respond
2939       with a reply code 540 (not implemented) and raise a channel
2940       exception.
2941     </doc>
2942   </field>
2943
2944   <field name = "routing key" type = "shortstr">
2945      Message routing key
2946     <doc>
2947       Specifies the routing key for the message.  The routing key is
2948       used for routing messages depending on the exchange configuration.
2949     </doc>
2950   </field>
2951
2952   <field name = "mandatory" type = "bit">
2953     indicate mandatory routing
2954     <doc>
2955       This flag tells the server how to react if the message cannot be
2956       routed to a queue.  If this flag is set, the server will return an
2957       unroutable message with a Return method.  If this flag is zero, the
2958       server silently drops the message.
2959     </doc>
2960     <doc name = "rule" test = "amq_file_00">
2961       The server SHOULD implement the mandatory flag.
2962     </doc>
2963   </field>
2964
2965   <field name = "immediate" type = "bit">
2966     request immediate delivery
2967     <doc>
2968       This flag tells the server how to react if the message cannot be
2969       routed to a queue consumer immediately.  If this flag is set, the
2970       server will return an undeliverable message with a Return method.
2971       If this flag is zero, the server will queue the message, but with
2972       no guarantee that it will ever be consumed.
2973     </doc>
2974     <doc name = "rule" test = "amq_file_00">
2975       The server SHOULD implement the immediate flag.
2976     </doc>
2977   </field>
2978
2979   <field name = "identifier" type = "shortstr">
2980     staging identifier
2981     <doc>
2982       This is the staging identifier of the message to publish.  The
2983       message must have been staged.  Note that a client can send the
2984       Publish method asynchronously without waiting for staging to
2985       finish.
2986     </doc>
2987   </field>
2988 </method>
2989
2990 <method name = "return" content = "1" index = "70">
2991   return a failed message
2992   <doc>
2993     This method returns an undeliverable message that was published
2994     with the "immediate" flag set, or an unroutable message published
2995     with the "mandatory" flag set. The reply code and text provide
2996     information about the reason that the message was undeliverable.
2997   </doc>
2998   <chassis name = "client" implement = "MUST" />
2999
3000   <field name = "reply code" domain = "reply code" />
3001   <field name = "reply text" domain = "reply text" />
3002
3003   <field name = "exchange" domain = "exchange name">
3004     <doc>
3005       Specifies the name of the exchange that the message was
3006       originally published to.
3007     </doc>
3008   </field>
3009
3010   <field name = "routing key" type = "shortstr">
3011      Message routing key
3012     <doc>
3013       Specifies the routing key name specified when the message was
3014       published.
3015     </doc>
3016   </field>
3017 </method>
3018
3019
3020 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3021
3022 <method name = "deliver" index = "80">
3023   notify the client of a consumer message
3024   <doc>
3025     This method delivers a staged file message to the client, via a
3026     consumer. In the asynchronous message delivery model, the client
3027     starts a consumer using the Consume method, then the server
3028     responds with Deliver methods as and when messages arrive for
3029     that consumer.
3030   </doc>
3031   <doc name = "rule">
3032     The server SHOULD track the number of times a message has been
3033     delivered to clients and when a message is redelivered a certain
3034     number of times - e.g. 5 times - without being acknowledged, the
3035     server SHOULD consider the message to be unprocessable (possibly
3036     causing client applications to abort), and move the message to a
3037     dead letter queue.
3038   </doc>
3039   <chassis name = "client" implement = "MUST" />
3040
3041   <field name = "consumer tag" domain = "consumer tag" />
3042
3043   <field name = "delivery tag" domain = "delivery tag" />
3044
3045   <field name = "redelivered" domain = "redelivered" />
3046
3047   <field name = "exchange" domain = "exchange name">
3048     <doc>
3049       Specifies the name of the exchange that the message was originally
3050       published to.
3051     </doc>
3052   </field>
3053
3054   <field name = "routing key" type = "shortstr">
3055      Message routing key
3056     <doc>
3057       Specifies the routing key name specified when the message was
3058       published.
3059     </doc>
3060   </field>
3061
3062   <field name = "identifier" type = "shortstr">
3063     staging identifier
3064     <doc>
3065       This is the staging identifier of the message to deliver.  The
3066       message must have been staged.  Note that a server can send the
3067       Deliver method asynchronously without waiting for staging to
3068       finish.
3069     </doc>
3070   </field>
3071 </method>
3072
3073
3074 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3075
3076 <method name = "ack" index = "90">
3077   acknowledge one or more messages
3078   <doc>
3079     This method acknowledges one or more messages delivered via the
3080     Deliver method.  The client can ask to confirm a single message or
3081     a set of messages up to and including a specific message.
3082   </doc>
3083   <chassis name = "server" implement = "MUST" />
3084   <field name = "delivery tag" domain = "delivery tag" />
3085
3086   <field name = "multiple" type = "bit">
3087     acknowledge multiple messages
3088     <doc>
3089       If set to 1, the delivery tag is treated as "up to and including",
3090       so that the client can acknowledge multiple messages with a single
3091       method.  If set to zero, the delivery tag refers to a single
3092       message.  If the multiple field is 1, and the delivery tag is zero,
3093       tells the server to acknowledge all outstanding mesages.
3094     </doc>
3095     <doc name = "rule">
3096       The server MUST validate that a non-zero delivery-tag refers to an
3097       delivered message, and raise a channel exception if this is not the
3098       case.
3099     </doc>
3100   </field>
3101 </method>
3102
3103
3104 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3105
3106 <method name = "reject" index = "100">
3107   reject an incoming message
3108   <doc>
3109     This method allows a client to reject a message.  It can be used to
3110     return untreatable messages to their original queue.  Note that file
3111     content is staged before delivery, so the client will not use this
3112     method to interrupt delivery of a large message.
3113   </doc>
3114   <doc name = "rule">
3115     The server SHOULD interpret this method as meaning that the client
3116     is unable to process the message at this time.
3117   </doc>
3118   <doc name = "rule">
3119     A client MUST NOT use this method as a means of selecting messages
3120     to process.  A rejected message MAY be discarded or dead-lettered,
3121     not necessarily passed to another client.
3122   </doc>
3123   <chassis name = "server" implement = "MUST" />
3124
3125   <field name = "delivery tag" domain = "delivery tag" />
3126
3127   <field name = "requeue" type = "bit">
3128     requeue the message
3129     <doc>
3130       If this field is zero, the message will be discarded.  If this bit
3131       is 1, the server will attempt to requeue the message.
3132     </doc>
3133     <doc name = "rule">
3134       The server MUST NOT deliver the message to the same client within
3135       the context of the current channel.  The recommended strategy is
3136       to attempt to deliver the message to an alternative consumer, and
3137       if that is not possible, to move the message to a dead-letter
3138       queue.  The server MAY use more sophisticated tracking to hold
3139       the message on the queue and redeliver it to the same client at
3140       a later stage.
3141     </doc>
3142   </field>
3143 </method>
3144
3145 </class>
3146
3147   <class name="stream" handler="channel" index="80">
3148     <!--
3149 ======================================================
3150 ==       STREAMING
3151 ======================================================
3152 -->
3153   work with streaming content
3154
3155 <doc>
3156   The stream class provides methods that support multimedia streaming.
3157   The stream class uses the following semantics: one message is one
3158   packet of data; delivery is unacknowleged and unreliable; the consumer
3159   can specify quality of service parameters that the server can try to
3160   adhere to; lower-priority messages may be discarded in favour of high
3161   priority messages.
3162 </doc>
3163
3164 <doc name = "grammar">
3165     stream              = C:QOS S:QOS-OK
3166                         / C:CONSUME S:CONSUME-OK
3167                         / C:CANCEL S:CANCEL-OK
3168                         / C:PUBLISH content
3169                         / S:RETURN
3170                         / S:DELIVER content
3171 </doc>
3172
3173 <chassis name = "server" implement = "MAY" />
3174 <chassis name = "client" implement = "MAY" />
3175
3176 <doc name = "rule">
3177   The server SHOULD discard stream messages on a priority basis if
3178   the queue size exceeds some configured limit.
3179 </doc>
3180 <doc name = "rule">
3181   The server MUST implement at least 2 priority levels for stream
3182   messages, where priorities 0-4 and 5-9 are treated as two distinct
3183   levels. The server MAY implement up to 10 priority levels.
3184 </doc>
3185 <doc name = "rule">
3186   The server MUST implement automatic acknowledgements on stream
3187   content.  That is, as soon as a message is delivered to a client
3188   via a Deliver method, the server must remove it from the queue.
3189 </doc>
3190
3191
3192 <!--  These are the properties for a Stream content  -->
3193
3194 <field name = "content type" type = "shortstr">
3195     MIME content type
3196 </field>
3197 <field name = "content encoding" type = "shortstr">
3198     MIME content encoding
3199 </field>
3200 <field name = "headers" type = "table">
3201     Message header field table
3202 </field>
3203 <field name = "priority" type = "octet">
3204     The message priority, 0 to 9
3205 </field>
3206 <field name = "timestamp" type = "timestamp">
3207     The message timestamp
3208 </field>
3209
3210
3211 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3212
3213 <method name = "qos" synchronous = "1" index = "10">
3214   specify quality of service
3215   <doc>
3216     This method requests a specific quality of service.  The QoS can
3217     be specified for the current channel or for all channels on the
3218     connection.  The particular properties and semantics of a qos method
3219     always depend on the content class semantics.  Though the qos method
3220     could in principle apply to both peers, it is currently meaningful
3221     only for the server.
3222   </doc>
3223   <chassis name = "server" implement = "MUST" />
3224   <response name = "qos-ok" />
3225
3226   <field name = "prefetch size" type = "long">
3227     prefetch window in octets
3228     <doc>
3229       The client can request that messages be sent in advance so that
3230       when the client finishes processing a message, the following
3231       message is already held locally, rather than needing to be sent
3232       down the channel.  Prefetching gives a performance improvement.
3233       This field specifies the prefetch window size in octets. May be
3234       set to zero, meaning "no specific limit".  Note that other
3235       prefetch limits may still apply.
3236     </doc>
3237   </field>
3238
3239   <field name = "prefetch count" type = "short">
3240     prefetch window in messages
3241     <doc>
3242       Specifies a prefetch window in terms of whole messages.  This
3243       field may be used in combination with the prefetch-size field;
3244       a message will only be sent in advance if both prefetch windows
3245       (and those at the channel and connection level) allow it.
3246     </doc>
3247   </field>
3248
3249   <field name = "consume rate" type = "long">
3250     transfer rate in octets/second
3251     <doc>
3252       Specifies a desired transfer rate in octets per second. This is
3253       usually determined by the application that uses the streaming
3254       data.  A value of zero means "no limit", i.e. as rapidly as
3255       possible.
3256     </doc>
3257     <doc name = "rule">
3258       The server MAY ignore the prefetch values and consume rates,
3259       depending on the type of stream and the ability of the server
3260       to queue and/or reply it.  The server MAY drop low-priority
3261       messages in favour of high-priority messages.
3262     </doc>
3263   </field>
3264
3265   <field name = "global" type = "bit">
3266     apply to entire connection
3267     <doc>
3268       By default the QoS settings apply to the current channel only.  If
3269       this field is set, they are applied to the entire connection.
3270     </doc>
3271   </field>
3272 </method>
3273
3274 <method name = "qos-ok" synchronous = "1" index = "11">
3275   confirm the requested qos
3276   <doc>
3277     This method tells the client that the requested QoS levels could
3278     be handled by the server.  The requested QoS applies to all active
3279     consumers until a new QoS is defined.
3280   </doc>
3281   <chassis name = "client" implement = "MUST" />
3282 </method>
3283
3284 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3285
3286 <method name = "consume" synchronous = "1" index = "20">
3287   start a queue consumer
3288   <doc>
3289     This method asks the server to start a "consumer", which is a
3290     transient request for messages from a specific queue. Consumers
3291     last as long as the channel they were created on, or until the
3292     client cancels them.
3293   </doc>
3294   <doc name = "rule">
3295     The server SHOULD support at least 16 consumers per queue, unless
3296     the queue was declared as private, and ideally, impose no limit
3297     except as defined by available resources.
3298   </doc>
3299   <doc name = "rule">
3300     Streaming applications SHOULD use different channels to select
3301     different streaming resolutions. AMQP makes no provision for
3302     filtering and/or transforming streams except on the basis of
3303     priority-based selective delivery of individual messages.
3304   </doc>
3305   <chassis name = "server" implement = "MUST" />
3306   <response name = "consume-ok" />
3307
3308   <field name = "ticket" domain = "access ticket">
3309     <doc name = "rule">
3310       The client MUST provide a valid access ticket giving "read" access
3311       rights to the realm for the queue.
3312     </doc>
3313   </field>
3314
3315   <field name = "queue" domain = "queue name">
3316     <doc>
3317       Specifies the name of the queue to consume from.  If the queue name
3318       is null, refers to the current queue for the channel, which is the
3319       last declared queue.
3320     </doc>
3321     <doc name = "rule">
3322       If the client did not previously declare a queue, and the queue name
3323       in this method is empty, the server MUST raise a connection exception
3324       with reply code 530 (not allowed).
3325     </doc>
3326   </field>
3327
3328   <field name = "consumer tag" domain = "consumer tag">
3329     <doc>
3330       Specifies the identifier for the consumer. The consumer tag is
3331       local to a connection, so two clients can use the same consumer
3332       tags. If this field is empty the server will generate a unique
3333       tag.
3334     </doc>
3335     <doc name = "rule" test = "todo">
3336       The tag MUST NOT refer to an existing consumer. If the client
3337       attempts to create two consumers with the same non-empty tag
3338       the server MUST raise a connection exception with reply code
3339       530 (not allowed).
3340     </doc>
3341   </field>
3342
3343   <field name = "no local" domain = "no local" />
3344
3345   <field name = "exclusive" type = "bit">
3346     request exclusive access
3347     <doc>
3348       Request exclusive consumer access, meaning only this consumer can
3349       access the queue.
3350     </doc>
3351     <doc name = "rule" test = "amq_file_00">
3352       If the server cannot grant exclusive access to the queue when asked,
3353       - because there are other consumers active - it MUST raise a channel
3354       exception with return code 405 (resource locked).
3355     </doc>
3356   </field>
3357
3358   <field name = "nowait" type = "bit">
3359     do not send a reply method
3360     <doc>
3361     If set, the server will not respond to the method. The client should
3362     not wait for a reply method.  If the server could not complete the
3363     method it will raise a channel or connection exception.
3364     </doc>
3365   </field>
3366 </method>
3367
3368
3369 <method name = "consume-ok" synchronous = "1" index = "21">
3370   confirm a new consumer
3371   <doc>
3372     This method provides the client with a consumer tag which it may
3373     use in methods that work with the consumer.
3374   </doc>
3375   <chassis name = "client" implement = "MUST" />
3376
3377   <field name = "consumer tag" domain = "consumer tag">
3378     <doc>
3379       Holds the consumer tag specified by the client or provided by
3380       the server.
3381     </doc>
3382   </field>
3383 </method>
3384
3385 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3386
3387 <method name = "cancel" synchronous = "1" index = "30">
3388   end a queue consumer
3389   <doc>
3390     This method cancels a consumer.  Since message delivery is
3391     asynchronous the client may continue to receive messages for
3392     a short while after canceling a consumer.  It may process or
3393     discard these as appropriate.
3394   </doc>
3395   <chassis name = "server" implement = "MUST" />
3396   <response name = "cancel-ok" />
3397
3398   <field name = "consumer tag" domain = "consumer tag" />
3399
3400   <field name = "nowait" type = "bit">
3401     do not send a reply method
3402     <doc>
3403     If set, the server will not respond to the method. The client should
3404     not wait for a reply method.  If the server could not complete the
3405     method it will raise a channel or connection exception.
3406     </doc>
3407   </field>
3408 </method>
3409
3410 <method name = "cancel-ok" synchronous = "1" index = "31">
3411   confirm a cancelled consumer
3412   <doc>
3413     This method confirms that the cancellation was completed.
3414   </doc>
3415   <chassis name = "client" implement = "MUST" />
3416
3417   <field name = "consumer tag" domain = "consumer tag" />
3418 </method>
3419
3420
3421 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3422
3423 <method name = "publish" content = "1" index = "40">
3424   publish a message
3425   <doc>
3426     This method publishes a message to a specific exchange. The message
3427     will be routed to queues as defined by the exchange configuration
3428     and distributed to any active consumers as appropriate.
3429   </doc>
3430   <chassis name = "server" implement = "MUST" />
3431
3432   <field name = "ticket" domain = "access ticket">
3433     <doc name = "rule">
3434       The client MUST provide a valid access ticket giving "write"
3435       access rights to the access realm for the exchange.
3436     </doc>
3437   </field>
3438
3439   <field name = "exchange" domain = "exchange name">
3440     <doc>
3441       Specifies the name of the exchange to publish to.  The exchange
3442       name can be empty, meaning the default exchange.  If the exchange
3443       name is specified, and that exchange does not exist, the server
3444       will raise a channel exception.
3445     </doc>
3446     <doc name = "rule">
3447       The server MUST accept a blank exchange name to mean the default
3448       exchange.
3449     </doc>
3450     <doc name = "rule">
3451       If the exchange was declared as an internal exchange, the server
3452       MUST respond with a reply code 403 (access refused) and raise a
3453       channel exception.
3454     </doc>
3455     <doc name = "rule">
3456       The exchange MAY refuse stream content in which case it MUST
3457       respond with a reply code 540 (not implemented) and raise a
3458       channel exception.
3459     </doc>
3460   </field>
3461
3462   <field name = "routing key" type = "shortstr">
3463      Message routing key
3464     <doc>
3465       Specifies the routing key for the message.  The routing key is
3466       used for routing messages depending on the exchange configuration.
3467     </doc>
3468   </field>
3469
3470   <field name = "mandatory" type = "bit">
3471     indicate mandatory routing
3472     <doc>
3473       This flag tells the server how to react if the message cannot be
3474       routed to a queue.  If this flag is set, the server will return an
3475       unroutable message with a Return method.  If this flag is zero, the
3476       server silently drops the message.
3477     </doc>
3478     <doc name = "rule" test = "amq_stream_00">
3479       The server SHOULD implement the mandatory flag.
3480     </doc>
3481   </field>
3482
3483   <field name = "immediate" type = "bit">
3484     request immediate delivery
3485     <doc>
3486       This flag tells the server how to react if the message cannot be
3487       routed to a queue consumer immediately.  If this flag is set, the
3488       server will return an undeliverable message with a Return method.
3489       If this flag is zero, the server will queue the message, but with
3490       no guarantee that it will ever be consumed.
3491     </doc>
3492     <doc name = "rule" test = "amq_stream_00">
3493       The server SHOULD implement the immediate flag.
3494     </doc>
3495   </field>
3496 </method>
3497
3498 <method name = "return" content = "1" index = "50">
3499   return a failed message
3500   <doc>
3501     This method returns an undeliverable message that was published
3502     with the "immediate" flag set, or an unroutable message published
3503     with the "mandatory" flag set. The reply code and text provide
3504     information about the reason that the message was undeliverable.
3505   </doc>
3506   <chassis name = "client" implement = "MUST" />
3507
3508   <field name = "reply code" domain = "reply code" />
3509   <field name = "reply text" domain = "reply text" />
3510
3511   <field name = "exchange" domain = "exchange name">
3512     <doc>
3513       Specifies the name of the exchange that the message was
3514       originally published to.
3515     </doc>
3516   </field>
3517
3518   <field name = "routing key" type = "shortstr">
3519      Message routing key
3520     <doc>
3521       Specifies the routing key name specified when the message was
3522       published.
3523     </doc>
3524   </field>
3525 </method>
3526
3527
3528 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3529
3530 <method name = "deliver" content = "1" index = "60">
3531   notify the client of a consumer message
3532   <doc>
3533     This method delivers a message to the client, via a consumer.  In
3534     the asynchronous message delivery model, the client starts a
3535     consumer using the Consume method, then the server responds with
3536     Deliver methods as and when messages arrive for that consumer.
3537   </doc>
3538   <chassis name = "client" implement = "MUST" />
3539
3540   <field name = "consumer tag" domain = "consumer tag" />
3541
3542   <field name = "delivery tag" domain = "delivery tag" />
3543
3544   <field name = "exchange" domain = "exchange name">
3545     <doc>
3546       Specifies the name of the exchange that the message was originally
3547       published to.
3548     </doc>
3549   </field>
3550
3551   <field name = "queue" domain = "queue name">
3552     <doc>
3553       Specifies the name of the queue that the message came from. Note
3554       that a single channel can start many consumers on different
3555       queues.
3556     </doc>
3557     <assert check = "notnull" />
3558   </field>
3559 </method>
3560   </class>
3561
3562   <class name="tx" handler="channel" index="90">
3563     <!--
3564 ======================================================
3565 ==       TRANSACTIONS
3566 ======================================================
3567 -->
3568   work with standard transactions
3569
3570 <doc>
3571   Standard transactions provide so-called "1.5 phase commit".  We can
3572   ensure that work is never lost, but there is a chance of confirmations
3573   being lost, so that messages may be resent.  Applications that use
3574   standard transactions must be able to detect and ignore duplicate
3575   messages.
3576 </doc>
3577     <rule implement="SHOULD">
3578   An client using standard transactions SHOULD be able to track all
3579   messages received within a reasonable period, and thus detect and
3580   reject duplicates of the same message. It SHOULD NOT pass these to
3581   the application layer.
3582 </rule>
3583     <doc name="grammar">
3584     tx                  = C:SELECT S:SELECT-OK
3585                         / C:COMMIT S:COMMIT-OK
3586                         / C:ROLLBACK S:ROLLBACK-OK
3587 </doc>
3588     <chassis name="server" implement="SHOULD"/>
3589     <chassis name="client" implement="MAY"/>
3590     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3591     <method name="select" synchronous="1" index="10">
3592 select standard transaction mode
3593   <doc>
3594     This method sets the channel to use standard transactions.  The
3595     client must use this method at least once on a channel before
3596     using the Commit or Rollback methods.
3597   </doc>
3598       <chassis name="server" implement="MUST"/>
3599       <response name="select-ok"/>
3600     </method>
3601     <method name="select-ok" synchronous="1" index="11">
3602 confirm transaction mode
3603   <doc>
3604     This method confirms to the client that the channel was successfully
3605     set to use standard transactions.
3606   </doc>
3607       <chassis name="client" implement="MUST"/>
3608     </method>
3609     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3610     <method name="commit" synchronous="1" index="20">
3611 commit the current transaction
3612   <doc>
3613     This method commits all messages published and acknowledged in
3614     the current transaction.  A new transaction starts immediately
3615     after a commit.
3616   </doc>
3617       <chassis name="server" implement="MUST"/>
3618       <response name="commit-ok"/>
3619     </method>
3620     <method name="commit-ok" synchronous="1" index="21">
3621 confirm a successful commit
3622   <doc>
3623     This method confirms to the client that the commit succeeded.
3624     Note that if a commit fails, the server raises a channel exception.
3625   </doc>
3626       <chassis name="client" implement="MUST"/>
3627     </method>
3628     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3629     <method name="rollback" synchronous="1" index="30">
3630 abandon the current transaction
3631   <doc>
3632     This method abandons all messages published and acknowledged in
3633     the current transaction.  A new transaction starts immediately
3634     after a rollback.
3635   </doc>
3636       <chassis name="server" implement="MUST"/>
3637       <response name="rollback-ok"/>
3638     </method>
3639     <method name="rollback-ok" synchronous="1" index="31">
3640 confirm a successful rollback
3641   <doc>
3642     This method confirms to the client that the rollback succeeded.
3643     Note that if an rollback fails, the server raises a channel exception.
3644   </doc>
3645       <chassis name="client" implement="MUST"/>
3646     </method>
3647   </class>
3648   <class name="dtx" handler="channel" index="100">
3649     <!--
3650 ======================================================
3651 ==       DISTRIBUTED TRANSACTIONS
3652 ======================================================
3653 -->
3654   work with distributed transactions
3655
3656 <doc>
3657   Distributed transactions provide so-called "2-phase commit".    The
3658   AMQP distributed transaction model supports the X-Open XA
3659   architecture and other distributed transaction implementations.
3660   The Dtx class assumes that the server has a private communications
3661   channel (not AMQP) to a distributed transaction coordinator.
3662 </doc>
3663     <doc name="grammar">
3664     dtx                 = C:SELECT S:SELECT-OK
3665                           C:START S:START-OK
3666 </doc>
3667     <chassis name="server" implement="MAY"/>
3668     <chassis name="client" implement="MAY"/>
3669     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3670     <method name="select" synchronous="1" index="10">
3671 select standard transaction mode
3672   <doc>
3673     This method sets the channel to use distributed transactions.  The
3674     client must use this method at least once on a channel before
3675     using the Start method.
3676   </doc>
3677       <chassis name="server" implement="MUST"/>
3678       <response name="select-ok"/>
3679     </method>
3680     <method name="select-ok" synchronous="1" index="11">
3681 confirm transaction mode
3682   <doc>
3683     This method confirms to the client that the channel was successfully
3684     set to use distributed transactions.
3685   </doc>
3686       <chassis name="client" implement="MUST"/>
3687     </method>
3688     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3689     <method name="start" synchronous="1" index="20">
3690   start a new distributed transaction
3691   <doc>
3692     This method starts a new distributed transaction.  This must be
3693     the first method on a new channel that uses the distributed
3694     transaction mode, before any methods that publish or consume
3695     messages.
3696   </doc>
3697       <chassis name="server" implement="MAY"/>
3698       <response name="start-ok"/>
3699       <field name="dtx identifier" type="shortstr">
3700     transaction identifier
3701     <doc>
3702       The distributed transaction key. This identifies the transaction
3703       so that the AMQP server can coordinate with the distributed
3704       transaction coordinator.
3705     </doc>
3706         <assert check="notnull"/>
3707       </field>
3708     </method>
3709     <method name="start-ok" synchronous="1" index="21">
3710   confirm the start of a new distributed transaction
3711   <doc>
3712     This method confirms to the client that the transaction started.
3713     Note that if a start fails, the server raises a channel exception.
3714   </doc>
3715       <chassis name="client" implement="MUST"/>
3716     </method>
3717   </class>
3718   <class name="tunnel" handler="tunnel" index="110">
3719     <!--
3720 ======================================================
3721 ==       TUNNEL
3722 ======================================================
3723 -->
3724   methods for protocol tunneling.
3725
3726 <doc>
3727   The tunnel methods are used to send blocks of binary data - which
3728   can be serialised AMQP methods or other protocol frames - between
3729   AMQP peers.
3730 </doc>
3731     <doc name="grammar">
3732     tunnel              = C:REQUEST
3733                         / S:REQUEST
3734 </doc>
3735     <chassis name="server" implement="MAY"/>
3736     <chassis name="client" implement="MAY"/>
3737     <field name="headers" type="table">
3738     Message header field table
3739 </field>
3740     <field name="proxy name" type="shortstr">
3741     The identity of the tunnelling proxy
3742 </field>
3743     <field name="data name" type="shortstr">
3744     The name or type of the message being tunnelled
3745 </field>
3746     <field name="durable" type="octet">
3747     The message durability indicator
3748 </field>
3749     <field name="broadcast" type="octet">
3750     The message broadcast mode
3751 </field>
3752     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3753     <method name="request" content="1" index="10">
3754   sends a tunnelled method
3755   <doc>
3756     This method tunnels a block of binary data, which can be an
3757     encoded AMQP method or other data.  The binary data is sent
3758     as the content for the Tunnel.Request method.
3759   </doc>
3760       <chassis name="server" implement="MUST"/>
3761       <field name="meta data" type="table">
3762     meta data for the tunnelled block
3763     <doc>
3764     This field table holds arbitrary meta-data that the sender needs
3765     to pass to the recipient.
3766     </doc>
3767       </field>
3768     </method>
3769   </class>
3770   <class name="test" handler="channel" index="120">
3771     <!--
3772 ======================================================
3773 ==       TEST - CHECK FUNCTIONAL CAPABILITIES OF AN IMPLEMENTATION
3774 ======================================================
3775 -->
3776   test functional primitives of the implementation
3777
3778 <doc>
3779   The test class provides methods for a peer to test the basic
3780   operational correctness of another peer. The test methods are
3781   intended to ensure that all peers respect at least the basic
3782   elements of the protocol, such as frame and content organisation
3783   and field types. We assume that a specially-designed peer, a
3784   "monitor client" would perform such tests.
3785 </doc>
3786     <doc name="grammar">
3787     test                = C:INTEGER S:INTEGER-OK
3788                         / S:INTEGER C:INTEGER-OK
3789                         / C:STRING S:STRING-OK
3790                         / S:STRING C:STRING-OK
3791                         / C:TABLE S:TABLE-OK
3792                         / S:TABLE C:TABLE-OK
3793                         / C:CONTENT S:CONTENT-OK
3794                         / S:CONTENT C:CONTENT-OK
3795 </doc>
3796     <chassis name="server" implement="MUST"/>
3797     <chassis name="client" implement="SHOULD"/>
3798     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3799     <method name="integer" synchronous="1" index="10">
3800   test integer handling
3801   <doc>
3802     This method tests the peer's capability to correctly marshal integer
3803     data.
3804   </doc>
3805       <chassis name="client" implement="MUST"/>
3806       <chassis name="server" implement="MUST"/>
3807       <response name="integer-ok"/>
3808       <field name="integer 1" type="octet">
3809     octet test value
3810     <doc>
3811       An octet integer test value.
3812     </doc>
3813       </field>
3814       <field name="integer 2" type="short">
3815     short test value
3816     <doc>
3817       A short integer test value.
3818     </doc>
3819       </field>
3820       <field name="integer 3" type="long">
3821     long test value
3822     <doc>
3823       A long integer test value.
3824     </doc>
3825       </field>
3826       <field name="integer 4" type="longlong">
3827     long-long test value
3828     <doc>
3829       A long long integer test value.
3830     </doc>
3831       </field>
3832       <field name="operation" type="octet">
3833     operation to test
3834     <doc>
3835       The client must execute this operation on the provided integer
3836       test fields and return the result.
3837     </doc>
3838         <assert check="enum">
3839           <value name="add">return sum of test values</value>
3840           <value name="min">return lowest of test values</value>
3841           <value name="max">return highest of test values</value>
3842         </assert>
3843       </field>
3844     </method>
3845     <method name="integer-ok" synchronous="1" index="11">
3846   report integer test result
3847   <doc>
3848     This method reports the result of an Integer method.
3849   </doc>
3850       <chassis name="client" implement="MUST"/>
3851       <chassis name="server" implement="MUST"/>
3852       <field name="result" type="longlong">
3853     result value
3854     <doc>
3855       The result of the tested operation.
3856     </doc>
3857       </field>
3858     </method>
3859     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3860     <method name="string" synchronous="1" index="20">
3861   test string handling
3862   <doc>
3863     This method tests the peer's capability to correctly marshal string
3864     data.
3865   </doc>
3866       <chassis name="client" implement="MUST"/>
3867       <chassis name="server" implement="MUST"/>
3868       <response name="string-ok"/>
3869       <field name="string 1" type="shortstr">
3870     short string test value
3871     <doc>
3872       An short string test value.
3873     </doc>
3874       </field>
3875       <field name="string 2" type="longstr">
3876     long string test value
3877     <doc>
3878       A long string test value.
3879     </doc>
3880       </field>
3881       <field name="operation" type="octet">
3882     operation to test
3883     <doc>
3884       The client must execute this operation on the provided string
3885       test fields and return the result.
3886     </doc>
3887         <assert check="enum">
3888           <value name="add">return concatentation of test strings</value>
3889           <value name="min">return shortest of test strings</value>
3890           <value name="max">return longest of test strings</value>
3891         </assert>
3892       </field>
3893     </method>
3894     <method name="string-ok" synchronous="1" index="21">
3895   report string test result
3896   <doc>
3897     This method reports the result of a String method.
3898   </doc>
3899       <chassis name="client" implement="MUST"/>
3900       <chassis name="server" implement="MUST"/>
3901       <field name="result" type="longstr">
3902     result value
3903     <doc>
3904       The result of the tested operation.
3905     </doc>
3906       </field>
3907     </method>
3908     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3909     <method name="table" synchronous="1" index="30">
3910   test field table handling
3911   <doc>
3912     This method tests the peer's capability to correctly marshal field
3913     table data.
3914   </doc>
3915       <chassis name="client" implement="MUST"/>
3916       <chassis name="server" implement="MUST"/>
3917       <response name="table-ok"/>
3918       <field name="table" type="table">
3919     field table of test values
3920     <doc>
3921       A field table of test values.
3922     </doc>
3923       </field>
3924       <field name="integer op" type="octet">
3925     operation to test on integers
3926     <doc>
3927       The client must execute this operation on the provided field
3928       table integer values and return the result.
3929     </doc>
3930         <assert check="enum">
3931           <value name="add">return sum of numeric field values</value>
3932           <value name="min">return min of numeric field values</value>
3933           <value name="max">return max of numeric field values</value>
3934         </assert>
3935       </field>
3936       <field name="string op" type="octet">
3937     operation to test on strings
3938     <doc>
3939       The client must execute this operation on the provided field
3940       table string values and return the result.
3941     </doc>
3942         <assert check="enum">
3943           <value name="add">return concatenation of string field values</value>
3944           <value name="min">return shortest of string field values</value>
3945           <value name="max">return longest of string field values</value>
3946         </assert>
3947       </field>
3948     </method>
3949     <method name="table-ok" synchronous="1" index="31">
3950   report table test result
3951   <doc>
3952     This method reports the result of a Table method.
3953   </doc>
3954       <chassis name="client" implement="MUST"/>
3955       <chassis name="server" implement="MUST"/>
3956       <field name="integer result" type="longlong">
3957     integer result value
3958     <doc>
3959       The result of the tested integer operation.
3960     </doc>
3961       </field>
3962       <field name="string result" type="longstr">
3963     string result value
3964     <doc>
3965       The result of the tested string operation.
3966     </doc>
3967       </field>
3968     </method>
3969     <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3970     <method name="content" synchronous="1" content="1" index="40">
3971   test content handling
3972   <doc>
3973     This method tests the peer's capability to correctly marshal content.
3974   </doc>
3975       <chassis name="client" implement="MUST"/>
3976       <chassis name="server" implement="MUST"/>
3977       <response name="content-ok"/>
3978     </method>
3979     <method name="content-ok" synchronous="1" content="1" index="41">
3980   report content test result
3981   <doc>
3982     This method reports the result of a Content method.  It contains the
3983     content checksum and echoes the original content as provided.
3984   </doc>
3985       <chassis name="client" implement="MUST"/>
3986       <chassis name="server" implement="MUST"/>
3987       <field name="content checksum" type="long">
3988     content hash
3989     <doc>
3990       The 32-bit checksum of the content, calculated by adding the
3991       content into a 32-bit accumulator.
3992     </doc>
3993       </field>
3994     </method>
3995   </class>
3996 </amqp>