# Spring Boot (/integrations/spring-boot)



The KubeMQ Spring Boot Starter is a production-quality Spring Boot 3.x and Spring Cloud Stream integration for the [KubeMQ](https://kubemq.io) message broker. It brings KubeMQ into the Spring programming model through auto-configuration, a thread-safe `KubeMQTemplate` send API, and annotation-driven listeners — all built on the native KubeMQ Java SDK clients so your application speaks gRPC to the broker directly.

## Why Spring Boot + KubeMQ? [#why-spring-boot--kubemq]

* **Native Spring idioms** — auto-configuration, `@ConfigurationProperties` bound under `kubemq.*`, Spring Boot Actuator health contributors, and Micrometer metrics and observations
* **Annotation-driven listeners** — `@KubeMQEventListener`, `@KubeMQEventStoreListener`, `@KubeMQQueueListener`, `@KubeMQCommandHandler`, and `@KubeMQQueryHandler` turn beans into message consumers
* **`KubeMQTemplate` send API** — one injectable template covers all five messaging patterns (Events, Events Store, Queues, Commands, Queries) with sync, async, and fluent-builder variants
* **Kotlin support** — coroutine extensions, `Flow` adapters, and a configuration DSL via the Kotlin starter
* **Spring Cloud Stream binder** — bind Events, Events Store, and Queues through the Spring Cloud Stream programming model
* **First-class test harness** — `MockKubeMQServer`, TestContainers support, and a test starter for exercising producers and consumers without a live broker

## Requirements [#requirements]

The starter targets the JVM and a running **KubeMQ broker** reachable over native gRPC on port `50000`. Supported languages and versions:

| Requirement                | Version       |
| -------------------------- | ------------- |
| Java                       | 17+           |
| Kotlin (Kotlin starter)    | JVM target 17 |
| Spring Boot                | 3.2.0+        |
| Spring Cloud (binder BOM)  | 2023.0.0      |
| KubeMQ Spring Boot Starter | 1.0.0         |

<Callout type="info">
  The Spring Cloud Stream binder pulls in the **Spring Cloud 2023.0.0** BOM; add it only when you use the binder.
</Callout>

## Installation [#installation]

Add the starter dependency — it aggregates the auto-configuration and the KubeMQ Java SDK:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("io.kubemq:kubemq-spring-boot-starter:1.0.0")
}
```

Then point the application at your broker. The properties are bound under `kubemq.*`:

```yaml title="application.yml"
kubemq:
  address: localhost:50000
  client-id: my-app
```

Inject `KubeMQTemplate` to send, and annotate a bean method to receive:

```java title="OrderService.java"
@Service
public class OrderService {
    private final KubeMQTemplate template;

    public OrderService(KubeMQTemplate template) {
        this.template = template;
    }

    public void placeOrder(Order order) {
        template.sendEvent("orders", order);
    }
}
```

```java title="OrderConsumer.java"
@Component
public class OrderConsumer {
    @KubeMQEventListener(channels = "orders")
    public void onOrder(EventMessageReceived event) {
        // process event
    }
}
```

<Callout type="info">
  Start a local broker with Docker — the gRPC API the starter connects to listens on `50000`, and the shared HTTP/REST and dashboard endpoints on `9090`:

  <RunKubeMQ ports="[50000, 9090]" />
</Callout>

## Modules [#modules]

The project is a multi-module Gradle build. Add `kubemq-spring-boot-starter` to your project; the rest are pulled in transitively or added when you need Spring Cloud Stream, Kotlin, or testing support.

| Module                              | Description                                                                 |
| ----------------------------------- | --------------------------------------------------------------------------- |
| `kubemq-spring-boot-autoconfigure`  | Auto-configuration, `KubeMQTemplate`, listener annotations, health, metrics |
| `kubemq-spring-boot-starter`        | Dependency aggregator — add this to your project                            |
| `kubemq-spring-cloud-stream-binder` | Spring Cloud Stream binder for Events, Events Store, and Queues             |
| `kubemq-spring-boot-starter-kotlin` | Kotlin coroutine extensions, `Flow` adapters, and DSL                       |
| `kubemq-spring-boot-starter-test`   | `MockKubeMQServer`, TestContainers, and test harness                        |

## Architecture [#architecture]

`KubeMQAutoConfiguration` wires the native KubeMQ Java SDK clients — `PubSubClient`, `QueuesClient`, and `CQClient` — from your `kubemq.*` properties. The `KubeMQTemplate` send API and the `@KubeMQ*Listener` / `@KubeMQ*Handler` beans both delegate to those clients, which speak gRPC to the broker on port `50000`. There is no connector to enable — the starter is a native SDK client that connects directly.

<Mermaid
  chart="`
flowchart LR
  App[&#x22;Spring Boot Application&#x22;] --> Tmpl[&#x22;KubeMQTemplate<br/>+ @KubeMQ*Listener beans&#x22;]
  Tmpl --> SDK[&#x22;KubeMQ Java SDK<br/>PubSubClient · QueuesClient · CQClient&#x22;]
  SDK -->|&#x22;gRPC :50000&#x22;| KMQ[&#x22;KubeMQ Broker&#x22;]

  class App,Tmpl client
  class SDK external
  class KMQ broker
`"
/>

*Auto-configuration binds the three SDK clients from `kubemq.*` properties; the template and listener beans delegate to them over gRPC on port 50000.*

## Capabilities [#capabilities]

Each capability page documents the Spring API surface (`KubeMQTemplate` send methods and the `@KubeMQ*Listener` / `@KubeMQ*Handler` annotations) and links to the underlying KubeMQ pattern so you learn the concept once.

<Cards>
  <Card title="Events & Events Store" href="/integrations/spring-boot/how-to/events-and-events-store" description="Publish fire-and-forget events and durable, replayable events store messages with the template and @KubeMQEventListener / @KubeMQEventStoreListener. → /docs/learn/events, /docs/learn/events-store" />

  <Card title="Queues" href="/integrations/spring-boot/how-to/queues" description="Durable point-to-point messaging with sendQueueMessage and @KubeMQQueueListener for competing consumers. → /docs/learn/queues" />

  <Card title="Commands & Queries" href="/integrations/spring-boot/how-to/commands-and-queries" description="Synchronous request-response with sendCommand / sendQuery and the @KubeMQCommandHandler / @KubeMQQueryHandler annotations. → /docs/learn/rpc" />

  <Card title="Spring Cloud Stream" href="/integrations/spring-boot/how-to/spring-cloud-stream-binder" description="Bind Events, Events Store, and Queues through the Spring Cloud Stream functional programming model." />

  <Card title="Kotlin" href="/integrations/spring-boot/how-to/kotlin" description="Coroutine suspend extensions, Flow-based subscriptions, and the kubemq { } configuration DSL from the Kotlin starter." />
</Cards>

## Quick Links [#quick-links]

<Cards>
  <Card title="Getting Started" href="/integrations/spring-boot/tutorials/getting-started" description="Add the starter, configure a broker, and send and receive your first message." />

  <Card title="Concepts" href="/integrations/spring-boot/concepts" description="Understand auto-configuration, the template, listeners, and how patterns map to Spring." />

  <Card title="Guides" href="/integrations/spring-boot/how-to/configure-connection-tls-observability" description="Configure the connection, TLS/mTLS, and observability; test with MockKubeMQServer and TestContainers." />

  <Card title="Reference" href="/integrations/spring-boot/reference/configuration" description="Every kubemq.* configuration property, the KubeMQTemplate API, and the listener annotations." />
</Cards>

New to integrations? See [what an integration is](/integrations#what-an-integration-is) for the mental model, or start with the [KubeMQ Getting Started guide](/deploy) for core broker concepts. This starter speaks native gRPC on port `50000` — it is a direct SDK client, not a [connector](/connectors).