Message Selection and Filtering

By default, a MessageConsumer will process every message that is sent to its destination, regardless of whether or not it is interested in the message. You can modify this behavior to allow MessageConsumers to process only the messages in which they have an interest. You do this by setting up a message filter. This filter will only allow (or select) messages that pass the filter.

There are two steps in setting up a Message filter:

1. Initialize header and property fields in the message.

2. MessageConsumers specify a query string to select certain messages based on the header and property fields.

The next section describes the two steps in more detail.

Setting Header and Property Fields

You have already seen the standard set of message header fields back in the "The Message Header" section. You also have seen that a JMS client can set extra properties that a MessageConsumer can read after a message arrives at the destination. These two sets of attributes are used to provide the data that the message filter will use to select the appropriate message. After the header and property fields are set, the MessageConsumer just needs to use these fields when defining the message selector.

Specify a Message Selector Query String

A message selector is a java.lang.String whose syntax is based on a subset of the SQL92 conditional expression syntax. A message selector can't reference the message body. The selector can only reference the header and property fields. A message is considered to have passed the filter and become a selected 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.

The following code fragment shows an example of a message selector string:

 auctionWinnerEmail is not null and auctionPrice > 1000 

To use the previous query selector in an example, the following code fragment shows how to create a QueueReceiver using the message selector above:

 String selector = "auctionWinnerEmail is not null and auctionPrice > 1000";  qSession.createReceiver(queue, selector); 

The order evaluation of the selector is from left to right. You can use parentheses to adjust the evaluation order. The following is the same message selector you previously viewed , but this time with parentheses:

 (auctionWinnerEmail is not null) and (auctionPrice > 1000) 

Table 10.5 describes the type of tokens that can be used in a message selector and an example of each.

Table 10.5. Tokens That Can Be Used in a Message Selector

Type	Example
Literals	" salary" or 67
Identifiers	firstName
Whitespace	Space, tab, form feed, and line terminator
Standard bracketing	(salary)
Logical operators	NOT , AND , OR
Comparison operators	= , > , >= , < , <= , <>
Arithmetic operators	+ , * ,
Is Null Comparison	email is null
Is Not Null Comparison	email is not null

The tokens in Table 10.5 are the most commonly used tokens. There are a few other lesser-used tokens, but the ones from Table 10.5 should be enough for most applications.

Note

If you attempt to set a syntactically invalid message selector, a JMSException will be thrown.