A selector is a way of attaching a filter to a given subscription, also known as content-based routing. In JMS, the selector uses message properties and headers compared against Boolean expressions to filter messages. The Boolean expressions are defined using SQL92 syntax. The following table summarizes the selector language used in JMS:

The code for the sample stock price consumer application in this recipe is identical to the consumer code from the previous recipe except for a few small changes. Let's take a look at the code and see how we apply a selector to our consumer's subscription:

public class SelectiveTickerConsumer {

    private final String connectionUri = "tcp://localhost:61616";
    private ActiveMQConnectionFactory connectionFactory;
    private Connection connection;
    private Session session;
    private Destination destination;
    private String selector;

    public void before() throws Exception {
        connectionFactory = new 
            ActiveMQConnectionFactory(connectionUri);
        connection = connectionFactory.createConnection();
        connection.start();
        session = connection.createSession(
            false, Session.AUTO_ACKNOWLEDGE);
        destination = session.createTopic("EVENTS.QUOTES");
        selector = System.getProperty(
            "QuoteSel", "symbol = 'GOOG'");
    }

    public void run() throws Exception {
        System.out.println(" Running example with selector: " + selector);

        MessageConsumer consumer = 
             session.createConsumer(destination, selector);
        consumer.setMessageListener(new EventListener());
        TimeUnit.MINUTES.sleep(5);
        connection.stop();
        consumer.close();
    }
}

As you can see in the sample code, we added a variable named selector to our consumer application and initialized it by reading a system property named QuoteSel, which defaults to symbol = 'GOOG'. We then pass in our set selector value to the Session object's createConsumer() method and that's it; the remainder of the code is unchanged.

By default our example stock price consumer will now only receive price updates for the ticker symbol GOOG. We can alter this by running the consumer application again and specifying a different selector and then running the price update producer application again. Try it yourself by running the demos again but using some different selector values.

To receive updates for both GOOG and AAPL run your consumer with:

$mvn exec:java –DQuoteSel="symbol='GOOG' OR symbol='AAPL'

To receiver updates for MSFT but only when the price is greater than $800 try:

$mvn exec:java –DquoteSel="symbol='MSFT' AND price >= 800"

Practice yourself by coming up with more selectors on your own and rerunning the consumer and producer applications.

ActiveMQ uses a paging architecture for messages that are stored on the broker. By default only a certain number of pages are brought into memory at any given time for a destination and this can have an impact on your consumers that use message selectors. If the destination contains a large number of messages and the selector doesn't match any of the messages that have been paged in, your consumer can stall until either the messages that are paged in are acknowledged or expired.

This sort of scenario happens most often when your selector is a sparse matching selector meaning it only matches a few messages out of the larger whole. If this happens, you can work around this issue by increasing the page size ActiveMQ uses for a destination. Refer to the documentation on setting destination policies for more information:

http://activemq.apache.org/per-destination-policies.html