Using Selectors
Selectors enable clients to specify which messages that 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.
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:
- Flows bound to a Queue or Topic Endpoint. Refer to Setting Selectors on Endpoints.
- Browsers or Browser Flows. Refer to Browsing Guaranteed Messages.
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.
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 |
The JMSXUserID property is only available when using Basic client authentication and if the |
||
User-Defined Message Properties |
User‑specified |
User‑specified |
NA |
Setting Selectors on Endpoints
A selector can be set on a Flow that binds to either a Queue or a Topic Endpoint. A selector functions differently on each endpoint type:
- Queue
Selectors act as egress filters on Queues.
When a Flow binds to an exclusive Queue, the selector defined for the Flow filters the messages to be consumed by the client. Non-selected messages remain in the Queue and can be consumed by clients on subsequent Flows with different selectors that might bind.
When a Flow 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.
- Topic Endpoint
Selectors act as ingress filters on Topic Endpoints.
When a Flow binds to a Topic Endpoint, messages that match the Topic subscription are received by the Topic Endpoint. When a selector is defined for the Flow, messages whose message header fields and properties do not match the corresponding identifiers defined in the selector are not queued to the Topic Endpoint.
If a Flow disconnects from a durable Topic Endpoint, and the selector is changed, all existing messages are removed when the Flow binds again. To prevent removing messages for a Topic Endpoint when rebinding, the selector used must be an identical string to the one used in the previous bind.
PubSub+ Messaging API | Use |
---|---|
JCSMP |
ConsumerFlowProperties.setSelector(...) |
Java RTO |
FlowHandle.PROPERTIES.SELECTOR |
C |
SOLCLIENT_FLOW_PROP_SELECTOR |
.NET |
FlowProperties.Selector |
JavaScript and Node.js |
Not applicable |
Related Samples
For an example of how to set selectors for a Flow, refer to the messageSelectorsOnQueue
sample for the appropriate messaging API.