Message selectors
A message contains a built-in facility to support application-defined property
values. In effect, this provides a mechanism to add application-specific header
fields to a message. Properties allow an application, using message selectors,
to have a JMS provider select or filter messages on its behalf, using application-specific
criteria. Application-defined properties must obey the following rules:
- Property names must obey the rules for a message selector identifier.
- Property values can be boolean, byte, short, int, long, float, double,
and String.
- The JMSX and JMS_ name prefixes are reserved.
Property values are set before sending a message. When a client receives
a message, the message properties are read-only. If a client attempts to set
properties at this point, a MessageNotWriteableException is thrown. If clearProperties
is called, the properties can now be both read from, and written to.
A property value might duplicate a value in a message's body. JMS does
not define a policy for what should or should not be made into a property.
However, application developers must be aware that JMS providers probably
handle data in a message's body more efficiently than data in a message's
properties. For best performance, applications must use message properties
only when they need to customize a message's header. The primary reason for
doing this is to support customized message selection.
A JMS message selector allows a client to specify the messages that it
is interested in by using the message header. Only messages whose headers
match the selector are delivered.
Message selectors cannot refer to message body values.
A message selector matches a message when the selector evaluates to true
when the message's header field and property values are substituted for their
corresponding identifiers in the selector.
A message selector is a String, whose syntax is based on a subset of the
SQL92 conditional expression syntax. The order in which a message selector
is evaluated is from left to right within a precedence level. You can use
parentheses to change this order. Predefined selector literals and operator
names are written here in upper case; however, they are not case-sensitive.
A selector can contain:
- Literals
- A string literal is enclosed in single quotes. A doubled single quote
represents a single quote. Examples are 'literal' and 'literal''s'. Like Java(TM) string literals, these use the Unicode character encoding.
- An exact numeric literal is a numeric value without a decimal point, such
as 57, -957, and +62. Numbers in the range of Java long are supported.
- An approximate numeric literal is a numeric value in scientific notation,
such as 7E3 or -57.9E2, or a numeric value with a decimal, such as 7., -95.7,
or +6.2. Numbers in the range of Java double are supported.
- The boolean literals TRUE and FALSE.
- Identifiers:
- An identifier is an unlimited length sequence of Java letters
and Java digits, the first of which must be a Java letter. A letter is any character
for which the method Character.isJavaLetter returns true. This includes _
and $. A letter or digit is any character for which the method Character.isJavaLetterOrDigit
returns true.
- Identifiers cannot be the names NULL, TRUE, or FALSE.
- Identifiers cannot be NOT, AND, OR, BETWEEN, LIKE, IN, or IS.
- Identifiers are either header field references or property references.
- Identifiers are case-sensitive.
- Message header field references are restricted to:
- JMSDeliveryMode
- JMSPriority
- JMSMessageID
- JMSTimestamp
- JMSCorrelationID
- JMSType
JMSMessageID, JMSTimestamp, JMSCorrelationID, and JMSType values can
be null, and if so, are treated as a NULL value.
- Any name beginning with JMSX is a JMS-defined property name.
- Any name beginning with JMS_ is a provider-specific property name.
- Any name that does not begin with JMS is an application-specific property
name. If there is a reference to a property that does not exist in a message,
its value is NULL. If it does exist, its value is the corresponding property
value.
- White space is the same as it is defined for Java: space, horizontal tab, form feed,
and line terminator.
- Expressions:
- A selector is a conditional expression. A selector that evaluates to true
matches; a selector that evaluates to false or unknown does not match.
- Arithmetic expressions are composed of themselves, arithmetic operations,
identifiers (whose value is treated as a numeric literal), and numeric literals.
- Conditional expressions are composed of themselves, comparison operations,
and logical operations.
- Standard bracketing (), to set the order in which expressions are evaluated,
is supported.
- Logical operators in precedence order: NOT, AND, OR.
- Comparison operators: =, >, >=, <, <=, <> (not equal).
- Only values of the same type can be compared. One exception is that it
is valid to compare exact numeric values and approximate numeric values. (The
type conversion required is defined by the rules of Java numeric promotion.) If there is an
attempt to compare different types, the selector is always false.
- String and boolean comparison is restricted to = and <>. Two strings
are equal only if they contain the same sequence of characters.
- Arithmetic operators in precedence order:
- +, - unary.
- *, /, multiplication, and division.
- +, -, addition, and subtraction.
- Arithmetic operations on a NULL value are not supported. If they are attempted,
the complete selector is always false.
- Arithmetic operations must use Java numeric promotion.
- arithmetic-expr1 [NOT] BETWEEN arithmetic-expr2 and arithmetic-expr3
comparison operator:
- Age BETWEEN 15 and 19 is equivalent to age >= 15 AND age <= 19.
- Age NOT BETWEEN 15 and 19 is equivalent to age < 15 OR age > 19.
- If any of the expressions of a BETWEEN operation are NULL, the value of
the operation is false. If any of the expressions of a NOT BETWEEN operation
are NULL, the value of the operation is true.
- identifier [NOT] IN (string-literal1, string-literal2,...) comparison
operator where identifier has a String or NULL value.
- Country IN ('UK', 'US', 'France') is true for 'UK' and false for 'Peru'.
It is equivalent to the expression (Country = 'UK') OR (Country = 'US') OR
(Country = 'France').
- Country NOT IN ('UK', 'US', 'France') is false for 'UK' and true for 'Peru'.
It is equivalent to the expression NOT ((Country = 'UK') OR (Country = 'US')
OR (Country = 'France')).
- If the identifier of an IN or NOT IN operation is NULL, the value of the
operation is unknown.
- identifier [NOT] LIKE pattern-value [ESCAPE escape-character]
comparison operator, where identifier has a string value. pattern-value is
a string literal, where _ stands for any single character and % stands
for any sequence of characters (including the empty sequence). All other characters
stand for themselves. The optional escape-character is a single character
string literal, whose character is used to escape the special meaning of the
_ and % in pattern-value.
- phone LIKE '12%3' is true for 123 and 12993 and false for 1234.
- word LIKE 'l_se' is true for lose and false for loose.
- underscored LIKE '\_%' ESCAPE '\' is true for _foo and false for
bar.
- phone NOT LIKE '12%3' is false for 123 and 12993 and true for
1234.
- If the identifier of a LIKE or NOT LIKE operation is NULL, the value of
the operation is unknown.
- identifier IS NULL comparison operator tests for a null header field value,
or a missing property value.
- identifier IS NOT NULL comparison operator tests for the existence of
a non-null header field value or a property value.
The following message selector selects messages with a message type of
car, color of blue, and weight greater than 2500 lbs:
"JMSType = 'car' AND color = 'blue' AND weight > 2500"
As noted above, property values can be NULL. The evaluation of selector
expressions that contain NULL values is defined by SQL 92 NULL semantics.
The following is a brief description of these semantics:
- SQL treats a NULL value as unknown.
- Comparison or arithmetic with an unknown value always yields an unknown
value.
- The IS NULL and IS NOT NULL operators convert an unknown value into the
respective TRUE and FALSE values.
Although SQL supports fixed decimal comparison and arithmetic, JMS message
selectors do not. This is why exact numeric literals are restricted to those
without a decimal. It is also why there are numerics with a decimal as an
alternate representation for an approximate numeric value.
SQL comments are not supported.