Using Message Selectors

A message selector allows a JMS consumer to be more selective about the messages that it receives from a particular topic or queue. A message selector uses message properties and message headers as criteria in conditional expressions. These expressions use Boolean logic to declare the messages that are delivered to a client. The message consumer will only receive messages where the headers and properties match the selector. There are different patterns that can be used in selector strings to filter messages and the broker (JMS provider) filters messages according to that query. It is not possible for a message selector to filter messages on the basis of the content of the message body.

Understanding how message selectors work with WSO2 MB

The way selectors work depends on the type of subscription that is created from JMS clients. The following sections explain the different scenarios:

Queue subscriptions

• Only messages that match the selector will be delivered to the subscriber. 
• If at least one subscriber out of a few subscribers for a queue has a matching selector, the message will be delivered to that subscriber. 
• If more than one subscriber has a matching selector, the messages will be delivered in round robin manner between those subscribers. 
• If none of the subscribers have matching selectors, that message will be placed in the Dead Letter Channel (DLC).

Topic subscriptions (non-durable)

• Only messages that match the selector will be delivered to the subscriber. 
• If none of the subscribers have selectors matching the message, the message is dropped.
• Selectors are not evaluated when messages are received by the Broker. Messages will be written anyway if there are subscribers for that topic, and the selectors are evaluated upon delivery.

Topic subscriptions (durable)

• Only messages that match the selector will be delivered to the durable topic subscriber. 
• When keeping a copy of a message coming for a topic for the particular subscription ID, selectors are not evaluated. They are evaluated upon delivery only. 
• If a message does not match with the selector for a particular durable topic subscription, it will be routed to the Dead Letter Channel (DLC). 

Messages routed to DLC

• If none of the subscribers have matching selectors with a message and if the message is for a durable queue or durable subscription, the message is routed to the DLC.
• User has the option to delete messages selectively if they are unnecessary. 
• It is possible to create a new queue and route all unmatched messages to that queue if required. 
• It is possible to create a new subscriber with a matching selector for some or all messages routed to the DLC and route all messages to the original queue again. Then, if there are newly created matching subscriptions, those messages will be delivered accordingly. Other messages will go to DLC queue once again. 

Using message headers as selector criteria

A message header contains a number of predefined fields that contain values that both clients and providers can use to identify and to route messages. Following is a list of message header selector strings that are supported:

The following message headers will not be filtered by the broker as they are handled by the JMS provider and the default values override the selector string:

• JMSDeliveryMode
• JMSExpiration
• JMSPriority
• JMSRedelivered

Using message properties as selector criteria

If you need values in addition to those provided by the header fields, you can create and set properties for the messages. Following is a list of message property selector strings that are supported:

Examples of selector patterns

Given below are some sample selector patterns.

Subscribing to topics/queues using selectors

The createConsumer and createDurableSubscriber methods allow you to specify a message selector as an argument when you create a message consumer.

You can create a message selector subscriber for a topic as shown in the example given below. Note that the nolocal parameter is set to 'false' as it is not supported by WSO2 MB. However, messages will be delivered to the subscriber irrespective of the nolocal parameter.

String messgeSelector="JMSType='AAAA'"; 
topicSession.createSubscriber(topic,messgeSelector,false)

The following examples illustrate how you can create a subscriber using selectors. The messageSelector property is set to "releaseYear < 1980" in all of these examples.

Queue subscription

QueueSession queueSession =
        queueConnection.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
 
//Receive message
Queue queue =  (Queue) ctx.lookup(queueName);
 
MessageConsumer queueReceiver = queueSession.
        createConsumer(queue, "releaseYear < 1980");

Non-durable topic subscription

TopicSession topicSession =
        topicConnection.createTopicSession(false, QueueSession.AUTO_ACKNOWLEDGE);
 
Topic topic = topicSession.createTopic(topicName);
 
javax.jms.TopicSubscriber topicSubscriber = topicSession.
        createSubscriber(topic, "releaseYear < 1980", false);

Durable topic subscription

TopicSession topicSession =
        topicConnection.createTopicSession(false, QueueSession.AUTO_ACKNOWLEDGE);
Topic topic = topicSession.createTopic(topicName);
 
javax.jms.TopicSubscriber topicSubscriber = topicSession.
        createDurableSubscriber(topic, "mySub4", "releaseYear < 1980", false

Publishing messages using selectors

When publishing messages you need to add the 'releaseYear' JMS property and set the value as shown below.

javax.jms.QueueSender queueSender = queueSession.createSender(queue);
int currentMsgCount = 0;
 
while(currentMsgCount < this.messageCount) {
    TextMessage textMessage = queueSession.
          createTextMessage("test: (" + currentMsgCount + ")");  
textMessage.setLongProperty("releaseYear", 1990);  
queueSender.send(textMessage);  
System.out.println("Sent message: " + currentMsgCount);
currentMsgCount ++;
}