Selective Consumer

Use the Selective Consumer pattern when a service reads from a shared channel but should receive or process only the messages that match its criteria.

The pattern is implemented at the consumer boundary or immediately inside the consumer flow. Use broker-side selection when the channel supports selectors based on message metadata. Use flow-level selection when the decision depends on payload content or rules that must run after delivery.

Broker-side selection

Use broker-side selection when the broker can evaluate the criteria before the message reaches the service. For JMS-backed channels, configure a JMS listener service with messageSelector so the service receives only messages whose headers or properties match the selector expression.

Visual Designer

1. Create the JMS-backed event service with the JMS listener.
2. Configure the listener connection with the broker endpoint and credentials through configurable variables.
3. Set the service queue or topic in @jms:ServiceConfig.
4. Set messageSelector to the selector expression, such as eventType = 'OrderCreated' AND priority = 'high'.
5. Add processing steps in the onMessage flow. The broker delivers only messages that match the selector.
6. Ensure producers set the message properties used by the selector before publishing to the shared channel.

Ballerina Code

@jms:ServiceConfig {
    queueName: "orders",
    messageSelector: "eventType = 'OrderCreated' AND priority = 'high'"
}
service "priority-order-consumer" on orderListener {
    remote function onMessage(jms:Message message) returns error? {
        check processPriorityOrder(message);
    }
}

Flow-level selection

Use flow-level selection with if/else statements when the consumer must inspect the delivered payload, call another system, or apply rules that cannot be expressed as a broker selector. The service still reads from the shared channel, but the accepted branch contains the processing logic and the unmatched branch is ignored or handled separately.

Visual Designer

1. Create or open the consumer service that receives messages from the shared channel.
2. Open the message handler flow and add a step.
3. Add an If node at the point where the flow has the payload fields needed for selection.
4. Set the condition to the consumer criteria, such as order.priority == "high" && order.region == "west".
5. Add the processing steps inside the True branch.
6. Leave the False branch empty when unmatched messages should be ignored, or add separate handling for rejected messages.

Ballerina Code

function consumeOrder(OrderEvent order) returns error? {
    if order.priority == "high" && order.region == "west" {
        check processWestPriorityOrder(order);
    }
}