Overview

A wildcard subscription lets one subscriber match a whole family of channels with a single call, instead of wiring up a separate subscribeToEvents for every sub-channel and touching code each time a new one appears. It's the natural fit for monitoring, logging, or fan-in aggregation across a channel hierarchy — for example, watching every regional order channel from one place.

KubeMQ matches wildcard tokens against the channel hierarchy server-side at delivery time. * matches exactly one dot-separated segment, and > matches one or more trailing segments, so an EventsSubscription built with .channel("java-events.orders.*") catches any single-segment suffix, while .channel("java-events.>") catches everything under the prefix regardless of depth. Every delivered event still carries its exact channel, so the callback can tell which concrete sub-channel it came from even though the subscription itself only named a pattern.

Gotchas: * matches exactly one segment — it won't reach two levels deep, so orders.* misses orders.us.east; use > for that. Wildcards are only valid on Events subscriptions, not on publishEvent/publishes or on events-store, queues, or commands/queries. And an overly broad pattern like > at the root will quietly pull in every channel under that prefix, including ones you didn't intend to monitor.

Prerequisites

KubeMQ server running on localhost:50000
Java SDK installed (implementation 'io.kubemq.sdk:kubemq-sdk-Java:3.1.1' (Gradle) or Maven dependency from Getting Started)

Code

WildcardSubscriptionExample.java

package io.kubemq.example.events;

import io.kubemq.sdk.pubsub.EventMessage;
import io.kubemq.sdk.pubsub.EventsSubscription;
import io.kubemq.sdk.pubsub.PubSubClient;

/**
 * Wildcard Subscription Example
 *
 * Demonstrates subscribing to events using wildcard channel patterns (* and >).
 */
public class WildcardSubscriptionExample {

    private static final String ADDRESS = "localhost:50000";
    private static final String CLIENT_ID = "java-events-wildcard-subscription-client";

    public static void main(String[] args) throws InterruptedException {
        // Create a client connected to the KubeMQ server
        PubSubClient client = PubSubClient.builder()
                .address(ADDRESS)
                .clientId(CLIENT_ID)
                .build();

        EventsSubscription singleLevel = EventsSubscription.builder()
                .channel("java-events.orders.*")
                .group("")
                .onReceiveEventCallback(event ->
                    System.out.println("Single-level wildcard received: " + event.getChannel()))
                .onErrorCallback(err ->
                    System.err.println("Error: " + err.getMessage()))
                .build();

        // Subscribe with single-level wildcard (* matches one token)
        client.subscribeToEvents(singleLevel);
        System.out.println("Subscribed with single-level wildcard: java-events.orders.*");

        EventsSubscription multiLevel = EventsSubscription.builder()
                .channel("java-events.>")
                .group("")
                .onReceiveEventCallback(event ->
                    System.out.println("Multi-level wildcard received: " + event.getChannel()))
                .onErrorCallback(err ->
                    System.err.println("Error: " + err.getMessage()))
                .build();

        // Subscribe with multi-level wildcard (> matches one or more tokens)
        client.subscribeToEvents(multiLevel);
        System.out.println("Subscribed with multi-level wildcard: java-events.>");

        // Send events to different channels to demonstrate wildcard matching
        String[] channels = {"java-events.orders.us", "java-events.orders.eu", "java-events.inventory.update"};
        for (String ch : channels) {
            EventMessage msg = EventMessage.builder()
                    .channel(ch)
                    .body(("hello from " + ch).getBytes())
                    .metadata("wildcard-test")
                    .build();
            client.publishEvent(msg);
            System.out.println("Published to: " + ch);
        }

        // Wait for events to be delivered
        Thread.sleep(3000);
        // Clean up resources
        client.close();
        System.out.println("Wildcard subscription example completed.");
    }
}

How It Works

java-events.orders.* uses a single-level wildcard: * matches exactly one dot-separated token, so orders.us and orders.eu match but orders.us.east would not.
java-events.> uses a multi-level wildcard: > matches one or more tokens, so every channel under java-events. matches, including orders.us, orders.eu, and inventory.update.
Both subscriptions are active simultaneously; publishing to java-events.orders.us triggers both callbacks, while publishing to java-events.inventory.update only triggers the multi-level wildcard.

Wildcard Subscription

Overview

Prerequisites

Code

How It Works

Related

On this page