2 <!-- WARNING: Modified from the official 0-8 specification XML by
3 the addition of queue.unbind, queue.unbind-ok -->
7 © Copyright JPMorgan Chase Bank & Co., Cisco Systems, Inc., Envoy Technologies Inc.,
8 iMatix Corporation, IONA� Technologies, Red Hat, Inc.,
9 TWIST Process Innovations, and 29West Inc. 2006. All rights reserved.
13 JPMorgan Chase Bank & Co., Cisco Systems, Inc., Envoy Technologies Inc., iMatix
14 Corporation, IONA� Technologies, Red Hat, Inc., TWIST Process Innovations, and
15 29West Inc. (collectively, the "Authors") each hereby grants to you a worldwide,
16 perpetual, royalty-free, nontransferable, nonexclusive license to
17 (i) copy, display, and implement the Advanced Messaging Queue Protocol
18 ("AMQP") Specification and (ii) the Licensed Claims that are held by
19 the Authors, all for the purpose of implementing the Advanced Messaging
20 Queue Protocol Specification. Your license and any rights under this
21 Agreement will terminate immediately without notice from
22 any Author if you bring any claim, suit, demand, or action related to
23 the Advanced Messaging Queue Protocol Specification against any Author.
24 Upon termination, you shall destroy all copies of the Advanced Messaging
25 Queue Protocol Specification in your possession or control.
27 As used hereunder, "Licensed Claims" means those claims of a patent or
28 patent application, throughout the world, excluding design patents and
29 design registrations, owned or controlled, or that can be sublicensed
30 without fee and in compliance with the requirements of this
31 Agreement, by an Author or its affiliates now or at any
32 future time and which would necessarily be infringed by implementation
33 of the Advanced Messaging Queue Protocol Specification. A claim is
34 necessarily infringed hereunder only when it is not possible to avoid
35 infringing it because there is no plausible non-infringing alternative
36 for implementing the required portions of the Advanced Messaging Queue
37 Protocol Specification. Notwithstanding the foregoing, Licensed Claims
38 shall not include any claims other than as set forth above even if
39 contained in the same patent as Licensed Claims; or that read solely
40 on any implementations of any portion of the Advanced Messaging Queue
41 Protocol Specification that are not required by the Advanced Messaging
42 Queue Protocol Specification, or that, if licensed, would require a
43 payment of royalties by the licensor to unaffiliated third parties.
44 Moreover, Licensed Claims shall not include (i) any enabling technologies
45 that may be necessary to make or use any Licensed Product but are not
46 themselves expressly set forth in the Advanced Messaging Queue Protocol
47 Specification (e.g., semiconductor manufacturing technology, compiler
48 technology, object oriented technology, networking technology, operating
49 system technology, and the like); or (ii) the implementation of other
50 published standards developed elsewhere and merely referred to in the
51 body of the Advanced Messaging Queue Protocol Specification, or
52 (iii) any Licensed Product and any combinations thereof the purpose or
53 function of which is not required for compliance with the Advanced
54 Messaging Queue Protocol Specification. For purposes of this definition,
55 the Advanced Messaging Queue Protocol Specification shall be deemed to
56 include both architectural and interconnection requirements essential
57 for interoperability and may also include supporting source code artifacts
58 where such architectural, interconnection requirements and source code
59 artifacts are expressly identified as being required or documentation to
60 achieve compliance with the Advanced Messaging Queue Protocol Specification.
62 As used hereunder, "Licensed Products" means only those specific portions
63 of products (hardware, software or combinations thereof) that implement
64 and are compliant with all relevant portions of the Advanced Messaging
65 Queue Protocol Specification.
67 The following disclaimers, which you hereby also acknowledge as to any
68 use you may make of the Advanced Messaging Queue Protocol Specification:
70 THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION IS PROVIDED "AS IS,"
71 AND THE AUTHORS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
72 IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY,
73 FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE
74 CONTENTS OF THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION ARE
75 SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF THE ADVANCED
76 MESSAGING QUEUE PROTOCOL SPECIFICATION WILL NOT INFRINGE ANY THIRD PARTY
77 PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
79 THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL,
80 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATING TO ANY
81 USE, IMPLEMENTATION OR DISTRIBUTION OF THE ADVANCED MESSAGING QUEUE
82 PROTOCOL SPECIFICATION.
84 The name and trademarks of the Authors may NOT be used in any manner,
85 including advertising or publicity pertaining to the Advanced Messaging
86 Queue Protocol Specification or its contents without specific, written
87 prior permission. Title to copyright in the Advanced Messaging Queue
88 Protocol Specification will at all times remain with the Authors.
90 No other rights are granted by implication, estoppel or otherwise.
92 Upon termination of your license or rights under this Agreement, you
93 shall destroy all copies of the Advanced Messaging Queue Protocol
94 Specification in your possession or control.
98 "JPMorgan", "JPMorgan Chase", "Chase", the JPMorgan Chase logo and the
99 Octagon Symbol are trademarks of JPMorgan Chase & Co.
101 IMATIX and the iMatix logo are trademarks of iMatix Corporation sprl.
103 IONA, IONA Technologies, and the IONA logos are trademarks of IONA
104 Technologies PLC and/or its subsidiaries.
106 LINUX is a trademark of Linus Torvalds. RED HAT and JBOSS are registered
107 trademarks of Red Hat, Inc. in the US and other countries.
109 Java, all Java-based trademarks and OpenOffice.org are trademarks of
110 Sun Microsystems, Inc. in the United States, other countries, or both.
112 Other company, product, or service names may be trademarks or service
115 Links to full AMQP specification:
116 =================================
117 http://www.envoytech.org/spec/amq/
118 http://www.iona.com/opensource/amqp/
119 http://www.redhat.com/solutions/specifications/amqp/
120 http://www.twiststandards.org/tiki-index.php?page=AMQ
121 http://www.imatix.com/amqp
125 <amqp major="8" minor="0" port="5672" comment="AMQ protocol 0.80">
128 ======================================================
130 ======================================================
132 <constant name="frame method" value="1"/>
133 <constant name="frame header" value="2"/>
134 <constant name="frame body" value="3"/>
135 <constant name="frame oob method" value="4"/>
136 <constant name="frame oob header" value="5"/>
137 <constant name="frame oob body" value="6"/>
138 <constant name="frame trace" value="7"/>
139 <constant name="frame heartbeat" value="8"/>
140 <constant name="frame min size" value="4096"/>
141 <constant name="frame end" value="206"/>
142 <constant name="reply success" value="200">
143 Indicates that the method completed successfully. This reply code is
144 reserved for future use - the current protocol design does not use
145 positive confirmation and reply codes are sent only in case of an
148 <constant name="not delivered" value="310" class="soft error">
149 The client asked for a specific message that is no longer available.
150 The message was delivered to another client, or was purged from the
151 queue for some other reason.
153 <constant name="content too large" value="311" class="soft error">
154 The client attempted to transfer content larger than the server
155 could accept at the present time. The client may retry at a later
158 <constant name="connection forced" value="320" class="hard error">
159 An operator intervened to close the connection for some reason.
160 The client may retry at some later date.
162 <constant name="invalid path" value="402" class="hard error">
163 The client tried to work with an unknown virtual host or cluster.
165 <constant name="access refused" value="403" class="soft error">
166 The client attempted to work with a server entity to which it has
167 no due to security settings.
169 <constant name="not found" value="404" class="soft error">
170 The client attempted to work with a server entity that does not exist.
172 <constant name="resource locked" value="405" class="soft error">
173 The client attempted to work with a server entity to which it has
174 no access because another client is working with it.
176 <constant name="frame error" value="501" class="hard error">
177 The client sent a malformed frame that the server could not decode.
178 This strongly implies a programming error in the client.
180 <constant name="syntax error" value="502" class="hard error">
181 The client sent a frame that contained illegal values for one or more
182 fields. This strongly implies a programming error in the client.
184 <constant name="command invalid" value="503" class="hard error">
185 The client sent an invalid sequence of frames, attempting to perform
186 an operation that was considered invalid by the server. This usually
187 implies a programming error in the client.
189 <constant name="channel error" value="504" class="hard error">
190 The client attempted to work with a channel that had not been
191 correctly opened. This most likely indicates a fault in the client
194 <constant name="resource error" value="506" class="hard error">
195 The server could not complete the method because it lacked sufficient
196 resources. This may be due to the client creating too many of some
199 <constant name="not allowed" value="530" class="hard error">
200 The client tried to work with some entity in a manner that is
201 prohibited by the server, due to security settings or by some other
204 <constant name="not implemented" value="540" class="hard error">
205 The client tried to use functionality that is not implemented in the
208 <constant name="internal error" value="541" class="hard error">
209 The server could not complete the method because of an internal error.
210 The server may require intervention by an operator in order to resume
214 ======================================================
216 ======================================================
218 <domain name="access ticket" type="short">
219 access ticket granted by server
221 An access ticket granted by the server for a certain set of access
222 rights within a specific realm. Access tickets are valid within the
223 channel where they were created, and expire when the channel closes.
225 <assert check="ne" value="0"/>
227 <domain name="class id" type="short"/>
228 <domain name="consumer tag" type="shortstr">
231 Identifier for the consumer, valid within the current connection.
233 <rule implement="MUST">
234 The consumer tag is valid only within the channel from which the
235 consumer was created. I.e. a client MUST NOT create a consumer in
236 one channel and then use it in another.
239 <domain name="delivery tag" type="longlong">
240 server-assigned delivery tag
242 The server-assigned and channel-specific delivery tag
244 <rule implement="MUST">
245 The delivery tag is valid only within the channel from which the
246 message was received. I.e. a client MUST NOT receive a message on
247 one channel and then acknowledge it on another.
249 <rule implement="MUST">
250 The server MUST NOT use a zero value for delivery tags. Zero is
251 reserved for client use, meaning "all messages so far received".
254 <domain name="exchange name" type="shortstr">
257 The exchange name is a client-selected string that identifies
258 the exchange for publish methods. Exchange names may consist
259 of any mixture of digits, letters, and underscores. Exchange
260 names are scoped by the virtual host.
262 <assert check="length" value="127"/>
264 <domain name="known hosts" type="shortstr">
267 Specifies the list of equivalent or alternative hosts that the server
268 knows about, which will normally include the current server itself.
269 Clients can cache this information and use it when reconnecting to a
270 server after a failure.
272 <rule implement="MAY">
273 The server MAY leave this field empty if it knows of no other
277 <domain name="method id" type="short"/>
278 <domain name="no ack" type="bit">
279 no acknowledgement needed
281 If this field is set the server does not expect acknowledgments
282 for messages. That is, when a message is delivered to the client
283 the server automatically and silently acknowledges it on behalf
284 of the client. This functionality increases performance but at
285 the cost of reliability. Messages can get lost if a client dies
286 before it can deliver them to the application.
289 <domain name="no local" type="bit">
290 do not deliver own messages
292 If the no-local field is set the server will not send messages to
293 the client that published them.
296 <domain name="path" type="shortstr">
298 Must start with a slash "/" and continue with path names
299 separated by slashes. A path name consists of any combination
300 of at least one of [A-Za-z0-9] plus zero or more of [.-_+!=:].
302 <assert check="notnull"/>
303 <assert check="syntax" rule="path"/>
304 <assert check="length" value="127"/>
306 <domain name="peer properties" type="table">
308 This string provides a set of peer properties, used for
309 identification, debugging, and general information.
311 <rule implement="SHOULD">
312 The properties SHOULD contain these fields:
313 "product", giving the name of the peer product, "version", giving
314 the name of the peer version, "platform", giving the name of the
315 operating system, "copyright", if appropriate, and "information",
316 giving other general information.
319 <domain name="queue name" type="shortstr">
322 The queue name identifies the queue within the vhost. Queue
323 names may consist of any mixture of digits, letters, and
326 <assert check="length" value="127"/>
328 <domain name="redelivered" type="bit">
329 message is being redelivered
331 This indicates that the message has been previously delivered to
332 this or another client.
334 <rule implement="SHOULD">
335 The server SHOULD try to signal redelivered messages when it can.
336 When redelivering a message that was not successfully acknowledged,
337 the server SHOULD deliver it to the original client if possible.
339 <rule implement="MUST">
340 The client MUST NOT rely on the redelivered field but MUST take it
341 as a hint that the message may already have been processed. A
342 fully robust client must be able to track duplicate received messages
343 on non-transacted, and locally-transacted channels.
346 <domain name="reply code" type="short">
347 reply code from server
349 The reply code. The AMQ reply codes are defined in AMQ RFC 011.
351 <assert check="notnull"/>
353 <domain name="reply text" type="shortstr">
356 The localised reply text. This text can be logged as an aid to
359 <assert check="notnull"/>
361 <class name="connection" handler="connection" index="10">
363 ======================================================
365 ======================================================
367 work with socket connections
369 The connection class provides methods for a client to establish a
370 network connection to a server, and for both peers to operate the
371 connection thereafter.
374 connection = open-connection *use-connection close-connection
375 open-connection = C:protocol-header
379 C:OPEN S:OPEN-OK | S:REDIRECT
380 challenge = S:SECURE C:SECURE-OK
381 use-connection = *channel
382 close-connection = C:CLOSE S:CLOSE-OK
385 <chassis name="server" implement="MUST"/>
386 <chassis name="client" implement="MUST"/>
387 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
388 <method name="start" synchronous="1" index="10">
389 start connection negotiation
391 This method starts the connection negotiation process by telling
392 the client the protocol version that the server proposes, along
393 with a list of security mechanisms which the client can use for
396 <rule implement="MUST">
397 If the client cannot handle the protocol version suggested by the
398 server it MUST close the socket connection.
400 <rule implement="MUST">
401 The server MUST provide a protocol version that is lower than or
402 equal to that requested by the client in the protocol header. If
403 the server cannot support the specified protocol it MUST NOT send
404 this method, but MUST close the socket connection.
406 <chassis name="client" implement="MUST"/>
407 <response name="start-ok"/>
408 <field name="version major" type="octet">
409 protocol major version
411 The protocol major version that the server agrees to use, which
412 cannot be higher than the client's major version.
415 <field name="version minor" type="octet">
416 protocol major version
418 The protocol minor version that the server agrees to use, which
419 cannot be higher than the client's minor version.
422 <field name="server properties" domain="peer properties">
425 <field name="mechanisms" type="longstr">
426 available security mechanisms
428 A list of the security mechanisms that the server supports, delimited
429 by spaces. Currently ASL supports these mechanisms: PLAIN.
431 <see name="security mechanisms"/>
432 <assert check="notnull"/>
434 <field name="locales" type="longstr">
435 available message locales
437 A list of the message locales that the server supports, delimited
438 by spaces. The locale defines the language in which the server
439 will send reply texts.
441 <rule implement="MUST">
442 All servers MUST support at least the en_US locale.
444 <assert check="notnull"/>
447 <method name="start-ok" synchronous="1" index="11">
448 select security mechanism and locale
450 This method selects a SASL security mechanism. ASL uses SASL
451 (RFC2222) to negotiate authentication and encryption.
453 <chassis name="server" implement="MUST"/>
454 <field name="client properties" domain="peer properties">
457 <field name="mechanism" type="shortstr">
458 selected security mechanism
460 A single security mechanisms selected by the client, which must be
461 one of those specified by the server.
463 <rule implement="SHOULD">
464 The client SHOULD authenticate using the highest-level security
465 profile it can handle from the list provided by the server.
467 <rule implement="MUST">
468 The mechanism field MUST contain one of the security mechanisms
469 proposed by the server in the Start method. If it doesn't, the
470 server MUST close the socket.
472 <assert check="notnull"/>
474 <field name="response" type="longstr">
475 security response data
477 A block of opaque data passed to the security mechanism. The contents
478 of this data are defined by the SASL security mechanism. For the
479 PLAIN security mechanism this is defined as a field table holding
480 two fields, LOGIN and PASSWORD.
482 <assert check="notnull"/>
484 <field name="locale" type="shortstr">
485 selected message locale
487 A single message local selected by the client, which must be one
488 of those specified by the server.
490 <assert check="notnull"/>
493 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
494 <method name="secure" synchronous="1" index="20">
495 security mechanism challenge
497 The SASL protocol works by exchanging challenges and responses until
498 both peers have received sufficient information to authenticate each
499 other. This method challenges the client to provide more information.
501 <chassis name="client" implement="MUST"/>
502 <response name="secure-ok"/>
503 <field name="challenge" type="longstr">
504 security challenge data
506 Challenge information, a block of opaque binary data passed to
507 the security mechanism.
509 <see name="security mechanisms"/>
512 <method name="secure-ok" synchronous="1" index="21">
513 security mechanism response
515 This method attempts to authenticate, passing a block of SASL data
516 for the security mechanism at the server side.
518 <chassis name="server" implement="MUST"/>
519 <field name="response" type="longstr">
520 security response data
522 A block of opaque data passed to the security mechanism. The contents
523 of this data are defined by the SASL security mechanism.
525 <assert check="notnull"/>
528 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
529 <method name="tune" synchronous="1" index="30">
530 propose connection tuning parameters
532 This method proposes a set of connection configuration values
533 to the client. The client can accept and/or adjust these.
535 <chassis name="client" implement="MUST"/>
536 <response name="tune-ok"/>
537 <field name="channel max" type="short">
538 proposed maximum channels
540 The maximum total number of channels that the server allows
541 per connection. Zero means that the server does not impose a
542 fixed limit, but the number of allowed channels may be limited
543 by available server resources.
546 <field name="frame max" type="long">
547 proposed maximum frame size
549 The largest frame size that the server proposes for the
550 connection. The client can negotiate a lower value. Zero means
551 that the server does not impose any specific limit but may reject
552 very large frames if it cannot allocate resources for them.
554 <rule implement="MUST">
555 Until the frame-max has been negotiated, both peers MUST accept
556 frames of up to 4096 octets large. The minimum non-zero value for
557 the frame-max field is 4096.
560 <field name="heartbeat" type="short">
561 desired heartbeat delay
563 The delay, in seconds, of the connection heartbeat that the server
564 wants. Zero means the server does not want a heartbeat.
568 <method name="tune-ok" synchronous="1" index="31">
569 negotiate connection tuning parameters
571 This method sends the client's connection tuning parameters to the
572 server. Certain fields are negotiated, others provide capability
575 <chassis name="server" implement="MUST"/>
576 <field name="channel max" type="short">
577 negotiated maximum channels
579 The maximum total number of channels that the client will use
580 per connection. May not be higher than the value specified by
583 <rule implement="MAY">
584 The server MAY ignore the channel-max value or MAY use it for
585 tuning its resource allocation.
587 <assert check="notnull"/>
588 <assert check="le" method="tune" field="channel max"/>
590 <field name="frame max" type="long">
591 negotiated maximum frame size
593 The largest frame size that the client and server will use for
594 the connection. Zero means that the client does not impose any
595 specific limit but may reject very large frames if it cannot
596 allocate resources for them. Note that the frame-max limit
597 applies principally to content frames, where large contents
598 can be broken into frames of arbitrary size.
600 <rule implement="MUST">
601 Until the frame-max has been negotiated, both peers must accept
602 frames of up to 4096 octets large. The minimum non-zero value for
603 the frame-max field is 4096.
606 <field name="heartbeat" type="short">
607 desired heartbeat delay
609 The delay, in seconds, of the connection heartbeat that the client
610 wants. Zero means the client does not want a heartbeat.
614 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
615 <method name="open" synchronous="1" index="40">
616 open connection to virtual host
618 This method opens a connection to a virtual host, which is a
619 collection of resources, and acts to separate multiple application
620 domains within a server.
622 <rule implement="MUST">
623 The client MUST open the context before doing any work on the
626 <chassis name="server" implement="MUST"/>
627 <response name="open-ok"/>
628 <response name="redirect"/>
629 <field name="virtual host" domain="path">
631 <assert check="regexp" value="^[a-zA-Z0-9/-_]+$"/>
633 The name of the virtual host to work with.
635 <rule implement="MUST">
636 If the server supports multiple virtual hosts, it MUST enforce a
637 full separation of exchanges, queues, and all associated entities
638 per virtual host. An application, connected to a specific virtual
639 host, MUST NOT be able to access resources of another virtual host.
641 <rule implement="SHOULD">
642 The server SHOULD verify that the client has permission to access
643 the specified virtual host.
645 <rule implement="MAY">
646 The server MAY configure arbitrary limits per virtual host, such
647 as the number of each type of entity that may be used, per
648 connection and/or in total.
651 <field name="capabilities" type="shortstr">
652 required capabilities
654 The client may specify a number of capability names, delimited by
655 spaces. The server can use this string to how to process the
656 client's connection request.
659 <field name="insist" type="bit">
660 insist on connecting to server
662 In a configuration with multiple load-sharing servers, the server
663 may respond to a Connection.Open method with a Connection.Redirect.
664 The insist option tells the server that the client is insisting on
665 a connection to the specified server.
667 <rule implement="SHOULD">
668 When the client uses the insist option, the server SHOULD accept
669 the client connection unless it is technically unable to do so.
673 <method name="open-ok" synchronous="1" index="41">
674 signal that the connection is ready
676 This method signals to the client that the connection is ready for
679 <chassis name="client" implement="MUST"/>
680 <field name="known hosts" domain="known hosts"/>
682 <method name="redirect" synchronous="1" index="50">
683 asks the client to use a different server
685 This method redirects the client to another server, based on the
686 requested virtual host and/or capabilities.
688 <rule implement="SHOULD">
689 When getting the Connection.Redirect method, the client SHOULD
690 reconnect to the host specified, and if that host is not present,
691 to any of the hosts specified in the known-hosts list.
693 <chassis name="client" implement="MAY"/>
694 <field name="host" type="shortstr">
697 Specifies the server to connect to. This is an IP address or a
698 DNS name, optionally followed by a colon and a port number. If
699 no port number is specified, the client should use the default
700 port number for the protocol.
702 <assert check="notnull"/>
704 <field name="known hosts" domain="known hosts"/>
706 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
707 <method name="close" synchronous="1" index="60">
708 request a connection close
710 This method indicates that the sender wants to close the connection.
711 This may be due to internal conditions (e.g. a forced shut-down) or
712 due to an error handling a specific method, i.e. an exception. When
713 a close is due to an exception, the sender provides the class and
714 method id of the method which caused the exception.
716 <rule implement="MUST">
717 After sending this method any received method except the Close-OK
718 method MUST be discarded.
720 <rule implement="MAY">
721 The peer sending this method MAY use a counter or timeout to
722 detect failure of the other peer to respond correctly with
725 <rule implement="MUST">
726 When a server receives the Close method from a client it MUST
727 delete all server-side resources associated with the client's
728 context. A client CANNOT reconnect to a context after sending
729 or receiving a Close method.
731 <chassis name="client" implement="MUST"/>
732 <chassis name="server" implement="MUST"/>
733 <response name="close-ok"/>
734 <field name="reply code" domain="reply code"/>
735 <field name="reply text" domain="reply text"/>
736 <field name="class id" domain="class id">
739 When the close is provoked by a method exception, this is the
743 <field name="method id" domain="class id">
746 When the close is provoked by a method exception, this is the
751 <method name="close-ok" synchronous="1" index="61">
752 confirm a connection close
754 This method confirms a Connection.Close method and tells the
755 recipient that it is safe to release resources for the connection
756 and close the socket.
758 <rule implement="SHOULD">
759 A peer that detects a socket closure without having received a
760 Close-Ok handshake method SHOULD log the error.
762 <chassis name="client" implement="MUST"/>
763 <chassis name="server" implement="MUST"/>
766 <class name="channel" handler="channel" index="20">
768 ======================================================
770 ======================================================
774 The channel class provides methods for a client to establish a virtual
775 connection - a channel - to a server and for both peers to operate the
776 virtual connection thereafter.
779 channel = open-channel *use-channel close-channel
780 open-channel = C:OPEN S:OPEN-OK
781 use-channel = C:FLOW S:FLOW-OK
785 close-channel = C:CLOSE S:CLOSE-OK
788 <chassis name="server" implement="MUST"/>
789 <chassis name="client" implement="MUST"/>
790 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
791 <method name="open" synchronous="1" index="10">
792 open a channel for use
794 This method opens a virtual connection (a channel).
796 <rule implement="MUST">
797 This method MUST NOT be called when the channel is already open.
799 <chassis name="server" implement="MUST"/>
800 <response name="open-ok"/>
801 <field name="out of band" type="shortstr">
804 Configures out-of-band transfers on this channel. The syntax and
805 meaning of this field will be formally defined at a later date.
807 <assert check="null"/>
810 <method name="open-ok" synchronous="1" index="11">
811 signal that the channel is ready
813 This method signals to the client that the channel is ready for use.
815 <chassis name="client" implement="MUST"/>
817 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
818 <method name="flow" synchronous="1" index="20">
819 enable/disable flow from peer
821 This method asks the peer to pause or restart the flow of content
822 data. This is a simple flow-control mechanism that a peer can use
823 to avoid oveflowing its queues or otherwise finding itself receiving
824 more messages than it can process. Note that this method is not
825 intended for window control. The peer that receives a request to
826 stop sending content should finish sending the current content, if
827 any, and then wait until it receives a Flow restart method.
829 <rule implement="MAY">
830 When a new channel is opened, it is active. Some applications
831 assume that channels are inactive until started. To emulate this
832 behaviour a client MAY open the channel, then pause it.
834 <rule implement="SHOULD">
835 When sending content data in multiple frames, a peer SHOULD monitor
836 the channel for incoming methods and respond to a Channel.Flow as
839 <rule implement="MAY">
840 A peer MAY use the Channel.Flow method to throttle incoming content
841 data for internal reasons, for example, when exchangeing data over a
844 <rule implement="MAY">
845 The peer that requests a Channel.Flow method MAY disconnect and/or
846 ban a peer that does not respect the request.
848 <chassis name="server" implement="MUST"/>
849 <chassis name="client" implement="MUST"/>
850 <response name="flow-ok"/>
851 <field name="active" type="bit">
852 start/stop content frames
854 If 1, the peer starts sending content frames. If 0, the peer
855 stops sending content frames.
859 <method name="flow-ok" index="21">
860 confirm a flow method
862 Confirms to the peer that a flow command was received and processed.
864 <chassis name="server" implement="MUST"/>
865 <chassis name="client" implement="MUST"/>
866 <field name="active" type="bit">
869 Confirms the setting of the processed flow method: 1 means the
870 peer will start sending or continue to send content frames; 0
875 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
876 <method name="alert" index="30">
877 send a non-fatal warning message
879 This method allows the server to send a non-fatal warning to the
880 client. This is used for methods that are normally asynchronous
881 and thus do not have confirmations, and for which the server may
882 detect errors that need to be reported. Fatal errors are handled
883 as channel or connection exceptions; non-fatal errors are sent
886 <chassis name="client" implement="MUST"/>
887 <field name="reply code" domain="reply code"/>
888 <field name="reply text" domain="reply text"/>
889 <field name="details" type="table">
890 detailed information for warning
892 A set of fields that provide more information about the
893 problem. The meaning of these fields are defined on a
894 per-reply-code basis (TO BE DEFINED).
898 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
899 <method name="close" synchronous="1" index="40">
900 request a channel close
902 This method indicates that the sender wants to close the channel.
903 This may be due to internal conditions (e.g. a forced shut-down) or
904 due to an error handling a specific method, i.e. an exception. When
905 a close is due to an exception, the sender provides the class and
906 method id of the method which caused the exception.
908 <rule implement="MUST">
909 After sending this method any received method except
910 Channel.Close-OK MUST be discarded.
912 <rule implement="MAY">
913 The peer sending this method MAY use a counter or timeout to detect
914 failure of the other peer to respond correctly with Channel.Close-OK..
916 <chassis name="client" implement="MUST"/>
917 <chassis name="server" implement="MUST"/>
918 <response name="close-ok"/>
919 <field name="reply code" domain="reply code"/>
920 <field name="reply text" domain="reply text"/>
921 <field name="class id" domain="class id">
924 When the close is provoked by a method exception, this is the
928 <field name="method id" domain="method id">
931 When the close is provoked by a method exception, this is the
936 <method name="close-ok" synchronous="1" index="41">
937 confirm a channel close
939 This method confirms a Channel.Close method and tells the recipient
940 that it is safe to release resources for the channel and close the
943 <rule implement="SHOULD">
944 A peer that detects a socket closure without having received a
945 Channel.Close-Ok handshake method SHOULD log the error.
947 <chassis name="client" implement="MUST"/>
948 <chassis name="server" implement="MUST"/>
951 <class name="access" handler="connection" index="30">
953 ======================================================
955 ======================================================
957 work with access tickets
959 The protocol control access to server resources using access tickets.
960 A client must explicitly request access tickets before doing work.
961 An access ticket grants a client the right to use a specific set of
962 resources - called a "realm" - in specific ways.
965 access = C:REQUEST S:REQUEST-OK
967 <chassis name="server" implement="MUST"/>
968 <chassis name="client" implement="MUST"/>
969 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
970 <method name="request" synchronous="1" index="10">
971 request an access ticket
973 This method requests an access ticket for an access realm.
974 The server responds by granting the access ticket. If the
975 client does not have access rights to the requested realm
976 this causes a connection exception. Access tickets are a
977 per-channel resource.
979 <rule implement="MUST">
980 The realm name MUST start with either "/data" (for application
981 resources) or "/admin" (for server administration resources).
982 If the realm starts with any other path, the server MUST raise
983 a connection exception with reply code 403 (access refused).
985 <rule implement="MUST">
986 The server MUST implement the /data realm and MAY implement the
987 /admin realm. The mapping of resources to realms is not
988 defined in the protocol - this is a server-side configuration
991 <chassis name="server" implement="MUST"/>
992 <response name="request-ok"/>
993 <field name="realm" domain="path">
994 name of requested realm
995 <rule implement="MUST">
996 If the specified realm is not known to the server, the server
997 must raise a channel exception with reply code 402 (invalid
1001 <field name="exclusive" type="bit">
1002 request exclusive access
1004 Request exclusive access to the realm. If the server cannot grant
1005 this - because there are other active tickets for the realm - it
1006 raises a channel exception.
1009 <field name="passive" type="bit">
1010 request passive access
1012 Request message passive access to the specified access realm.
1013 Passive access lets a client get information about resources in
1014 the realm but not to make any changes to them.
1017 <field name="active" type="bit">
1018 request active access
1020 Request message active access to the specified access realm.
1021 Acvtive access lets a client get create and delete resources in
1025 <field name="write" type="bit">
1026 request write access
1028 Request write access to the specified access realm. Write access
1029 lets a client publish messages to all exchanges in the realm.
1032 <field name="read" type="bit">
1035 Request read access to the specified access realm. Read access
1036 lets a client consume messages from queues in the realm.
1040 <method name="request-ok" synchronous="1" index="11">
1041 grant access to server resources
1043 This method provides the client with an access ticket. The access
1044 ticket is valid within the current channel and for the lifespan of
1047 <rule implement="MUST">
1048 The client MUST NOT use access tickets except within the same
1049 channel as originally granted.
1051 <rule implement="MUST">
1052 The server MUST isolate access tickets per channel and treat an
1053 attempt by a client to mix these as a connection exception.
1055 <chassis name="client" implement="MUST"/>
1056 <field name="ticket" domain="access ticket"/>
1059 <class name="exchange" handler="channel" index="40">
1061 ======================================================
1062 == EXCHANGES (or "routers", if you prefer)
1063 == (Or matchers, plugins, extensions, agents,... Routing is just one of
1064 == the many fun things an exchange can do.)
1065 ======================================================
1069 Exchanges match and distribute messages across queues. Exchanges can be
1070 configured in the server or created at runtime.
1072 <doc name="grammar">
1073 exchange = C:DECLARE S:DECLARE-OK
1074 / C:DELETE S:DELETE-OK
1076 <chassis name="server" implement="MUST"/>
1077 <chassis name="client" implement="MUST"/>
1078 <rule implement="MUST">
1079 <test>amq_exchange_19</test>
1080 The server MUST implement the direct and fanout exchange types, and
1081 predeclare the corresponding exchanges named amq.direct and amq.fanout
1082 in each virtual host. The server MUST also predeclare a direct
1083 exchange to act as the default exchange for content Publish methods
1084 and for default queue bindings.
1086 <rule implement="SHOULD">
1087 <test>amq_exchange_20</test>
1088 The server SHOULD implement the topic exchange type, and predeclare
1089 the corresponding exchange named amq.topic in each virtual host.
1091 <rule implement="MAY">
1092 <test>amq_exchange_21</test>
1093 The server MAY implement the system exchange type, and predeclare the
1094 corresponding exchanges named amq.system in each virtual host. If the
1095 client attempts to bind a queue to the system exchange, the server
1096 MUST raise a connection exception with reply code 507 (not allowed).
1098 <rule implement="MUST">
1099 <test>amq_exchange_22</test>
1100 The default exchange MUST be defined as internal, and be inaccessible
1101 to the client except by specifying an empty exchange name in a content
1102 Publish method. That is, the server MUST NOT let clients make explicit
1103 bindings to this exchange.
1105 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1106 <method name="declare" synchronous="1" index="10">
1107 declare exchange, create if needed
1109 This method creates an exchange if it does not already exist, and if the
1110 exchange exists, verifies that it is of the correct and expected class.
1112 <rule implement="SHOULD">
1113 <test>amq_exchange_23</test>
1114 The server SHOULD support a minimum of 16 exchanges per virtual host
1115 and ideally, impose no limit except as defined by available resources.
1117 <chassis name="server" implement="MUST"/>
1118 <response name="declare-ok"/>
1119 <field name="ticket" domain="access ticket">
1121 When a client defines a new exchange, this belongs to the access realm
1122 of the ticket used. All further work done with that exchange must be
1123 done with an access ticket for the same realm.
1125 <rule implement="MUST">
1126 The client MUST provide a valid access ticket giving "active" access
1127 to the realm in which the exchange exists or will be created, or
1128 "passive" access if the if-exists flag is set.
1131 <field name="exchange" domain="exchange name">
1132 <rule implement="MUST">
1133 <test>amq_exchange_15</test>
1134 Exchange names starting with "amq." are reserved for predeclared
1135 and standardised exchanges. If the client attempts to create an
1136 exchange starting with "amq.", the server MUST raise a channel
1137 exception with reply code 403 (access refused).
1139 <assert check="regexp" value="^[a-zA-Z0-9-_.:]+$"/>
1141 <field name="type" type="shortstr">
1144 Each exchange belongs to one of a set of exchange types implemented
1145 by the server. The exchange types define the functionality of the
1146 exchange - i.e. how messages are routed through it. It is not valid
1147 or meaningful to attempt to change the type of an existing exchange.
1149 <rule implement="MUST">
1150 <test>amq_exchange_16</test>
1151 If the exchange already exists with a different type, the server
1152 MUST raise a connection exception with a reply code 507 (not allowed).
1154 <rule implement="MUST">
1155 <test>amq_exchange_18</test>
1156 If the server does not support the requested exchange type it MUST
1157 raise a connection exception with a reply code 503 (command invalid).
1159 <assert check="regexp" value="^[a-zA-Z0-9-_.:]+$"/>
1161 <field name="passive" type="bit">
1162 do not create exchange
1164 If set, the server will not create the exchange. The client can use
1165 this to check whether an exchange exists without modifying the server
1168 <rule implement="MUST">
1169 <test>amq_exchange_05</test>
1170 If set, and the exchange does not already exist, the server MUST
1171 raise a channel exception with reply code 404 (not found).
1174 <field name="durable" type="bit">
1175 request a durable exchange
1177 If set when creating a new exchange, the exchange will be marked as
1178 durable. Durable exchanges remain active when a server restarts.
1179 Non-durable exchanges (transient exchanges) are purged if/when a
1182 <rule implement="MUST">
1183 <test>amq_exchange_24</test>
1184 The server MUST support both durable and transient exchanges.
1186 <rule implement="MUST">
1187 The server MUST ignore the durable field if the exchange already
1191 <field name="auto delete" type="bit">
1192 auto-delete when unused
1194 If set, the exchange is deleted when all queues have finished
1197 <rule implement="SHOULD">
1198 <test>amq_exchange_02</test>
1199 The server SHOULD allow for a reasonable delay between the point
1200 when it determines that an exchange is not being used (or no longer
1201 used), and the point when it deletes the exchange. At the least it
1202 must allow a client to create an exchange and then bind a queue to
1203 it, with a small but non-zero delay between these two actions.
1205 <rule implement="MUST">
1206 <test>amq_exchange_25</test>
1207 The server MUST ignore the auto-delete field if the exchange already
1211 <field name="internal" type="bit">
1212 create internal exchange
1214 If set, the exchange may not be used directly by publishers, but
1215 only when bound to other exchanges. Internal exchanges are used to
1216 construct wiring that is not visible to applications.
1220 <field name = "nowait" type = "bit">
1221 do not send a reply method
1223 If set, the server will not respond to the method. The client should
1224 not wait for a reply method. If the server could not complete the
1225 method it will raise a channel or connection exception.
1229 <field name="arguments" type="table">
1230 arguments for declaration
1232 A set of arguments for the declaration. The syntax and semantics
1233 of these arguments depends on the server implementation. This
1234 field is ignored if passive is 1.
1238 <method name="declare-ok" synchronous="1" index="11">
1239 confirms an exchange declaration
1241 This method confirms a Declare method and confirms the name of the
1242 exchange, essential for automatically-named exchanges.
1244 <chassis name="client" implement="MUST"/>
1246 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1247 <method name="delete" synchronous="1" index="20">
1250 This method deletes an exchange. When an exchange is deleted all queue
1251 bindings on the exchange are cancelled.
1253 <chassis name="server" implement="MUST"/>
1254 <response name="delete-ok"/>
1255 <field name="ticket" domain="access ticket">
1256 <rule implement="MUST">
1257 The client MUST provide a valid access ticket giving "active"
1258 access rights to the exchange's access realm.
1261 <field name="exchange" domain="exchange name">
1262 <rule implement="MUST">
1263 <test>amq_exchange_11</test>
1264 The exchange MUST exist. Attempting to delete a non-existing exchange
1265 causes a channel exception.
1267 <assert check="notnull"/>
1269 <field name="if unused" type="bit">
1270 delete only if unused
1272 If set, the server will only delete the exchange if it has no queue
1273 bindings. If the exchange has queue bindings the server does not
1274 delete it but raises a channel exception instead.
1276 <rule implement="SHOULD">
1277 <test>amq_exchange_12</test>
1278 If set, the server SHOULD delete the exchange but only if it has
1281 <rule implement="SHOULD">
1282 <test>amq_exchange_13</test>
1283 If set, the server SHOULD raise a channel exception if the exchange is in
1288 <field name = "nowait" type = "bit">
1289 do not send a reply method
1291 If set, the server will not respond to the method. The client should
1292 not wait for a reply method. If the server could not complete the
1293 method it will raise a channel or connection exception.
1298 <method name="delete-ok" synchronous="1" index="21">
1299 confirm deletion of an exchange
1301 This method confirms the deletion of an exchange.
1303 <chassis name="client" implement="MUST"/>
1306 <class name="queue" handler="channel" index="50">
1308 ======================================================
1310 ======================================================
1315 Queues store and forward messages. Queues can be configured in the server
1316 or created at runtime. Queues must be attached to at least one exchange
1317 in order to receive messages from publishers.
1319 <doc name="grammar">
1320 queue = C:DECLARE S:DECLARE-OK
1322 / C:PURGE S:PURGE-OK
1323 / C:DELETE S:DELETE-OK
1325 <chassis name="server" implement="MUST"/>
1326 <chassis name="client" implement="MUST"/>
1327 <rule implement="MUST">
1328 <test>amq_queue_33</test>
1329 A server MUST allow any content class to be sent to any queue, in any
1330 mix, and queue and delivery these content classes independently. Note
1331 that all methods that fetch content off queues are specific to a given
1334 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1335 <method name="declare" synchronous="1" index="10">
1336 declare queue, create if needed
1338 This method creates or checks a queue. When creating a new queue
1339 the client can specify various properties that control the durability
1340 of the queue and its contents, and the level of sharing for the queue.
1342 <rule implement="MUST">
1343 <test>amq_queue_34</test>
1344 The server MUST create a default binding for a newly-created queue
1345 to the default exchange, which is an exchange of type 'direct'.
1347 <rule implement="SHOULD">
1348 <test>amq_queue_35</test>
1349 The server SHOULD support a minimum of 256 queues per virtual host
1350 and ideally, impose no limit except as defined by available resources.
1352 <chassis name="server" implement="MUST"/>
1353 <response name="declare-ok"/>
1354 <field name="ticket" domain="access ticket">
1356 When a client defines a new queue, this belongs to the access realm
1357 of the ticket used. All further work done with that queue must be
1358 done with an access ticket for the same realm.
1361 The client provides a valid access ticket giving "active" access
1362 to the realm in which the queue exists or will be created, or
1363 "passive" access if the if-exists flag is set.
1366 <field name="queue" domain="queue name">
1367 <rule implement="MAY">
1368 <test>amq_queue_10</test>
1369 The queue name MAY be empty, in which case the server MUST create
1370 a new queue with a unique generated name and return this to the
1371 client in the Declare-Ok method.
1373 <rule implement="MUST">
1374 <test>amq_queue_32</test>
1375 Queue names starting with "amq." are reserved for predeclared and
1376 standardised server queues. If the queue name starts with "amq."
1377 and the passive option is zero, the server MUST raise a connection
1378 exception with reply code 403 (access refused).
1380 <assert check="regexp" value="^[a-zA-Z0-9-_.:]*$"/>
1382 <field name="passive" type="bit">
1385 If set, the server will not create the queue. The client can use
1386 this to check whether a queue exists without modifying the server
1389 <rule implement="MUST">
1390 <test>amq_queue_05</test>
1391 If set, and the queue does not already exist, the server MUST
1392 respond with a reply code 404 (not found) and raise a channel
1396 <field name="durable" type="bit">
1397 request a durable queue
1399 If set when creating a new queue, the queue will be marked as
1400 durable. Durable queues remain active when a server restarts.
1401 Non-durable queues (transient queues) are purged if/when a
1402 server restarts. Note that durable queues do not necessarily
1403 hold persistent messages, although it does not make sense to
1404 send persistent messages to a transient queue.
1406 <rule implement="MUST">
1407 <test>amq_queue_03</test>
1408 The server MUST recreate the durable queue after a restart.
1410 <rule implement="MUST">
1411 <test>amq_queue_36</test>
1412 The server MUST support both durable and transient queues.
1414 <rule implement="MUST">
1415 <test>amq_queue_37</test>
1416 The server MUST ignore the durable field if the queue already
1420 <field name="exclusive" type="bit">
1421 request an exclusive queue
1423 Exclusive queues may only be consumed from by the current connection.
1424 Setting the 'exclusive' flag always implies 'auto-delete'.
1426 <rule implement="MUST">
1427 <test>amq_queue_38</test>
1428 The server MUST support both exclusive (private) and non-exclusive
1431 <rule implement="MUST">
1432 <test>amq_queue_04</test>
1433 The server MUST raise a channel exception if 'exclusive' is specified
1434 and the queue already exists and is owned by a different connection.
1437 <field name="auto delete" type="bit">
1438 auto-delete queue when unused
1440 If set, the queue is deleted when all consumers have finished
1441 using it. Last consumer can be cancelled either explicitly or because
1442 its channel is closed. If there was no consumer ever on the queue, it
1445 <rule implement="SHOULD">
1446 <test>amq_queue_02</test>
1447 The server SHOULD allow for a reasonable delay between the point
1448 when it determines that a queue is not being used (or no longer
1449 used), and the point when it deletes the queue. At the least it
1450 must allow a client to create a queue and then create a consumer
1451 to read from it, with a small but non-zero delay between these
1452 two actions. The server should equally allow for clients that may
1453 be disconnected prematurely, and wish to re-consume from the same
1454 queue without losing messages. We would recommend a configurable
1455 timeout, with a suitable default value being one minute.
1457 <rule implement="MUST">
1458 <test>amq_queue_31</test>
1459 The server MUST ignore the auto-delete field if the queue already
1463 <field name = "nowait" type = "bit">
1464 do not send a reply method
1466 If set, the server will not respond to the method. The client should
1467 not wait for a reply method. If the server could not complete the
1468 method it will raise a channel or connection exception.
1472 <field name="arguments" type="table">
1473 arguments for declaration
1475 A set of arguments for the declaration. The syntax and semantics
1476 of these arguments depends on the server implementation. This
1477 field is ignored if passive is 1.
1481 <method name="declare-ok" synchronous="1" index="11">
1482 confirms a queue definition
1484 This method confirms a Declare method and confirms the name of the
1485 queue, essential for automatically-named queues.
1487 <chassis name="client" implement="MUST"/>
1488 <field name="queue" domain="queue name">
1490 Reports the name of the queue. If the server generated a queue
1491 name, this field contains that name.
1493 <assert check="notnull"/>
1495 <field name="message count" type="long">
1496 number of messages in queue
1498 Reports the number of messages in the queue, which will be zero
1499 for newly-created queues.
1502 <field name="consumer count" type="long">
1505 Reports the number of active consumers for the queue. Note that
1506 consumers can suspend activity (Channel.Flow) in which case they
1507 do not appear in this count.
1511 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1512 <method name="bind" synchronous="1" index="20">
1513 bind queue to an exchange
1515 This method binds a queue to an exchange. Until a queue is
1516 bound it will not receive any messages. In a classic messaging
1517 model, store-and-forward queues are bound to a dest exchange
1518 and subscription queues are bound to a dest_wild exchange.
1520 <rule implement="MUST">
1521 <test>amq_queue_25</test>
1522 A server MUST allow ignore duplicate bindings - that is, two or
1523 more bind methods for a specific queue, with identical arguments
1524 - without treating these as an error.
1526 <rule implement="MUST">
1527 <test>amq_queue_39</test>
1528 If a bind fails, the server MUST raise a connection exception.
1530 <rule implement="MUST">
1531 <test>amq_queue_12</test>
1532 The server MUST NOT allow a durable queue to bind to a transient
1533 exchange. If the client attempts this the server MUST raise a
1536 <rule implement="SHOULD">
1537 <test>amq_queue_13</test>
1538 Bindings for durable queues are automatically durable and the
1539 server SHOULD restore such bindings after a server restart.
1541 <rule implement="MUST">
1542 <test>amq_queue_17</test>
1543 If the client attempts to an exchange that was declared as internal,
1544 the server MUST raise a connection exception with reply code 530
1547 <rule implement="SHOULD">
1548 <test>amq_queue_40</test>
1549 The server SHOULD support at least 4 bindings per queue, and
1550 ideally, impose no limit except as defined by available resources.
1552 <chassis name="server" implement="MUST"/>
1553 <response name="bind-ok"/>
1554 <field name="ticket" domain="access ticket">
1556 The client provides a valid access ticket giving "active"
1557 access rights to the queue's access realm.
1561 <field name = "queue" domain = "queue name">
1563 Specifies the name of the queue to bind. If the queue name is
1564 empty, refers to the current queue for the channel, which is
1565 the last declared queue.
1568 If the client did not previously declare a queue, and the queue
1569 name in this method is empty, the server MUST raise a connection
1570 exception with reply code 530 (not allowed).
1572 <doc name = "rule" test = "amq_queue_26">
1573 If the queue does not exist the server MUST raise a channel exception
1574 with reply code 404 (not found).
1578 <field name="exchange" domain="exchange name">
1579 The name of the exchange to bind to.
1580 <rule implement="MUST">
1581 <test>amq_queue_14</test>
1582 If the exchange does not exist the server MUST raise a channel
1583 exception with reply code 404 (not found).
1586 <field name="routing key" type="shortstr">
1589 Specifies the routing key for the binding. The routing key is
1590 used for routing messages depending on the exchange configuration.
1591 Not all exchanges use a routing key - refer to the specific
1592 exchange documentation. If the routing key is empty and the queue
1593 name is empty, the routing key will be the current queue for the
1594 channel, which is the last declared queue.
1598 <field name = "nowait" type = "bit">
1599 do not send a reply method
1601 If set, the server will not respond to the method. The client should
1602 not wait for a reply method. If the server could not complete the
1603 method it will raise a channel or connection exception.
1607 <field name="arguments" type="table">
1608 arguments for binding
1610 A set of arguments for the binding. The syntax and semantics of
1611 these arguments depends on the exchange class.
1615 <method name="bind-ok" synchronous="1" index="21">
1616 confirm bind successful
1618 This method confirms that the bind was successful.
1620 <chassis name="client" implement="MUST"/>
1623 <!-- Unofficial additions to the 0-8 protocol, lifted from the 0-9
1624 protocol specification: queue.unbind, queue.unbind-ok -->
1626 <method name = "unbind" synchronous = "1" index = "50" label = "unbind a queue from an exchange">
1627 <doc>This method unbinds a queue from an exchange.</doc>
1629 <doc>If a unbind fails, the server MUST raise a connection exception.</doc>
1631 <chassis name="server" implement="MUST"/>
1632 <response name="unbind-ok"/>
1634 <field name = "ticket" domain = "access ticket">
1636 The client provides a valid access ticket giving "active"
1637 access rights to the queue's access realm.
1641 <field name = "queue" domain = "queue name">
1642 <doc>Specifies the name of the queue to unbind.</doc>
1645 If the queue does not exist the server MUST raise a channel exception
1646 with reply code 404 (not found).
1651 <field name = "exchange" domain = "exchange name">
1652 <doc>The name of the exchange to unbind from.</doc>
1655 If the exchange does not exist the server MUST raise a channel
1656 exception with reply code 404 (not found).
1661 <field name = "routing key" domain = "shortstr" label = "routing key of binding">
1662 <doc>Specifies the routing key of the binding to unbind.</doc>
1665 <field name = "arguments" domain = "table" label = "arguments of binding">
1666 <doc>Specifies the arguments of the binding to unbind.</doc>
1670 <method name = "unbind-ok" synchronous = "1" index = "51" label = "confirm unbind successful">
1671 <doc>This method confirms that the unbind was successful.</doc>
1672 <chassis name = "client" implement = "MUST"/>
1675 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1676 <method name="purge" synchronous="1" index="30">
1679 This method removes all messages from a queue. It does not cancel
1680 consumers. Purged messages are deleted without any formal "undo"
1683 <rule implement="MUST">
1684 <test>amq_queue_15</test>
1685 A call to purge MUST result in an empty queue.
1687 <rule implement="MUST">
1688 <test>amq_queue_41</test>
1689 On transacted channels the server MUST not purge messages that have
1690 already been sent to a client but not yet acknowledged.
1692 <rule implement="MAY">
1693 <test>amq_queue_42</test>
1694 The server MAY implement a purge queue or log that allows system
1695 administrators to recover accidentally-purged messages. The server
1696 SHOULD NOT keep purged messages in the same storage spaces as the
1697 live messages since the volumes of purged messages may get very
1700 <chassis name="server" implement="MUST"/>
1701 <response name="purge-ok"/>
1702 <field name="ticket" domain="access ticket">
1704 The access ticket must be for the access realm that holds the
1707 <rule implement="MUST">
1708 The client MUST provide a valid access ticket giving "read" access
1709 rights to the queue's access realm. Note that purging a queue is
1710 equivalent to reading all messages and discarding them.
1713 <field name = "queue" domain = "queue name">
1715 Specifies the name of the queue to purge. If the queue name is
1716 empty, refers to the current queue for the channel, which is
1717 the last declared queue.
1720 If the client did not previously declare a queue, and the queue
1721 name in this method is empty, the server MUST raise a connection
1722 exception with reply code 530 (not allowed).
1724 <doc name = "rule" test = "amq_queue_16">
1725 The queue must exist. Attempting to purge a non-existing queue
1726 causes a channel exception.
1730 <field name = "nowait" type = "bit">
1731 do not send a reply method
1733 If set, the server will not respond to the method. The client should
1734 not wait for a reply method. If the server could not complete the
1735 method it will raise a channel or connection exception.
1739 <method name="purge-ok" synchronous="1" index="31">
1740 confirms a queue purge
1742 This method confirms the purge of a queue.
1744 <chassis name="client" implement="MUST"/>
1745 <field name="message count" type="long">
1746 number of messages purged
1748 Reports the number of messages purged.
1752 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1753 <method name="delete" synchronous="1" index="40">
1756 This method deletes a queue. When a queue is deleted any pending
1757 messages are sent to a dead-letter queue if this is defined in the
1758 server configuration, and all consumers on the queue are cancelled.
1760 <rule implement="SHOULD">
1761 <test>amq_queue_43</test>
1762 The server SHOULD use a dead-letter queue to hold messages that
1763 were pending on a deleted queue, and MAY provide facilities for
1764 a system administrator to move these messages back to an active
1767 <chassis name="server" implement="MUST"/>
1768 <response name="delete-ok"/>
1769 <field name="ticket" domain="access ticket">
1771 The client provides a valid access ticket giving "active"
1772 access rights to the queue's access realm.
1776 <field name = "queue" domain = "queue name">
1778 Specifies the name of the queue to delete. If the queue name is
1779 empty, refers to the current queue for the channel, which is the
1780 last declared queue.
1783 If the client did not previously declare a queue, and the queue
1784 name in this method is empty, the server MUST raise a connection
1785 exception with reply code 530 (not allowed).
1787 <doc name = "rule" test = "amq_queue_21">
1788 The queue must exist. Attempting to delete a non-existing queue
1789 causes a channel exception.
1793 <field name="if unused" type="bit">
1794 delete only if unused
1796 If set, the server will only delete the queue if it has no
1797 consumers. If the queue has consumers the server does does not
1798 delete it but raises a channel exception instead.
1800 <rule implement="MUST">
1801 <test>amq_queue_29</test>
1802 <test>amq_queue_30</test>
1803 The server MUST respect the if-unused flag when deleting a queue.
1806 <field name="if empty" type="bit">
1807 delete only if empty
1808 <test>amq_queue_27</test>
1810 If set, the server will only delete the queue if it has no
1811 messages. If the queue is not empty the server raises a channel
1815 <field name = "nowait" type = "bit">
1816 do not send a reply method
1818 If set, the server will not respond to the method. The client should
1819 not wait for a reply method. If the server could not complete the
1820 method it will raise a channel or connection exception.
1825 <method name="delete-ok" synchronous="1" index="41">
1826 confirm deletion of a queue
1828 This method confirms the deletion of a queue.
1830 <chassis name="client" implement="MUST"/>
1831 <field name="message count" type="long">
1832 number of messages purged
1834 Reports the number of messages purged.
1839 <class name="basic" handler="channel" index="60">
1841 ======================================================
1843 ======================================================
1845 work with basic content
1847 The Basic class provides methods that support an industry-standard
1851 <doc name = "grammar">
1852 basic = C:QOS S:QOS-OK
1853 / C:CONSUME S:CONSUME-OK
1854 / C:CANCEL S:CANCEL-OK
1858 / C:GET ( S:GET-OK content / S:GET-EMPTY )
1863 <chassis name = "server" implement = "MUST" />
1864 <chassis name = "client" implement = "MAY" />
1866 <doc name = "rule" test = "amq_basic_08">
1867 The server SHOULD respect the persistent property of basic messages
1868 and SHOULD make a best-effort to hold persistent basic messages on a
1869 reliable storage mechanism.
1871 <doc name = "rule" test = "amq_basic_09">
1872 The server MUST NOT discard a persistent basic message in case of a
1873 queue overflow. The server MAY use the Channel.Flow method to slow
1874 or stop a basic message publisher when necessary.
1876 <doc name = "rule" test = "amq_basic_10">
1877 The server MAY overflow non-persistent basic messages to persistent
1878 storage and MAY discard or dead-letter non-persistent basic messages
1879 on a priority basis if the queue size exceeds some configured limit.
1881 <doc name = "rule" test = "amq_basic_11">
1882 The server MUST implement at least 2 priority levels for basic
1883 messages, where priorities 0-4 and 5-9 are treated as two distinct
1884 levels. The server MAY implement up to 10 priority levels.
1886 <doc name = "rule" test = "amq_basic_12">
1887 The server MUST deliver messages of the same priority in order
1888 irrespective of their individual persistence.
1890 <doc name = "rule" test = "amq_basic_13">
1891 The server MUST support both automatic and explicit acknowledgements
1895 <!-- These are the properties for a Basic content -->
1897 <field name = "content type" type = "shortstr">
1900 <field name = "content encoding" type = "shortstr">
1901 MIME content encoding
1903 <field name = "headers" type = "table">
1904 Message header field table
1906 <field name = "delivery mode" type = "octet">
1907 Non-persistent (1) or persistent (2)
1909 <field name = "priority" type = "octet">
1910 The message priority, 0 to 9
1912 <field name = "correlation id" type = "shortstr">
1913 The application correlation identifier
1915 <field name = "reply to" type = "shortstr">
1916 The destination to reply to
1918 <field name = "expiration" type = "shortstr">
1919 Message expiration specification
1921 <field name = "message id" type = "shortstr">
1922 The application message identifier
1924 <field name = "timestamp" type = "timestamp">
1925 The message timestamp
1927 <field name = "type" type = "shortstr">
1928 The message type name
1930 <field name = "user id" type = "shortstr">
1931 The creating user id
1933 <field name = "app id" type = "shortstr">
1934 The creating application id
1936 <field name = "cluster id" type = "shortstr">
1937 Intra-cluster routing identifier
1941 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1943 <method name = "qos" synchronous = "1" index = "10">
1944 specify quality of service
1946 This method requests a specific quality of service. The QoS can
1947 be specified for the current channel or for all channels on the
1948 connection. The particular properties and semantics of a qos method
1949 always depend on the content class semantics. Though the qos method
1950 could in principle apply to both peers, it is currently meaningful
1951 only for the server.
1953 <chassis name = "server" implement = "MUST" />
1954 <response name = "qos-ok" />
1956 <field name = "prefetch size" type = "long">
1957 prefetch window in octets
1959 The client can request that messages be sent in advance so that
1960 when the client finishes processing a message, the following
1961 message is already held locally, rather than needing to be sent
1962 down the channel. Prefetching gives a performance improvement.
1963 This field specifies the prefetch window size in octets. The
1964 server will send a message in advance if it is equal to or
1965 smaller in size than the available prefetch size (and also falls
1966 into other prefetch limits). May be set to zero, meaning "no
1967 specific limit", although other prefetch limits may still apply.
1968 The prefetch-size is ignored if the no-ack option is set.
1970 <doc name = "rule" test = "amq_basic_17">
1971 The server MUST ignore this setting when the client is not
1972 processing any messages - i.e. the prefetch size does not limit
1973 the transfer of single messages to a client, only the sending in
1974 advance of more messages while the client still has one or more
1975 unacknowledged messages.
1979 <field name = "prefetch count" type = "short">
1980 prefetch window in messages
1982 Specifies a prefetch window in terms of whole messages. This
1983 field may be used in combination with the prefetch-size field;
1984 a message will only be sent in advance if both prefetch windows
1985 (and those at the channel and connection level) allow it.
1986 The prefetch-count is ignored if the no-ack option is set.
1988 <doc name = "rule" test = "amq_basic_18">
1989 The server MAY send less data in advance than allowed by the
1990 client's specified prefetch windows but it MUST NOT send more.
1994 <field name = "global" type = "bit">
1995 apply to entire connection
1997 By default the QoS settings apply to the current channel only. If
1998 this field is set, they are applied to the entire connection.
2003 <method name = "qos-ok" synchronous = "1" index = "11">
2004 confirm the requested qos
2006 This method tells the client that the requested QoS levels could
2007 be handled by the server. The requested QoS applies to all active
2008 consumers until a new QoS is defined.
2010 <chassis name = "client" implement = "MUST" />
2013 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2015 <method name = "consume" synchronous = "1" index = "20">
2016 start a queue consumer
2018 This method asks the server to start a "consumer", which is a
2019 transient request for messages from a specific queue. Consumers
2020 last as long as the channel they were created on, or until the
2021 client cancels them.
2023 <doc name = "rule" test = "amq_basic_01">
2024 The server SHOULD support at least 16 consumers per queue, unless
2025 the queue was declared as private, and ideally, impose no limit
2026 except as defined by available resources.
2028 <chassis name = "server" implement = "MUST" />
2029 <response name = "consume-ok" />
2031 <field name = "ticket" domain = "access ticket">
2033 The client MUST provide a valid access ticket giving "read" access
2034 rights to the realm for the queue.
2038 <field name = "queue" domain = "queue name">
2040 Specifies the name of the queue to consume from. If the queue name
2041 is null, refers to the current queue for the channel, which is the
2042 last declared queue.
2045 If the client did not previously declare a queue, and the queue name
2046 in this method is empty, the server MUST raise a connection exception
2047 with reply code 530 (not allowed).
2051 <field name = "consumer tag" domain = "consumer tag">
2053 Specifies the identifier for the consumer. The consumer tag is
2054 local to a connection, so two clients can use the same consumer
2055 tags. If this field is empty the server will generate a unique
2058 <doc name = "rule" test = "todo">
2059 The tag MUST NOT refer to an existing consumer. If the client
2060 attempts to create two consumers with the same non-empty tag
2061 the server MUST raise a connection exception with reply code
2066 <field name = "no local" domain = "no local" />
2068 <field name = "no ack" domain = "no ack" />
2070 <field name = "exclusive" type = "bit">
2071 request exclusive access
2073 Request exclusive consumer access, meaning only this consumer can
2076 <doc name = "rule" test = "amq_basic_02">
2077 If the server cannot grant exclusive access to the queue when asked,
2078 - because there are other consumers active - it MUST raise a channel
2079 exception with return code 403 (access refused).
2083 <field name = "nowait" type = "bit">
2084 do not send a reply method
2086 If set, the server will not respond to the method. The client should
2087 not wait for a reply method. If the server could not complete the
2088 method it will raise a channel or connection exception.
2093 <method name = "consume-ok" synchronous = "1" index = "21">
2094 confirm a new consumer
2096 The server provides the client with a consumer tag, which is used
2097 by the client for methods called on the consumer at a later stage.
2099 <chassis name = "client" implement = "MUST" />
2101 <field name = "consumer tag" domain = "consumer tag">
2103 Holds the consumer tag specified by the client or provided by
2110 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2112 <method name = "cancel" synchronous = "1" index = "30">
2113 end a queue consumer
2114 <doc test = "amq_basic_04">
2115 This method cancels a consumer. This does not affect already
2116 delivered messages, but it does mean the server will not send any
2117 more messages for that consumer. The client may receive an
2118 abitrary number of messages in between sending the cancel method
2119 and receiving the cancel-ok reply.
2121 <doc name = "rule" test = "todo">
2122 If the queue no longer exists when the client sends a cancel command,
2123 or the consumer has been cancelled for other reasons, this command
2126 <chassis name = "server" implement = "MUST" />
2127 <response name = "cancel-ok" />
2129 <field name = "consumer tag" domain = "consumer tag" />
2131 <field name = "nowait" type = "bit">
2132 do not send a reply method
2134 If set, the server will not respond to the method. The client should
2135 not wait for a reply method. If the server could not complete the
2136 method it will raise a channel or connection exception.
2141 <method name = "cancel-ok" synchronous = "1" index = "31">
2142 confirm a cancelled consumer
2144 This method confirms that the cancellation was completed.
2146 <chassis name = "client" implement = "MUST" />
2148 <field name = "consumer tag" domain = "consumer tag" />
2152 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2154 <method name = "publish" content = "1" index = "40">
2157 This method publishes a message to a specific exchange. The message
2158 will be routed to queues as defined by the exchange configuration
2159 and distributed to any active consumers when the transaction, if any,
2162 <chassis name = "server" implement = "MUST" />
2164 <field name = "ticket" domain = "access ticket">
2166 The client MUST provide a valid access ticket giving "write"
2167 access rights to the access realm for the exchange.
2171 <field name = "exchange" domain = "exchange name">
2173 Specifies the name of the exchange to publish to. The exchange
2174 name can be empty, meaning the default exchange. If the exchange
2175 name is specified, and that exchange does not exist, the server
2176 will raise a channel exception.
2178 <doc name = "rule" test = "amq_basic_06">
2179 The server MUST accept a blank exchange name to mean the default
2182 <doc name = "rule" test = "amq_basic_14">
2183 If the exchange was declared as an internal exchange, the server
2184 MUST raise a channel exception with a reply code 403 (access
2187 <doc name = "rule" test = "amq_basic_15">
2188 The exchange MAY refuse basic content in which case it MUST raise
2189 a channel exception with reply code 540 (not implemented).
2193 <field name = "routing key" type = "shortstr">
2196 Specifies the routing key for the message. The routing key is
2197 used for routing messages depending on the exchange configuration.
2201 <field name = "mandatory" type = "bit">
2202 indicate mandatory routing
2204 This flag tells the server how to react if the message cannot be
2205 routed to a queue. If this flag is set, the server will return an
2206 unroutable message with a Return method. If this flag is zero, the
2207 server silently drops the message.
2209 <doc name = "rule" test = "amq_basic_07">
2210 The server SHOULD implement the mandatory flag.
2214 <field name = "immediate" type = "bit">
2215 request immediate delivery
2217 This flag tells the server how to react if the message cannot be
2218 routed to a queue consumer immediately. If this flag is set, the
2219 server will return an undeliverable message with a Return method.
2220 If this flag is zero, the server will queue the message, but with
2221 no guarantee that it will ever be consumed.
2223 <doc name = "rule" test = "amq_basic_16">
2224 The server SHOULD implement the immediate flag.
2229 <method name = "return" content = "1" index = "50">
2230 return a failed message
2232 This method returns an undeliverable message that was published
2233 with the "immediate" flag set, or an unroutable message published
2234 with the "mandatory" flag set. The reply code and text provide
2235 information about the reason that the message was undeliverable.
2237 <chassis name = "client" implement = "MUST" />
2239 <field name = "reply code" domain = "reply code" />
2240 <field name = "reply text" domain = "reply text" />
2242 <field name = "exchange" domain = "exchange name">
2244 Specifies the name of the exchange that the message was
2245 originally published to.
2249 <field name = "routing key" type = "shortstr">
2252 Specifies the routing key name specified when the message was
2259 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2261 <method name = "deliver" content = "1" index = "60">
2262 notify the client of a consumer message
2264 This method delivers a message to the client, via a consumer. In
2265 the asynchronous message delivery model, the client starts a
2266 consumer using the Consume method, then the server responds with
2267 Deliver methods as and when messages arrive for that consumer.
2269 <doc name = "rule" test = "amq_basic_19">
2270 The server SHOULD track the number of times a message has been
2271 delivered to clients and when a message is redelivered a certain
2272 number of times - e.g. 5 times - without being acknowledged, the
2273 server SHOULD consider the message to be unprocessable (possibly
2274 causing client applications to abort), and move the message to a
2277 <chassis name = "client" implement = "MUST" />
2279 <field name = "consumer tag" domain = "consumer tag" />
2281 <field name = "delivery tag" domain = "delivery tag" />
2283 <field name = "redelivered" domain = "redelivered" />
2285 <field name = "exchange" domain = "exchange name">
2287 Specifies the name of the exchange that the message was
2288 originally published to.
2292 <field name = "routing key" type = "shortstr">
2295 Specifies the routing key name specified when the message was
2302 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2304 <method name = "get" synchronous = "1" index = "70">
2305 direct access to a queue
2307 This method provides a direct access to the messages in a queue
2308 using a synchronous dialogue that is designed for specific types of
2309 application where synchronous functionality is more important than
2312 <response name = "get-ok" />
2313 <response name = "get-empty" />
2314 <chassis name = "server" implement = "MUST" />
2316 <field name = "ticket" domain = "access ticket">
2318 The client MUST provide a valid access ticket giving "read"
2319 access rights to the realm for the queue.
2323 <field name = "queue" domain = "queue name">
2325 Specifies the name of the queue to consume from. If the queue name
2326 is null, refers to the current queue for the channel, which is the
2327 last declared queue.
2330 If the client did not previously declare a queue, and the queue name
2331 in this method is empty, the server MUST raise a connection exception
2332 with reply code 530 (not allowed).
2336 <field name = "no ack" domain = "no ack" />
2339 <method name = "get-ok" synchronous = "1" content = "1" index = "71">
2340 provide client with a message
2342 This method delivers a message to the client following a get
2343 method. A message delivered by 'get-ok' must be acknowledged
2344 unless the no-ack option was set in the get method.
2346 <chassis name = "client" implement = "MAY" />
2348 <field name = "delivery tag" domain = "delivery tag" />
2350 <field name = "redelivered" domain = "redelivered" />
2352 <field name = "exchange" domain = "exchange name">
2354 Specifies the name of the exchange that the message was originally
2355 published to. If empty, the message was published to the default
2360 <field name = "routing key" type = "shortstr">
2363 Specifies the routing key name specified when the message was
2368 <field name = "message count" type = "long" >
2369 number of messages pending
2371 This field reports the number of messages pending on the queue,
2372 excluding the message being delivered. Note that this figure is
2373 indicative, not reliable, and can change arbitrarily as messages
2374 are added to the queue and removed by other clients.
2380 <method name = "get-empty" synchronous = "1" index = "72">
2381 indicate no messages available
2383 This method tells the client that the queue has no messages
2384 available for the client.
2386 <chassis name = "client" implement = "MAY" />
2388 <field name = "cluster id" type = "shortstr">
2391 For use by cluster applications, should not be used by
2392 client applications.
2397 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2399 <method name = "ack" index = "80">
2400 acknowledge one or more messages
2402 This method acknowledges one or more messages delivered via the
2403 Deliver or Get-Ok methods. The client can ask to confirm a
2404 single message or a set of messages up to and including a specific
2407 <chassis name = "server" implement = "MUST" />
2408 <field name = "delivery tag" domain = "delivery tag" />
2410 <field name = "multiple" type = "bit">
2411 acknowledge multiple messages
2413 If set to 1, the delivery tag is treated as "up to and including",
2414 so that the client can acknowledge multiple messages with a single
2415 method. If set to zero, the delivery tag refers to a single
2416 message. If the multiple field is 1, and the delivery tag is zero,
2417 tells the server to acknowledge all outstanding mesages.
2419 <doc name = "rule" test = "amq_basic_20">
2420 The server MUST validate that a non-zero delivery-tag refers to an
2421 delivered message, and raise a channel exception if this is not the
2427 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2429 <method name = "reject" index = "90">
2430 reject an incoming message
2432 This method allows a client to reject a message. It can be used to
2433 interrupt and cancel large incoming messages, or return untreatable
2434 messages to their original queue.
2436 <doc name = "rule" test = "amq_basic_21">
2437 The server SHOULD be capable of accepting and process the Reject
2438 method while sending message content with a Deliver or Get-Ok
2439 method. I.e. the server should read and process incoming methods
2440 while sending output frames. To cancel a partially-send content,
2441 the server sends a content body frame of size 1 (i.e. with no data
2442 except the frame-end octet).
2444 <doc name = "rule" test = "amq_basic_22">
2445 The server SHOULD interpret this method as meaning that the client
2446 is unable to process the message at this time.
2449 A client MUST NOT use this method as a means of selecting messages
2450 to process. A rejected message MAY be discarded or dead-lettered,
2451 not necessarily passed to another client.
2453 <chassis name = "server" implement = "MUST" />
2455 <field name = "delivery tag" domain = "delivery tag" />
2457 <field name = "requeue" type = "bit">
2460 If this field is zero, the message will be discarded. If this bit
2461 is 1, the server will attempt to requeue the message.
2463 <doc name = "rule" test = "amq_basic_23">
2464 The server MUST NOT deliver the message to the same client within
2465 the context of the current channel. The recommended strategy is
2466 to attempt to deliver the message to an alternative consumer, and
2467 if that is not possible, to move the message to a dead-letter
2468 queue. The server MAY use more sophisticated tracking to hold
2469 the message on the queue and redeliver it to the same client at
2475 <method name = "recover" index = "100">
2476 redeliver unacknowledged messages. This method is only allowed on non-transacted channels.
2478 This method asks the broker to redeliver all unacknowledged messages on a
2479 specifieid channel. Zero or more messages may be redelivered.
2481 <chassis name = "server" implement = "MUST" />
2483 <field name = "requeue" type = "bit">
2486 If this field is zero, the message will be redelivered to the original recipient. If this bit
2487 is 1, the server will attempt to requeue the message, potentially then delivering it to an
2488 alternative subscriber.
2493 The server MUST set the redelivered flag on all messages that are resent.
2496 The server MUST raise a channel exception if this is called on a transacted channel.
2504 <class name="file" handler="channel" index="70">
2506 ======================================================
2508 ======================================================
2510 work with file content
2512 The file class provides methods that support reliable file transfer.
2513 File messages have a specific set of properties that are required for
2514 interoperability with file transfer applications. File messages and
2515 acknowledgements are subject to channel transactions. Note that the
2516 file class does not provide message browsing methods; these are not
2517 compatible with the staging model. Applications that need browsable
2518 file transfer should use Basic content and the Basic class.
2521 <doc name = "grammar">
2522 file = C:QOS S:QOS-OK
2523 / C:CONSUME S:CONSUME-OK
2524 / C:CANCEL S:CANCEL-OK
2525 / C:OPEN S:OPEN-OK C:STAGE content
2526 / S:OPEN C:OPEN-OK S:STAGE content
2534 <chassis name = "server" implement = "MAY" />
2535 <chassis name = "client" implement = "MAY" />
2538 The server MUST make a best-effort to hold file messages on a
2539 reliable storage mechanism.
2542 The server MUST NOT discard a file message in case of a queue
2543 overflow. The server MUST use the Channel.Flow method to slow or stop
2544 a file message publisher when necessary.
2547 The server MUST implement at least 2 priority levels for file
2548 messages, where priorities 0-4 and 5-9 are treated as two distinct
2549 levels. The server MAY implement up to 10 priority levels.
2552 The server MUST support both automatic and explicit acknowledgements
2556 <!-- These are the properties for a File content -->
2558 <field name = "content type" type = "shortstr">
2561 <field name = "content encoding" type = "shortstr">
2562 MIME content encoding
2564 <field name = "headers" type = "table">
2565 Message header field table
2567 <field name = "priority" type = "octet">
2568 The message priority, 0 to 9
2570 <field name = "reply to" type = "shortstr">
2571 The destination to reply to
2573 <field name = "message id" type = "shortstr">
2574 The application message identifier
2576 <field name = "filename" type = "shortstr">
2577 The message filename
2579 <field name = "timestamp" type = "timestamp">
2580 The message timestamp
2582 <field name = "cluster id" type = "shortstr">
2583 Intra-cluster routing identifier
2587 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2589 <method name = "qos" synchronous = "1" index = "10">
2590 specify quality of service
2592 This method requests a specific quality of service. The QoS can
2593 be specified for the current channel or for all channels on the
2594 connection. The particular properties and semantics of a qos method
2595 always depend on the content class semantics. Though the qos method
2596 could in principle apply to both peers, it is currently meaningful
2597 only for the server.
2599 <chassis name = "server" implement = "MUST" />
2600 <response name = "qos-ok" />
2602 <field name = "prefetch size" type = "long">
2603 prefetch window in octets
2605 The client can request that messages be sent in advance so that
2606 when the client finishes processing a message, the following
2607 message is already held locally, rather than needing to be sent
2608 down the channel. Prefetching gives a performance improvement.
2609 This field specifies the prefetch window size in octets. May be
2610 set to zero, meaning "no specific limit". Note that other
2611 prefetch limits may still apply. The prefetch-size is ignored
2612 if the no-ack option is set.
2616 <field name = "prefetch count" type = "short">
2617 prefetch window in messages
2619 Specifies a prefetch window in terms of whole messages. This
2620 is compatible with some file API implementations. This field
2621 may be used in combination with the prefetch-size field; a
2622 message will only be sent in advance if both prefetch windows
2623 (and those at the channel and connection level) allow it.
2624 The prefetch-count is ignored if the no-ack option is set.
2627 The server MAY send less data in advance than allowed by the
2628 client's specified prefetch windows but it MUST NOT send more.
2632 <field name = "global" type = "bit">
2633 apply to entire connection
2635 By default the QoS settings apply to the current channel only. If
2636 this field is set, they are applied to the entire connection.
2641 <method name = "qos-ok" synchronous = "1" index = "11">
2642 confirm the requested qos
2644 This method tells the client that the requested QoS levels could
2645 be handled by the server. The requested QoS applies to all active
2646 consumers until a new QoS is defined.
2648 <chassis name = "client" implement = "MUST" />
2651 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2653 <method name = "consume" synchronous = "1" index = "20">
2654 start a queue consumer
2656 This method asks the server to start a "consumer", which is a
2657 transient request for messages from a specific queue. Consumers
2658 last as long as the channel they were created on, or until the
2659 client cancels them.
2662 The server SHOULD support at least 16 consumers per queue, unless
2663 the queue was declared as private, and ideally, impose no limit
2664 except as defined by available resources.
2666 <chassis name = "server" implement = "MUST" />
2667 <response name = "consume-ok" />
2669 <field name = "ticket" domain = "access ticket">
2671 The client MUST provide a valid access ticket giving "read" access
2672 rights to the realm for the queue.
2676 <field name = "queue" domain = "queue name">
2678 Specifies the name of the queue to consume from. If the queue name
2679 is null, refers to the current queue for the channel, which is the
2680 last declared queue.
2683 If the client did not previously declare a queue, and the queue name
2684 in this method is empty, the server MUST raise a connection exception
2685 with reply code 530 (not allowed).
2689 <field name = "consumer tag" domain = "consumer tag">
2691 Specifies the identifier for the consumer. The consumer tag is
2692 local to a connection, so two clients can use the same consumer
2693 tags. If this field is empty the server will generate a unique
2696 <doc name = "rule" test = "todo">
2697 The tag MUST NOT refer to an existing consumer. If the client
2698 attempts to create two consumers with the same non-empty tag
2699 the server MUST raise a connection exception with reply code
2704 <field name = "no local" domain = "no local" />
2706 <field name = "no ack" domain = "no ack" />
2708 <field name = "exclusive" type = "bit">
2709 request exclusive access
2711 Request exclusive consumer access, meaning only this consumer can
2714 <doc name = "rule" test = "amq_file_00">
2715 If the server cannot grant exclusive access to the queue when asked,
2716 - because there are other consumers active - it MUST raise a channel
2717 exception with return code 405 (resource locked).
2721 <field name = "nowait" type = "bit">
2722 do not send a reply method
2724 If set, the server will not respond to the method. The client should
2725 not wait for a reply method. If the server could not complete the
2726 method it will raise a channel or connection exception.
2731 <method name = "consume-ok" synchronous = "1" index = "21">
2732 confirm a new consumer
2734 This method provides the client with a consumer tag which it MUST
2735 use in methods that work with the consumer.
2737 <chassis name = "client" implement = "MUST" />
2739 <field name = "consumer tag" domain = "consumer tag">
2741 Holds the consumer tag specified by the client or provided by
2748 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2750 <method name = "cancel" synchronous = "1" index = "30">
2751 end a queue consumer
2753 This method cancels a consumer. This does not affect already
2754 delivered messages, but it does mean the server will not send any
2755 more messages for that consumer.
2757 <chassis name = "server" implement = "MUST" />
2758 <response name = "cancel-ok" />
2760 <field name = "consumer tag" domain = "consumer tag" />
2762 <field name = "nowait" type = "bit">
2763 do not send a reply method
2765 If set, the server will not respond to the method. The client should
2766 not wait for a reply method. If the server could not complete the
2767 method it will raise a channel or connection exception.
2772 <method name = "cancel-ok" synchronous = "1" index = "31">
2773 confirm a cancelled consumer
2775 This method confirms that the cancellation was completed.
2777 <chassis name = "client" implement = "MUST" />
2779 <field name = "consumer tag" domain = "consumer tag" />
2783 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2785 <method name = "open" synchronous = "1" index = "40">
2786 request to start staging
2788 This method requests permission to start staging a message. Staging
2789 means sending the message into a temporary area at the recipient end
2790 and then delivering the message by referring to this temporary area.
2791 Staging is how the protocol handles partial file transfers - if a
2792 message is partially staged and the connection breaks, the next time
2793 the sender starts to stage it, it can restart from where it left off.
2795 <response name = "open-ok" />
2796 <chassis name = "server" implement = "MUST" />
2797 <chassis name = "client" implement = "MUST" />
2799 <field name = "identifier" type = "shortstr">
2802 This is the staging identifier. This is an arbitrary string chosen
2803 by the sender. For staging to work correctly the sender must use
2804 the same staging identifier when staging the same message a second
2805 time after recovery from a failure. A good choice for the staging
2806 identifier would be the SHA1 hash of the message properties data
2807 (including the original filename, revised time, etc.).
2811 <field name = "content size" type = "longlong">
2812 message content size
2814 The size of the content in octets. The recipient may use this
2815 information to allocate or check available space in advance, to
2816 avoid "disk full" errors during staging of very large messages.
2819 The sender MUST accurately fill the content-size field.
2820 Zero-length content is permitted.
2825 <method name = "open-ok" synchronous = "1" index = "41">
2826 confirm staging ready
2828 This method confirms that the recipient is ready to accept staged
2829 data. If the message was already partially-staged at a previous
2830 time the recipient will report the number of octets already staged.
2832 <response name = "stage" />
2833 <chassis name = "server" implement = "MUST" />
2834 <chassis name = "client" implement = "MUST" />
2836 <field name = "staged size" type = "longlong">
2837 already staged amount
2839 The amount of previously-staged content in octets. For a new
2840 message this will be zero.
2843 The sender MUST start sending data from this octet offset in the
2844 message, counting from zero.
2847 The recipient MAY decide how long to hold partially-staged content
2848 and MAY implement staging by always discarding partially-staged
2849 content. However if it uses the file content type it MUST support
2850 the staging methods.
2855 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2857 <method name = "stage" content = "1" index = "50">
2858 stage message content
2860 This method stages the message, sending the message content to the
2861 recipient from the octet offset specified in the Open-Ok method.
2863 <chassis name = "server" implement = "MUST" />
2864 <chassis name = "client" implement = "MUST" />
2868 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2870 <method name = "publish" index = "60">
2873 This method publishes a staged file message to a specific exchange.
2874 The file message will be routed to queues as defined by the exchange
2875 configuration and distributed to any active consumers when the
2876 transaction, if any, is committed.
2878 <chassis name = "server" implement = "MUST" />
2880 <field name = "ticket" domain = "access ticket">
2882 The client MUST provide a valid access ticket giving "write"
2883 access rights to the access realm for the exchange.
2887 <field name = "exchange" domain = "exchange name">
2889 Specifies the name of the exchange to publish to. The exchange
2890 name can be empty, meaning the default exchange. If the exchange
2891 name is specified, and that exchange does not exist, the server
2892 will raise a channel exception.
2895 The server MUST accept a blank exchange name to mean the default
2899 If the exchange was declared as an internal exchange, the server
2900 MUST respond with a reply code 403 (access refused) and raise a
2904 The exchange MAY refuse file content in which case it MUST respond
2905 with a reply code 540 (not implemented) and raise a channel
2910 <field name = "routing key" type = "shortstr">
2913 Specifies the routing key for the message. The routing key is
2914 used for routing messages depending on the exchange configuration.
2918 <field name = "mandatory" type = "bit">
2919 indicate mandatory routing
2921 This flag tells the server how to react if the message cannot be
2922 routed to a queue. If this flag is set, the server will return an
2923 unroutable message with a Return method. If this flag is zero, the
2924 server silently drops the message.
2926 <doc name = "rule" test = "amq_file_00">
2927 The server SHOULD implement the mandatory flag.
2931 <field name = "immediate" type = "bit">
2932 request immediate delivery
2934 This flag tells the server how to react if the message cannot be
2935 routed to a queue consumer immediately. If this flag is set, the
2936 server will return an undeliverable message with a Return method.
2937 If this flag is zero, the server will queue the message, but with
2938 no guarantee that it will ever be consumed.
2940 <doc name = "rule" test = "amq_file_00">
2941 The server SHOULD implement the immediate flag.
2945 <field name = "identifier" type = "shortstr">
2948 This is the staging identifier of the message to publish. The
2949 message must have been staged. Note that a client can send the
2950 Publish method asynchronously without waiting for staging to
2956 <method name = "return" content = "1" index = "70">
2957 return a failed message
2959 This method returns an undeliverable message that was published
2960 with the "immediate" flag set, or an unroutable message published
2961 with the "mandatory" flag set. The reply code and text provide
2962 information about the reason that the message was undeliverable.
2964 <chassis name = "client" implement = "MUST" />
2966 <field name = "reply code" domain = "reply code" />
2967 <field name = "reply text" domain = "reply text" />
2969 <field name = "exchange" domain = "exchange name">
2971 Specifies the name of the exchange that the message was
2972 originally published to.
2976 <field name = "routing key" type = "shortstr">
2979 Specifies the routing key name specified when the message was
2986 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2988 <method name = "deliver" index = "80">
2989 notify the client of a consumer message
2991 This method delivers a staged file message to the client, via a
2992 consumer. In the asynchronous message delivery model, the client
2993 starts a consumer using the Consume method, then the server
2994 responds with Deliver methods as and when messages arrive for
2998 The server SHOULD track the number of times a message has been
2999 delivered to clients and when a message is redelivered a certain
3000 number of times - e.g. 5 times - without being acknowledged, the
3001 server SHOULD consider the message to be unprocessable (possibly
3002 causing client applications to abort), and move the message to a
3005 <chassis name = "client" implement = "MUST" />
3007 <field name = "consumer tag" domain = "consumer tag" />
3009 <field name = "delivery tag" domain = "delivery tag" />
3011 <field name = "redelivered" domain = "redelivered" />
3013 <field name = "exchange" domain = "exchange name">
3015 Specifies the name of the exchange that the message was originally
3020 <field name = "routing key" type = "shortstr">
3023 Specifies the routing key name specified when the message was
3028 <field name = "identifier" type = "shortstr">
3031 This is the staging identifier of the message to deliver. The
3032 message must have been staged. Note that a server can send the
3033 Deliver method asynchronously without waiting for staging to
3040 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3042 <method name = "ack" index = "90">
3043 acknowledge one or more messages
3045 This method acknowledges one or more messages delivered via the
3046 Deliver method. The client can ask to confirm a single message or
3047 a set of messages up to and including a specific message.
3049 <chassis name = "server" implement = "MUST" />
3050 <field name = "delivery tag" domain = "delivery tag" />
3052 <field name = "multiple" type = "bit">
3053 acknowledge multiple messages
3055 If set to 1, the delivery tag is treated as "up to and including",
3056 so that the client can acknowledge multiple messages with a single
3057 method. If set to zero, the delivery tag refers to a single
3058 message. If the multiple field is 1, and the delivery tag is zero,
3059 tells the server to acknowledge all outstanding mesages.
3062 The server MUST validate that a non-zero delivery-tag refers to an
3063 delivered message, and raise a channel exception if this is not the
3070 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3072 <method name = "reject" index = "100">
3073 reject an incoming message
3075 This method allows a client to reject a message. It can be used to
3076 return untreatable messages to their original queue. Note that file
3077 content is staged before delivery, so the client will not use this
3078 method to interrupt delivery of a large message.
3081 The server SHOULD interpret this method as meaning that the client
3082 is unable to process the message at this time.
3085 A client MUST NOT use this method as a means of selecting messages
3086 to process. A rejected message MAY be discarded or dead-lettered,
3087 not necessarily passed to another client.
3089 <chassis name = "server" implement = "MUST" />
3091 <field name = "delivery tag" domain = "delivery tag" />
3093 <field name = "requeue" type = "bit">
3096 If this field is zero, the message will be discarded. If this bit
3097 is 1, the server will attempt to requeue the message.
3100 The server MUST NOT deliver the message to the same client within
3101 the context of the current channel. The recommended strategy is
3102 to attempt to deliver the message to an alternative consumer, and
3103 if that is not possible, to move the message to a dead-letter
3104 queue. The server MAY use more sophisticated tracking to hold
3105 the message on the queue and redeliver it to the same client at
3113 <class name="stream" handler="channel" index="80">
3115 ======================================================
3117 ======================================================
3119 work with streaming content
3122 The stream class provides methods that support multimedia streaming.
3123 The stream class uses the following semantics: one message is one
3124 packet of data; delivery is unacknowleged and unreliable; the consumer
3125 can specify quality of service parameters that the server can try to
3126 adhere to; lower-priority messages may be discarded in favour of high
3130 <doc name = "grammar">
3131 stream = C:QOS S:QOS-OK
3132 / C:CONSUME S:CONSUME-OK
3133 / C:CANCEL S:CANCEL-OK
3139 <chassis name = "server" implement = "MAY" />
3140 <chassis name = "client" implement = "MAY" />
3143 The server SHOULD discard stream messages on a priority basis if
3144 the queue size exceeds some configured limit.
3147 The server MUST implement at least 2 priority levels for stream
3148 messages, where priorities 0-4 and 5-9 are treated as two distinct
3149 levels. The server MAY implement up to 10 priority levels.
3152 The server MUST implement automatic acknowledgements on stream
3153 content. That is, as soon as a message is delivered to a client
3154 via a Deliver method, the server must remove it from the queue.
3158 <!-- These are the properties for a Stream content -->
3160 <field name = "content type" type = "shortstr">
3163 <field name = "content encoding" type = "shortstr">
3164 MIME content encoding
3166 <field name = "headers" type = "table">
3167 Message header field table
3169 <field name = "priority" type = "octet">
3170 The message priority, 0 to 9
3172 <field name = "timestamp" type = "timestamp">
3173 The message timestamp
3177 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3179 <method name = "qos" synchronous = "1" index = "10">
3180 specify quality of service
3182 This method requests a specific quality of service. The QoS can
3183 be specified for the current channel or for all channels on the
3184 connection. The particular properties and semantics of a qos method
3185 always depend on the content class semantics. Though the qos method
3186 could in principle apply to both peers, it is currently meaningful
3187 only for the server.
3189 <chassis name = "server" implement = "MUST" />
3190 <response name = "qos-ok" />
3192 <field name = "prefetch size" type = "long">
3193 prefetch window in octets
3195 The client can request that messages be sent in advance so that
3196 when the client finishes processing a message, the following
3197 message is already held locally, rather than needing to be sent
3198 down the channel. Prefetching gives a performance improvement.
3199 This field specifies the prefetch window size in octets. May be
3200 set to zero, meaning "no specific limit". Note that other
3201 prefetch limits may still apply.
3205 <field name = "prefetch count" type = "short">
3206 prefetch window in messages
3208 Specifies a prefetch window in terms of whole messages. This
3209 field may be used in combination with the prefetch-size field;
3210 a message will only be sent in advance if both prefetch windows
3211 (and those at the channel and connection level) allow it.
3215 <field name = "consume rate" type = "long">
3216 transfer rate in octets/second
3218 Specifies a desired transfer rate in octets per second. This is
3219 usually determined by the application that uses the streaming
3220 data. A value of zero means "no limit", i.e. as rapidly as
3224 The server MAY ignore the prefetch values and consume rates,
3225 depending on the type of stream and the ability of the server
3226 to queue and/or reply it. The server MAY drop low-priority
3227 messages in favour of high-priority messages.
3231 <field name = "global" type = "bit">
3232 apply to entire connection
3234 By default the QoS settings apply to the current channel only. If
3235 this field is set, they are applied to the entire connection.
3240 <method name = "qos-ok" synchronous = "1" index = "11">
3241 confirm the requested qos
3243 This method tells the client that the requested QoS levels could
3244 be handled by the server. The requested QoS applies to all active
3245 consumers until a new QoS is defined.
3247 <chassis name = "client" implement = "MUST" />
3250 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3252 <method name = "consume" synchronous = "1" index = "20">
3253 start a queue consumer
3255 This method asks the server to start a "consumer", which is a
3256 transient request for messages from a specific queue. Consumers
3257 last as long as the channel they were created on, or until the
3258 client cancels them.
3261 The server SHOULD support at least 16 consumers per queue, unless
3262 the queue was declared as private, and ideally, impose no limit
3263 except as defined by available resources.
3266 Streaming applications SHOULD use different channels to select
3267 different streaming resolutions. AMQP makes no provision for
3268 filtering and/or transforming streams except on the basis of
3269 priority-based selective delivery of individual messages.
3271 <chassis name = "server" implement = "MUST" />
3272 <response name = "consume-ok" />
3274 <field name = "ticket" domain = "access ticket">
3276 The client MUST provide a valid access ticket giving "read" access
3277 rights to the realm for the queue.
3281 <field name = "queue" domain = "queue name">
3283 Specifies the name of the queue to consume from. If the queue name
3284 is null, refers to the current queue for the channel, which is the
3285 last declared queue.
3288 If the client did not previously declare a queue, and the queue name
3289 in this method is empty, the server MUST raise a connection exception
3290 with reply code 530 (not allowed).
3294 <field name = "consumer tag" domain = "consumer tag">
3296 Specifies the identifier for the consumer. The consumer tag is
3297 local to a connection, so two clients can use the same consumer
3298 tags. If this field is empty the server will generate a unique
3301 <doc name = "rule" test = "todo">
3302 The tag MUST NOT refer to an existing consumer. If the client
3303 attempts to create two consumers with the same non-empty tag
3304 the server MUST raise a connection exception with reply code
3309 <field name = "no local" domain = "no local" />
3311 <field name = "exclusive" type = "bit">
3312 request exclusive access
3314 Request exclusive consumer access, meaning only this consumer can
3317 <doc name = "rule" test = "amq_file_00">
3318 If the server cannot grant exclusive access to the queue when asked,
3319 - because there are other consumers active - it MUST raise a channel
3320 exception with return code 405 (resource locked).
3324 <field name = "nowait" type = "bit">
3325 do not send a reply method
3327 If set, the server will not respond to the method. The client should
3328 not wait for a reply method. If the server could not complete the
3329 method it will raise a channel or connection exception.
3335 <method name = "consume-ok" synchronous = "1" index = "21">
3336 confirm a new consumer
3338 This method provides the client with a consumer tag which it may
3339 use in methods that work with the consumer.
3341 <chassis name = "client" implement = "MUST" />
3343 <field name = "consumer tag" domain = "consumer tag">
3345 Holds the consumer tag specified by the client or provided by
3351 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3353 <method name = "cancel" synchronous = "1" index = "30">
3354 end a queue consumer
3356 This method cancels a consumer. Since message delivery is
3357 asynchronous the client may continue to receive messages for
3358 a short while after canceling a consumer. It may process or
3359 discard these as appropriate.
3361 <chassis name = "server" implement = "MUST" />
3362 <response name = "cancel-ok" />
3364 <field name = "consumer tag" domain = "consumer tag" />
3366 <field name = "nowait" type = "bit">
3367 do not send a reply method
3369 If set, the server will not respond to the method. The client should
3370 not wait for a reply method. If the server could not complete the
3371 method it will raise a channel or connection exception.
3376 <method name = "cancel-ok" synchronous = "1" index = "31">
3377 confirm a cancelled consumer
3379 This method confirms that the cancellation was completed.
3381 <chassis name = "client" implement = "MUST" />
3383 <field name = "consumer tag" domain = "consumer tag" />
3387 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3389 <method name = "publish" content = "1" index = "40">
3392 This method publishes a message to a specific exchange. The message
3393 will be routed to queues as defined by the exchange configuration
3394 and distributed to any active consumers as appropriate.
3396 <chassis name = "server" implement = "MUST" />
3398 <field name = "ticket" domain = "access ticket">
3400 The client MUST provide a valid access ticket giving "write"
3401 access rights to the access realm for the exchange.
3405 <field name = "exchange" domain = "exchange name">
3407 Specifies the name of the exchange to publish to. The exchange
3408 name can be empty, meaning the default exchange. If the exchange
3409 name is specified, and that exchange does not exist, the server
3410 will raise a channel exception.
3413 The server MUST accept a blank exchange name to mean the default
3417 If the exchange was declared as an internal exchange, the server
3418 MUST respond with a reply code 403 (access refused) and raise a
3422 The exchange MAY refuse stream content in which case it MUST
3423 respond with a reply code 540 (not implemented) and raise a
3428 <field name = "routing key" type = "shortstr">
3431 Specifies the routing key for the message. The routing key is
3432 used for routing messages depending on the exchange configuration.
3436 <field name = "mandatory" type = "bit">
3437 indicate mandatory routing
3439 This flag tells the server how to react if the message cannot be
3440 routed to a queue. If this flag is set, the server will return an
3441 unroutable message with a Return method. If this flag is zero, the
3442 server silently drops the message.
3444 <doc name = "rule" test = "amq_stream_00">
3445 The server SHOULD implement the mandatory flag.
3449 <field name = "immediate" type = "bit">
3450 request immediate delivery
3452 This flag tells the server how to react if the message cannot be
3453 routed to a queue consumer immediately. If this flag is set, the
3454 server will return an undeliverable message with a Return method.
3455 If this flag is zero, the server will queue the message, but with
3456 no guarantee that it will ever be consumed.
3458 <doc name = "rule" test = "amq_stream_00">
3459 The server SHOULD implement the immediate flag.
3464 <method name = "return" content = "1" index = "50">
3465 return a failed message
3467 This method returns an undeliverable message that was published
3468 with the "immediate" flag set, or an unroutable message published
3469 with the "mandatory" flag set. The reply code and text provide
3470 information about the reason that the message was undeliverable.
3472 <chassis name = "client" implement = "MUST" />
3474 <field name = "reply code" domain = "reply code" />
3475 <field name = "reply text" domain = "reply text" />
3477 <field name = "exchange" domain = "exchange name">
3479 Specifies the name of the exchange that the message was
3480 originally published to.
3484 <field name = "routing key" type = "shortstr">
3487 Specifies the routing key name specified when the message was
3494 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3496 <method name = "deliver" content = "1" index = "60">
3497 notify the client of a consumer message
3499 This method delivers a message to the client, via a consumer. In
3500 the asynchronous message delivery model, the client starts a
3501 consumer using the Consume method, then the server responds with
3502 Deliver methods as and when messages arrive for that consumer.
3504 <chassis name = "client" implement = "MUST" />
3506 <field name = "consumer tag" domain = "consumer tag" />
3508 <field name = "delivery tag" domain = "delivery tag" />
3510 <field name = "exchange" domain = "exchange name">
3512 Specifies the name of the exchange that the message was originally
3517 <field name = "queue" domain = "queue name">
3519 Specifies the name of the queue that the message came from. Note
3520 that a single channel can start many consumers on different
3523 <assert check = "notnull" />
3528 <class name="tx" handler="channel" index="90">
3530 ======================================================
3532 ======================================================
3534 work with standard transactions
3537 Standard transactions provide so-called "1.5 phase commit". We can
3538 ensure that work is never lost, but there is a chance of confirmations
3539 being lost, so that messages may be resent. Applications that use
3540 standard transactions must be able to detect and ignore duplicate
3543 <rule implement="SHOULD">
3544 An client using standard transactions SHOULD be able to track all
3545 messages received within a reasonable period, and thus detect and
3546 reject duplicates of the same message. It SHOULD NOT pass these to
3547 the application layer.
3549 <doc name="grammar">
3550 tx = C:SELECT S:SELECT-OK
3551 / C:COMMIT S:COMMIT-OK
3552 / C:ROLLBACK S:ROLLBACK-OK
3554 <chassis name="server" implement="SHOULD"/>
3555 <chassis name="client" implement="MAY"/>
3556 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3557 <method name="select" synchronous="1" index="10">
3558 select standard transaction mode
3560 This method sets the channel to use standard transactions. The
3561 client must use this method at least once on a channel before
3562 using the Commit or Rollback methods.
3564 <chassis name="server" implement="MUST"/>
3565 <response name="select-ok"/>
3567 <method name="select-ok" synchronous="1" index="11">
3568 confirm transaction mode
3570 This method confirms to the client that the channel was successfully
3571 set to use standard transactions.
3573 <chassis name="client" implement="MUST"/>
3575 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3576 <method name="commit" synchronous="1" index="20">
3577 commit the current transaction
3579 This method commits all messages published and acknowledged in
3580 the current transaction. A new transaction starts immediately
3583 <chassis name="server" implement="MUST"/>
3584 <response name="commit-ok"/>
3586 <method name="commit-ok" synchronous="1" index="21">
3587 confirm a successful commit
3589 This method confirms to the client that the commit succeeded.
3590 Note that if a commit fails, the server raises a channel exception.
3592 <chassis name="client" implement="MUST"/>
3594 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3595 <method name="rollback" synchronous="1" index="30">
3596 abandon the current transaction
3598 This method abandons all messages published and acknowledged in
3599 the current transaction. A new transaction starts immediately
3602 <chassis name="server" implement="MUST"/>
3603 <response name="rollback-ok"/>
3605 <method name="rollback-ok" synchronous="1" index="31">
3606 confirm a successful rollback
3608 This method confirms to the client that the rollback succeeded.
3609 Note that if an rollback fails, the server raises a channel exception.
3611 <chassis name="client" implement="MUST"/>
3614 <class name="dtx" handler="channel" index="100">
3616 ======================================================
3617 == DISTRIBUTED TRANSACTIONS
3618 ======================================================
3620 work with distributed transactions
3623 Distributed transactions provide so-called "2-phase commit". The
3624 AMQP distributed transaction model supports the X-Open XA
3625 architecture and other distributed transaction implementations.
3626 The Dtx class assumes that the server has a private communications
3627 channel (not AMQP) to a distributed transaction coordinator.
3629 <doc name="grammar">
3630 dtx = C:SELECT S:SELECT-OK
3633 <chassis name="server" implement="MAY"/>
3634 <chassis name="client" implement="MAY"/>
3635 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3636 <method name="select" synchronous="1" index="10">
3637 select standard transaction mode
3639 This method sets the channel to use distributed transactions. The
3640 client must use this method at least once on a channel before
3641 using the Start method.
3643 <chassis name="server" implement="MUST"/>
3644 <response name="select-ok"/>
3646 <method name="select-ok" synchronous="1" index="11">
3647 confirm transaction mode
3649 This method confirms to the client that the channel was successfully
3650 set to use distributed transactions.
3652 <chassis name="client" implement="MUST"/>
3654 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3655 <method name="start" synchronous="1" index="20">
3656 start a new distributed transaction
3658 This method starts a new distributed transaction. This must be
3659 the first method on a new channel that uses the distributed
3660 transaction mode, before any methods that publish or consume
3663 <chassis name="server" implement="MAY"/>
3664 <response name="start-ok"/>
3665 <field name="dtx identifier" type="shortstr">
3666 transaction identifier
3668 The distributed transaction key. This identifies the transaction
3669 so that the AMQP server can coordinate with the distributed
3670 transaction coordinator.
3672 <assert check="notnull"/>
3675 <method name="start-ok" synchronous="1" index="21">
3676 confirm the start of a new distributed transaction
3678 This method confirms to the client that the transaction started.
3679 Note that if a start fails, the server raises a channel exception.
3681 <chassis name="client" implement="MUST"/>
3684 <class name="tunnel" handler="tunnel" index="110">
3686 ======================================================
3688 ======================================================
3690 methods for protocol tunneling.
3693 The tunnel methods are used to send blocks of binary data - which
3694 can be serialised AMQP methods or other protocol frames - between
3697 <doc name="grammar">
3701 <chassis name="server" implement="MAY"/>
3702 <chassis name="client" implement="MAY"/>
3703 <field name="headers" type="table">
3704 Message header field table
3706 <field name="proxy name" type="shortstr">
3707 The identity of the tunnelling proxy
3709 <field name="data name" type="shortstr">
3710 The name or type of the message being tunnelled
3712 <field name="durable" type="octet">
3713 The message durability indicator
3715 <field name="broadcast" type="octet">
3716 The message broadcast mode
3718 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3719 <method name="request" content="1" index="10">
3720 sends a tunnelled method
3722 This method tunnels a block of binary data, which can be an
3723 encoded AMQP method or other data. The binary data is sent
3724 as the content for the Tunnel.Request method.
3726 <chassis name="server" implement="MUST"/>
3727 <field name="meta data" type="table">
3728 meta data for the tunnelled block
3730 This field table holds arbitrary meta-data that the sender needs
3731 to pass to the recipient.
3736 <class name="test" handler="channel" index="120">
3738 ======================================================
3739 == TEST - CHECK FUNCTIONAL CAPABILITIES OF AN IMPLEMENTATION
3740 ======================================================
3742 test functional primitives of the implementation
3745 The test class provides methods for a peer to test the basic
3746 operational correctness of another peer. The test methods are
3747 intended to ensure that all peers respect at least the basic
3748 elements of the protocol, such as frame and content organisation
3749 and field types. We assume that a specially-designed peer, a
3750 "monitor client" would perform such tests.
3752 <doc name="grammar">
3753 test = C:INTEGER S:INTEGER-OK
3754 / S:INTEGER C:INTEGER-OK
3755 / C:STRING S:STRING-OK
3756 / S:STRING C:STRING-OK
3757 / C:TABLE S:TABLE-OK
3758 / S:TABLE C:TABLE-OK
3759 / C:CONTENT S:CONTENT-OK
3760 / S:CONTENT C:CONTENT-OK
3762 <chassis name="server" implement="MUST"/>
3763 <chassis name="client" implement="SHOULD"/>
3764 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3765 <method name="integer" synchronous="1" index="10">
3766 test integer handling
3768 This method tests the peer's capability to correctly marshal integer
3771 <chassis name="client" implement="MUST"/>
3772 <chassis name="server" implement="MUST"/>
3773 <response name="integer-ok"/>
3774 <field name="integer 1" type="octet">
3777 An octet integer test value.
3780 <field name="integer 2" type="short">
3783 A short integer test value.
3786 <field name="integer 3" type="long">
3789 A long integer test value.
3792 <field name="integer 4" type="longlong">
3793 long-long test value
3795 A long long integer test value.
3798 <field name="operation" type="octet">
3801 The client must execute this operation on the provided integer
3802 test fields and return the result.
3804 <assert check="enum">
3805 <value name="add">return sum of test values</value>
3806 <value name="min">return lowest of test values</value>
3807 <value name="max">return highest of test values</value>
3811 <method name="integer-ok" synchronous="1" index="11">
3812 report integer test result
3814 This method reports the result of an Integer method.
3816 <chassis name="client" implement="MUST"/>
3817 <chassis name="server" implement="MUST"/>
3818 <field name="result" type="longlong">
3821 The result of the tested operation.
3825 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3826 <method name="string" synchronous="1" index="20">
3827 test string handling
3829 This method tests the peer's capability to correctly marshal string
3832 <chassis name="client" implement="MUST"/>
3833 <chassis name="server" implement="MUST"/>
3834 <response name="string-ok"/>
3835 <field name="string 1" type="shortstr">
3836 short string test value
3838 An short string test value.
3841 <field name="string 2" type="longstr">
3842 long string test value
3844 A long string test value.
3847 <field name="operation" type="octet">
3850 The client must execute this operation on the provided string
3851 test fields and return the result.
3853 <assert check="enum">
3854 <value name="add">return concatentation of test strings</value>
3855 <value name="min">return shortest of test strings</value>
3856 <value name="max">return longest of test strings</value>
3860 <method name="string-ok" synchronous="1" index="21">
3861 report string test result
3863 This method reports the result of a String method.
3865 <chassis name="client" implement="MUST"/>
3866 <chassis name="server" implement="MUST"/>
3867 <field name="result" type="longstr">
3870 The result of the tested operation.
3874 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3875 <method name="table" synchronous="1" index="30">
3876 test field table handling
3878 This method tests the peer's capability to correctly marshal field
3881 <chassis name="client" implement="MUST"/>
3882 <chassis name="server" implement="MUST"/>
3883 <response name="table-ok"/>
3884 <field name="table" type="table">
3885 field table of test values
3887 A field table of test values.
3890 <field name="integer op" type="octet">
3891 operation to test on integers
3893 The client must execute this operation on the provided field
3894 table integer values and return the result.
3896 <assert check="enum">
3897 <value name="add">return sum of numeric field values</value>
3898 <value name="min">return min of numeric field values</value>
3899 <value name="max">return max of numeric field values</value>
3902 <field name="string op" type="octet">
3903 operation to test on strings
3905 The client must execute this operation on the provided field
3906 table string values and return the result.
3908 <assert check="enum">
3909 <value name="add">return concatenation of string field values</value>
3910 <value name="min">return shortest of string field values</value>
3911 <value name="max">return longest of string field values</value>
3915 <method name="table-ok" synchronous="1" index="31">
3916 report table test result
3918 This method reports the result of a Table method.
3920 <chassis name="client" implement="MUST"/>
3921 <chassis name="server" implement="MUST"/>
3922 <field name="integer result" type="longlong">
3923 integer result value
3925 The result of the tested integer operation.
3928 <field name="string result" type="longstr">
3931 The result of the tested string operation.
3935 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3936 <method name="content" synchronous="1" content="1" index="40">
3937 test content handling
3939 This method tests the peer's capability to correctly marshal content.
3941 <chassis name="client" implement="MUST"/>
3942 <chassis name="server" implement="MUST"/>
3943 <response name="content-ok"/>
3945 <method name="content-ok" synchronous="1" content="1" index="41">
3946 report content test result
3948 This method reports the result of a Content method. It contains the
3949 content checksum and echoes the original content as provided.
3951 <chassis name="client" implement="MUST"/>
3952 <chassis name="server" implement="MUST"/>
3953 <field name="content checksum" type="long">
3956 The 32-bit checksum of the content, calculated by adding the
3957 content into a 32-bit accumulator.
projects / mono.git / blob