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, via 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 following name prefixes are reserved: JMSX, JMS_.

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 may duplicate a value in a message's body, or it may not. JMS does not define a policy for what should or should not be made into a property. However, application developers should note that JMS providers will probably handle data in a message's body more efficiently than data in a message's properties. For best performance, applications should only use message properties 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 reference 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 string literals, these use the Unicode character encoding.
  • An exact numeric literal is a numeric value without a decimal point, such as 57, -957, +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, and 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 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 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 does match, and 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 if, and 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 exprs of a BETWEEN operation are NULL, the value of the operation is false. If any of the exprs 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' '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' '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.
  • prop_name IS NULL.
• identifier IS NOT NULL comparison operator tests for the existence of a non-null header field value or a property value.
  • prop_name IS NOT NULL.

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 may 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.