Selectors
An AMQP receiver can send a JMS message selector on its source, as an
apache.org:selector-filter:string or amqp:sql-filter filter. The
gateway then delivers only the messages that match. A JMS client sends one
when it creates a consumer with a selector. Both filters use the Jakarta
Messaging selector syntax that this page lists.
Examples
| Selector | Matches | Does not match |
|---|---|---|
region = 'EU' | region is EU | region is eu, or missing |
region IN ('EU', 'APAC') | region is EU or APAC | region is US, or missing |
region <> 'EU' | region is US | region is EU, or missing |
region <> 'EU' OR region IS NULL | region is US, or missing | region is EU |
amount > 1000 | amount is 1200 or '1200' | amount is 80 or 'abc', or missing |
amount BETWEEN 50 AND 100 | amount is 50 or 100 | amount is 49.9 |
sku LIKE 'A-%' | sku is A-100 or A- | sku is a-100 or B-100 |
sku LIKE 'A\_%' ESCAPE '\' | sku is A_1 | sku is AB1 |
tier IS NULL | tier is missing | tier is set, even to '' |
urgent | urgent is true or TRUE | urgent is false or yes, or missing |
region = 'EU' AND (amount > 1000 OR tier = 'gold') | EU with amount 1200, or with tier gold | EU with amount 5 and no tier |
JMSPriority >= 5 | Priority 5 to 9 | No priority, which reads as 4 |
JMSDeliveryMode = 'PERSISTENT' | durable is true | durable is false or unset |
Identifiers
An identifier starts with a letter, _ or $, and continues with
letters, digits, _ or $. Identifiers are case sensitive: Amount does
not read amount. A keyword, such as AND or TRUE, in any case, is not
an identifier. Selectors have no quoted identifiers.
An identifier names an application property, unless it is one of the JMS
names below. MQTT v5 User Properties and the Mqg-Prop-<key> headers of
NATS clients are application properties too (see
Mapping to NATS). On a routed address, the
gateway reads a property that the route's template names from the
subject, not from the header.
| Name | Value | When unset |
|---|---|---|
JMSMessageID | message-id, as a JMS client reads it. See Rules | NULL |
JMSCorrelationID | correlation-id, as a JMS client reads it. See Rules | NULL |
JMSType | subject | NULL |
JMSPriority | priority, 0 to 9. A higher priority reads as 9 | 4 |
JMSTimestamp | creation-time, in milliseconds since the Unix epoch | 0 |
JMSDeliveryMode | 'PERSISTENT' when durable is true, else 'NON_PERSISTENT' | 'NON_PERSISTENT' |
JMSExpiration | When the message expires, in milliseconds since the Unix epoch | 0 |
JMSXUserID | user-id, else the application property JMSXUserID | NULL |
JMSXGroupID | group-id | NULL |
JMSXGroupSeq | group-sequence, as a signed 32-bit integer | NULL |
Any other name, JMS-prefixed or not, is an application property. The
gateway refuses a selector on JMSXDeliveryCount.
Literals
| Literal | Examples | Notes |
|---|---|---|
| String | 'EU', 'it''s' | Single quotes. Two quotes write one |
| Number | 57, -9.5, 1e3, 100L | Decimal only. A Java type suffix L, F or D, in any case, is optional |
| Boolean | TRUE, FALSE | |
| Null | NULL | Unknown. a = NULL never matches. Use IS NULL |
Keywords such as AND, LIKE and TRUE are not case sensitive.
Operators
| Operator | Example | Notes |
|---|---|---|
+ - (sign) | -amount < -1000 | |
* / | amount * 2 >= 2400 | |
+ - | price + tax > 100 | |
= <> | region = 'EU' | Any type |
< <= > >= | amount > 1000 | Not on a string or boolean literal |
[NOT] BETWEEN ... AND ... | amount BETWEEN 50 AND 100 | Not on a string or boolean literal. The bounds are inclusive |
[NOT] IN (...) | region IN ('EU', 'APAC') | An identifier, and a list of strings |
[NOT] LIKE ... [ESCAPE ...] | sku LIKE 'A\_%' ESCAPE '\' | A string pattern: % is any run of characters, _ is one. The escape is one character |
IS [NOT] NULL | tier IS NULL | True when the message has no such value |
NOT AND OR | NOT region = 'EU' OR amount > 1000 |
Precedence follows the table. The sign binds first, then * and /,
then + and -. The comparisons, from = to IS NULL, share one level
and do not chain. Then come NOT, AND and OR, in that order.
Parentheses group terms.
The gateway refuses a string or boolean literal next to <, <=, >,
>= or BETWEEN. Two properties can still be ordered (see Rules).
Rules
- A property takes the type of what it is compared with. Against a
number, it is a number when its text reads as one, so the string
property
'1200'matchesamount > 1000. AgainstTRUEorFALSE, it is a boolean in any case. Against a string, it is text, compared exactly. - Unlike types do not match. A property that does not read as a
number, compared with one, makes the comparison false. Its negation, such
as
NOT word < 100, is then true.word NOT BETWEEN 1 AND 2isword < 1 OR word > 2, so it is false too. - A missing property is unknown. Neither
tier = 'gold'nortier <> 'gold'matches a message withouttier. UseIS NULLto match it.ORwith a true side andANDwith a false side still decide. - Two properties compare as numbers when both read as numbers. Otherwise they compare as text, by their bytes.
- IDs read as a JMS client reads them. A
message-idorcorrelation-idthat is not a string reads with a type prefix, such asID:AMQP_ULONG:42. A stringmessage-idwithoutID:reads asID:AMQP_NO_PREFIX:<id>. - Numbers are 64-bit floating point. Integers above 2^53 compare inexactly.
- A property alone is a condition.
flagmatches when the property's text istrue, in any case. - Spelling does not change a selector. Selectors that differ only in
spaces, keyword case, redundant parentheses or number format are the
same. Receivers in queue mode on a stored address then share a queue.
a AND (b AND c)anda AND b AND care different selectors. See AMQP support. - The gateway checks the selector at attach. It refuses the receiver's link when the selector does not parse.