Selectors

Selectors enable client applications to specify which messages they are interested in receiving, as determined by the messages’ header field and property values. A selector is a string up to a maximum of 2,000 bytes that uses a conditional expression syntax that is a subset of SQL92. For detailed information on message selector syntax, refer to the Java Message Service Specification – Version 1.1. Selectors are supported by all Solace messaging APIs.

When a selector is used, a client only receives a message if the selector evaluates to true when the message’s header field and property values are substituted for their corresponding identifiers in the selector. The event broker filters out messages that do not match.

Selectors can be set for:

Performance Considerations When Using Selectors

While selectors are fully supported, the best performance is typically achieved using topic matching without selectors. In many cases, it’s possible to include the message properties that would be selected upon within the topic hierarchy. Topic subscriptions and topic subscription exceptions can then be used to match against the relevant levels within the topic to implement selector expression-like matching.

Topic subscriptions and topic subscription exceptions support wildcards and prefix matching within levels. With wildcards, exceptions, and the ability to specify multiple subscriptions or exceptions for a queue or topic endpoint, it’s possible to implement matching operations like AND, OR, and NOT.

Consideration must also be given to performance when using selectors to retrieve messages from deep queues. The Solace event broker needs to retrieve each of the queue’s messages, potentially from disk, to evaluate its contents against the consumer’s selector expression. If the queue is very deep, it may take several seconds before the first matching message is found. Large messages also take longer to retrieve and evaluate against selector expressions. These challenges are eliminated when using topic subscriptions for filtering, because the filtering occurs before the event broker adds the messages into the queues.

In general, you should avoid using selectors whenever possible

Selector Identifier Mapping between JMS and Solace APIs

The following table lists standard JMS identifiers and their equivalent Solace identifiers. Solace identifiers are encoded in structured data maps of Solace SMF messages as reserved keys. Both types of identifiers can be used to define selectors.

For example, JMSCorrelatonID is encoded in the map with the key ci. If you are using the JMS API and you want to match only messages where the correlation ID, which is a string, is "myCorrelationId", you could write a selector expression in JMS like this:

JMSCorrelationID = 'myCorrelationId'

If you are using a Solace messaging API, you could write the same expression like this:

ci = 'myCorrelatonId'

JMS may have no set methods for some Solace identifiers, such as message sequence number (sn), but it is still possible to select on the sn identifier.

Selector Identifiers

 

JMS Identifier Solace Identifier Relevant Solace Message Property

Message Header Fields

JMSCorrelationID

ci

CorrelationId

JMSDeliveryMode

NA

DeliveryMode

JMSMessageID

mi

ApplicationMessageId

JMSPriority

NA

Priority

JMSReplyTo

rt

ReplyTo

JMSTimestamp

ts

SenderTimestamp

JMSType

mt

ApplicationMessageType

NA

si

SenderID

NA

sn

SequenceNo

NA

ex

Expiration

NA

ct

HttpContentType

NA

ce

HttpContentEncoding

JMS-Defined Properties

JMSXGroupSeq

Treated as user‑specified

Solace messaging APIs can access JMSX properties as user properties with the same property name as used in JMS.

JMSXGroupID

Treated as user‑specified

JMSXUserID

<client-username>

The JMSXUserID property is only available when using Basic client authentication and if the jmsx-user-id-enabled Connection Factory property is enabled.

User-Defined Message Properties

User‑specified

User‑specified

NA

Setting Selectors for Consumers

Selectors can be set for durable topic subscribers that use Guaranteed Transport or message consumers of Queues that use Guaranteed Transport. (Message selectors cannot be set for consumers that are using Direct Transport. If message selectors are configured, configuration exceptions are returned.)

Selectors function differently for each type of consumer:

  • Durable topic subscriber

    When a selector is defined for a durable topic subscriber, messages whose messages’ header fields and properties do not match the corresponding identifiers defined in the selector are not queued to the durable topic subscription. Therefore, a selector acts as an ingress filter for durable topic subscriptions.

    If the durable topic subscriber disconnects, and its selector is changed, all existing messages from the durable topic subscription are removed before the topic subscriber binds again. To prevent the removal of all messages for a durable topic subscription when the durable topic subscriber rebinds, the selector used must be identical to the one used in the previous bind.

  • Queue consumer

    When a consumer binds to an exclusive queue, the messages that it can consume are filtered by the selector defined for the consumer. The messages excluded by the consumer’s selector remain in the queue and can be consumed by subsequent consumers with different selectors or no selectors that might bind. Selectors act as egress filters on queues.

    When a consumer binds to a non-exclusive queue, messages are consumed by bound clients in a round-robin fashion according to their selectors. Once a message is consumed, it is no longer available for subsequent clients.

    The following code shows how to define a selector for a consumer on a queue:

    Connection connection = null;
    queue = session.createQueue("queue");
    selector = new String("phone NOT LIKE '12%3'");
    consumer = session.createConsumer(queue,selector);