arvicco-amqp 0.6.8 → 0.6.9

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