1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE amqp SYSTEM "amqp.dtd">
<?xml-stylesheet type="text/xsl" href="amqp.xsl"?>
<amqp name="apache-filters" label="Apache Proposed AMQP 1-0 Filters">
<section name="legacy-amqp" title="Legacy AMQP Exchange Binding Support">
<doc>
<p>
Versions of AMQP prior to 1.0 prescribed a model of Exchanges and Queues, where Queues were
bound to Exchanges with a binding key whose meaning depended upon the type of the Exchange.
In order to allow a consistent mechanism for addressing legacy AMQP Exchanges over AMQP 1.0
the following filter types are defined. Use of an Exchange as an address for a Source thus
can be seen as equivalent to constructing exclusive queues bound to an Exchange in legacy
AMQP versions.
</p>
<p>
Containers which support the filters that are defined in this section should advertise the
capability <term>APACHE.ORG:LEGACY_AMQP_EXCHANGE_FILTERS</term> in their connection
capabilities when sending the open performative, and MUST provide this capability on
sources supporting these filter types.
</p>
</doc>
<type class="restricted" name="legacy-amqp-direct-binding" source="string" provides="filter">
<descriptor name="apache.org:legacy-amqp-direct-binding:string"
code="0x0000468C:0x00000000"/>
<doc>
<p>
The legacy-amqp-direct-binding filter consists of a described string value. The filter
matches a message if and only if the described string value exactly matches the subject
field of the Properties section of the message being evaluated. If the message has no
Properties section, or if the subject field of the Properties section is not set, then
the legacy-amqp-direct-binding filter does not match.
</p>
</doc>
</type>
<type class="restricted" name="legacy-amqp-topic-binding" source="string" provides="filter">
<descriptor name="apache.org:legacy-amqp-topic-binding:string"
code="0x0000468C:0x00000001"/>
<doc>
<p>
The legacy-amqp-topic-binding filter consists of a described string value. The value
value described by the type is interpreted as a pattern to match against the subject
field of the Properties section of the message being evaluated.
</p>
<ul>
<li>The pattern is formed using zero or more tokens, with each token delimited by the
"." character. The tokens "#" and "*" have special meanings.</li>
<li>The token consisting of the single character "*" matches a single word in the
subject field.</li>
<li>The token consisting of the single character "#" matches zero or more words in the
subject field.</li>
</ul>
<p>
Thus the filter value "*.stock.#" would match the subjects "usd.stock" and
"eur.stock.db" but not "stock.nasdaq".
</p>
<p>
If the message has no Properties section, or if the subject field of the Properties
section is not set, then the legacy-amqp-topic-binding filter matches only if the value
of the filter is a single "#".
</p>
</doc>
</type>
<type class="restricted" name="legacy-amqp-headers-binding" source="map" provides="filter">
<descriptor name="apache.org:legacy-amqp-headers-binding:map" code="0x0000468C:0x00000002"/>
<doc>
<p>
The legacy-amqp-headers-binding filter consists of a described map value. The map
value described by the type is interpreted as a pattern to match against the
application-properties section of the message being evaluated. The map has the same
restriction as the application-properties section, namely that the keys of this are
restricted to be of type string (which excludes the possibility of a null key) and the
values are restricted to be of simple types only, that is, excluding map, list, and
array types.
</p>
<p>
The key "x-match" in the described map has special meaning. This key MUST map to the
symbolic value "any" or the symbolic value "all" within the described map. All other
keys which begin "x-" MUST be ignored by the source when evaluating. If the value for
"x-match" is "all" then all other valid key-value pairs in the map MUST match with an
entry with the same key in the application-properties section. If the value for
"x-match" is "any" then the filter will accept the message if at least one key-value
pair matches the equivalent key value pair in the application-properties section.
</p>
<p>
A key-value pair in the filter's map matches a key-value pair in the
application-properties section if the keys are identical (including the same type), or
if the value in the filter map for the key is null.
</p>
</doc>
</type>
</section>
<section name="jms" title="Java Message Service Support">
<doc>
<p>
The Java Message Service defines two types of filtering of messages: firstly the ability to
exclude from a subscription messages sent by the same connection, secondly a more general
filtering syntax known as "selectors" based on an SQL like syntax.
</p>
<p>
AMQP filter extensions through which these two types of
filtering may be achieved are defined below. Their use, though
motivated by support for JMS, is not restricted to JMS.
</p>
</doc>
<type class="composite" name="no-local-filter" source="list" provides="filter">
<descriptor name="apache.org:no-local-filter:list" code="0x0000468C:0x00000003"/>
<doc>
<p>
A message will be accepted by the simple-no-local-filter if and only if the message
was originally sent to the container of the source on a separate connection from that
which is currently receiving from the source.
</p>
<p>
Containers which support this filter should advertise the
capability <term>APACHE.ORG:NO_LOCAL</term> in their
connection capabilities when sending the open
performative, and MUST provide this capability on sources
supporting these filter types.
</p>
</doc>
</type>
<type class="restricted" name="selector-filter" provides="filter" source="string">
<descriptor name="apache.org:selector-filter:string" code="0x0000468C:0x00000004"/>
<doc>
<p>
The Java Message Service "selector" defines an SQL like
syntax for filtering messages. The selector filters based
on the values of "headers" and "properties". The
selector-filter uses the selector as defined by JMS but
with the names of JMS headers translated into their AMQP
equivalents. The defined JMS headers can be mapped to
equivalent fields within the AMQP message sections:
</p>
<picture title="Mapping JMS Headers to AMQP fields">
JMS Header Name | AMQP 1.0 Field
==================|====================================================
JMSCorrelationID | correlation-id field of properties section
JMSDeliveryMode | durable field of header section
JMSDestination | to field of the properties section
JMSExpiration | absolute-expiry-time of properties section
JMSMessageID | message-id of properties section
JMSPriority | priority field of header section
JMSRedelivered | delivery-count > 0 in header section
JMSReplyTo | reply-to in properties section
JMSTimestamp | creation-time of properties section
JMSType | annotation jms-type in message-annotations section
</picture>
<p>
When encoding the selector string on the wire, these JMS
header names should be translated to amqp.<i>field_name</i>
where <i>field_name</i> is the appropriate AMQP 1.0 field
named in the table above, with the hyphen replaced by an
underscore. For example, the selector: "JMSCorrelationID =
'abc' AND color = 'blue' AND weight > 2500" would be
transferred over the wire as: "amqp.correlation_id = 'abc'
AND color = 'blue' AND weight > 2500"
</p>
<p>
The "properties" of the JMS message are equivalent to the AMQP application-properties
section. Thus a reference to a property Foo in a message selector would be evaluated
as the value associated with the key "Foo" (if present) in the application-properties
section.
</p>
<p>
The operands of the JMS selector are defined in terms of the types available within JMS,
When evaluated against the application properties section, the values within that section
MUST be evaluated according to the following type mapping.
</p>
<picture title="Mapping AMQP types to JMS types">
AMQP Type | JMS Selector Type
==================|===================
null | null
boolean | boolean
ubyte | short
ushort | int
uint | long
ulong | long
byte | byte
short | short
int | int
long | long
float | float
double | double
decimal32 | double
decimal64 | double
decimal128 | double
char | char
timestamp | long
uuid | byte[16]
binary | byte[]
string | String
symbol | String
</picture>
<p>
Containers which support this filter should advertise the
capability <term>APACHE.ORG:SELECTOR</term> in their
connection capabilities when sending the open
performative, and MUST provide this capability on sources
supporting these filter types.
</p>
</doc>
</type>
</section>
</amqp>
|
