/[de-setf-amqp]/specification/amqp0-9.xml
ViewVC logotype

Contents of /specification/amqp0-9.xml

Parent Directory Parent Directory | Revision Log Revision Log


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