# Wildcard Subscription (/sdks/java/how-to/events/wildcard-subscription)



## Overview [#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 [#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](/sdks/java))

## Code [#code]

```java title="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 [#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.

## Related [#related]

* [Pattern overview](/learn/events/getting-started)
* [Java SDK Reference](/sdks/java/reference/events)
* [Basic Pub/Sub](/sdks/java/tutorials/basic-pubsub)
* [Cancel Subscription](/sdks/java/how-to/events/cancel-subscription)