JMS Connect User's Guide

APPENDIX B

Message Selector Syntax

A message selector is a String containing an expression that, if it evaluates to TRUE, will result in messages being selected, or if FALSE results in messages being neglected. The syntax of the JMS selector expression is based on a subset of SQL92. The order of evaluation of a message selector is from left to right within precedence level; but parentheses can be used to alter the evaluation order. For consistency, predefined selector literals and operator names are shown in upper case below (but are nevertheless case-insensitive).

A selector can contain tokens, operators, and expressions conforming to the rules outlined hereunder.

Literals

A string literal is enclosed in single quotes. If a string literal is to contain an included single quote, it can be represented by a doubled single quote: for example, 'its' and 'it''s'. As with Java String literals, the Unicode character encoding is presumed.

An exact numeric literal is a numeric value without a decimal point, such as 59, -257, +82, etc. Numbers in the range of Java long are supported. Exact numeric literals use the Java integer literal syntax.

An approximate numeric literal is a numeric value in scientific notation, such as 7E4, -27.9E2 or a numeric value with a decimal such as 7., -95.7, +16.2; numbers in the range of Java double are supported. Approximate literals use the Java floating point literal syntax.

A boolean literal can have a value of TRUE or FALSE.

Identifiers

Identifiers can be either header field references or property references. An identifier is a character sequence that begins with a Java-identifier start character and is followed by characters that are Java-identifier part characters. An identifier start character is any character for which the method Character.isJavaIdentifierStart() returns true. This includes underscore and $. An identifier part character is any character for which the method Character.isJavaIdentifierPart() returns true.

Identifiers cannot be NULL, TRUE,nor FALSE.

Identifiers cannot be NOT, AND, OR, BETWEEN, LIKE, IN, nor IS.

Identifiers are case-sensitive.

Message header field references are restricted to JMSDeliveryMode, JMSPriority, JMSMessageID, JMSTimestamp, JMSCorrelationID, and JMSType.

JMSMessageID, JMSCorrelationID, and JMSType values may 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 a non-existent property is referenced, its value is NULL. If it does exist, its value is the corresponding property value.

Whitespace is the same as that defined for Java: space, horizontal tab, form feed and/or line terminator.

Expressions

A selector is a conditional expression. Any selector that evaluates to true matches; a selector that evaluates to false or unknown does not match.

Arithmetic expressions are composed of arithmetic operators, identifiers with numeric values, numeric literals and/or other arithmetic expressions.

Conditional expressions are composed of comparison operators, logical operators, identifiers with boolean values, boolean literals, and/or other conditional expressions.

Standard bracketing () for ordering expression evaluation is supported.

Logical operators in precedence order: NOT, AND, OR

Comparison operators: =, >, >=, <, <=, <> (not equal)

Only like type values can be compared. One exception is that it is valid to compare exact numeric values and approximate numeric values. (The necessary type conversion is conducted according to the rules of Java numeric promotion.) If the comparison of non-like type values is attempted, the selector is always false.

String and Boolean comparisons are restricted to = (equal) and <> (not equal). Two strings are equal if and only if they contain the same sequence of characters.

Arithmetic operators in precedence order:

+, - unary

*, / multiplication and division

+, - addition and subtraction

NOTE: Arithmetic operations must use Java numeric promotion.

Comparisons

· arithmetic-expr1 [NOT] BETWEEN arithmetic-expr2 and arithmetic-expr3

Example:

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

· identifier [NOT] IN (string-literal1, string-literal2,...), where identifieris a String or NULL value.

Example: 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')

Example: 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 identifier in an IN or NOT IN operation is NULL, the value of the operation is unknown.

· identifier [NOT] LIKE pattern-value [ESCAPE escape-character], where identifier has a String value; pattern-value is a string literal where '_' (underscore) stands for any single character; '%' stands for any sequence of characters (including the empty sequence); and 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' or '12993' and false for '1234'

phone NOT LIKE '12%3' is false for '123' and '12993' and true 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'

If identifier in a LIKE or NOT LIKE operation is NULL, the value of the operation is unknown.

· identifier IS NULL tests for a null header field value, or a missing property value.

· identifier IS NOT NULL tests for the existence of a non null header field value or property value.

The following message selector selects messages with a message type of car and color of red and weight greater than 3500 lbs:

"JMSType = 'car' AND color = 'red' AND weight > 3500"

Null Values

As noted above, header fields and property values may be NULL. The evaluation of selector expressions containing NULL values is defined by SQL 92 NULL semantics. I.e., 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 header or property value intoTRUE or FALSE values.

Special Considerations

When used in a message selector, JMSDeliveryMode will have the value 'PERSISTENT' or 'NON_PERSISTENT'.

Date and time values should use the standard Java long millis value. When including a date or time literal in a message selector, it should be an integer literal for a millis value. The standard way to produce millis values is to use java.util.Calendar. Although SQL supports fixed decimal comparison and arithmetic, JMS message selectors do not. (This is the reason for restricting exact numeric literals to non-decimals.)

SQL comments are not supported.