org.exolab.jms.selector
Class Selector

java.lang.Object
  |
  +--org.exolab.jms.selector.Selector

public class Selector

extends java.lang.Object

This class enables messages to be filtered using a message selector. This is a String whose syntax is based on a subset of the SQL92 conditional expression syntax. A selector can contain:

• Literals:
• A string literal is enclosed in single quotes with an included single quote represented by doubled single quote such as '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. Exact numeric literals use the Java integer literal syntax.
• An approximate numeric literal is a numeric value in scientific notation such as 7E3, -57.9E2 or a numeric value with a decimal such as 7., -95.7, +6.2; numbers in the range of Java double are supported. Approximate literals use the Java floating point literal syntax.
• The boolean literals TRUE and FALSE.
• Identifiers:
• Identifiers use the Java identifier syntax. They are case sensitive.
• 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.

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 property is referenced that does not exist in a message its value is NULL. If it does exist, its value is the corresponding property value.
• 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 with numeric values and numeric literals.
• Conditional expressions are composed of themselves, comparison operations, logical operations, identifiers with boolean values and boolean literals.
• 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 type conversion required is defined by the rules of Java numeric promotion). If the comparison of non-like type values is attempted, 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 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
• 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 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; '%' 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', '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 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 property value.
• prop_name IS NOT NULL

Version:

$Revision: 1.1 $ $Date: 2004/11/26 01:50:44 $

Author:

Tim Anderson

Constructor Summary

Selector(java.lang.String expression)
Construct a message selector that selects messages based on the supplied expression.

Method Summary

boolean

selects(javax.jms.Message message) Return if message is selected by the expression

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Selector

public Selector(java.lang.String expression)
         throws javax.jms.InvalidSelectorException

Construct a message selector that selects messages based on the supplied expression.

Parameters:

expression - the conditional expression

Throws:

javax.jms.InvalidSelectorException - if expression is invalid

Method Detail

selects

public boolean selects(javax.jms.Message message)

Return if message is selected by the expression

Parameters:

message - the message

Returns:

true if the message is selected, otherwise false