# Java SDK

The **Java SDK** provides programmatic access to EventSourcingDB **from Java applications**. It offers a convenient interface for **writing**, **reading**, and **observing events** without having to interact with the HTTP API directly.

> **Partner SDK**
>
> This SDK is **developed** and maintained by **[Digital Frontiers GmbH & Co. KG](https://www.digitalfrontiers.de/)**, a **trusted partner** of the EventSourcingDB team. It has been **reviewed and recommended** as a high-quality integration, but it is **not maintained by the creators of EventSourcingDB**.

## Installation

To **install the SDK**, add the following line to your `build.gradle.kts` file:

```kotlin
implementation("com.opencqrs:esdb-client-spring-boot-starter:1.0-rc3")
```

You can also find this SDK on **[Maven Central](https://central.sonatype.com/artifact/com.opencqrs/esdb-client-spring-boot-starter)**.

## Capabilities

This SDK intentionally focuses on **application-level use cases**. It provides core functionality for **writing**, **reading**, and **observing events**, and deliberately **excludes operational concerns** such as backup, restore, or health monitoring.

For a detailed explanation of the specific requirements behind each capability, see the **[Compliance Criteria](/docs/eventsourcingdb/sdks/compliance-criteria)**.

> **Version Information**
>
> The list is based on **SDK version `1.0.0`**, tested against **EventSourcingDB `1.2.0`**, verified on **November 3rd, 2025**.

> **Essentials**
>
> <span style="color:lime;">✓</span> Initialize the Client<br />
> <span style="color:lime;">✓</span> Ping the Server<br />
> <span style="color:lime;">✓</span> Verify API Token

> **Writing Events**
>
> <span style="color:lime;">✓</span> Write Single Events<br />
> <span style="color:lime;">✓</span> Write Multiple Events<br />
> <span style="color:lime;">✓</span> Use `isSubjectPristine`<br />
> <span style="color:red;">✗</span> Use `isSubjectPopulated`<br />
> <span style="color:lime;">✓</span> Use `isSubjectOnEventId`<br />
> <span style="color:red;">✗</span> Use `isEventQlQueryTrue`<br />
> <span style="color:red;">✗</span> Include OpenTelemetry Trace Context

> **Reading Events**
>
> <span style="color:lime;">✓</span> Read Events by Subject<br />
> <span style="color:lime;">✓</span> Read Recursively<br />
> <span style="color:lime;">✓</span> Read Chronological and Anti-Chronological<br />
> <span style="color:lime;">✓</span> Use Boundaries<br />
> <span style="color:lime;">✓</span> Use `fromLatestEvent`

> **Using EventQL**
>
> <span style="color:lime;">✓</span> Execute EventQL Queries

> **Observing Events**
>
> <span style="color:lime;">✓</span> Observe Events By Subject<br />
> <span style="color:lime;">✓</span> Observe Recursively<br />
> <span style="color:lime;">✓</span> Use Boundaries<br />
> <span style="color:lime;">✓</span> Use `fromLatestEvent`

> **Metadata and Discovery**
>
> <span style="color:red;">✗</span> Register Event Schemas<br />
> <span style="color:red;">✗</span> List Subjects<br />
> <span style="color:red;">✗</span> List Event Types<br />
> <span style="color:red;">✗</span> List a Specific Event Type<br />
> <span style="color:red;">✗</span> Verify Event Hashes<br />
> <span style="color:red;">✗</span> Verify Event Signatures

> **Testcontainers Support**
>
> Explicit Testcontainers support is not included yet. However, you can see how to run EventSourcingDB with Testcontainers in [this example](https://github.com/open-cqrs/opencqrs/blob/50669295e650475d1cd3c5033c0ae998d38a98f6/esdb-client/src/test/java/com/opencqrs/esdb/client/EsdbClientIntegrationTest.java#L691-L707).

## Documentation

Refer to the SDK's **[GitHub repository](https://github.com/open-cqrs/opencqrs)** for **detailed usage instructions**, **code examples**, and **API reference**.

## Further Resources

- **Repository**: **[open-cqrs/opencqrs](https://github.com/open-cqrs/opencqrs)**
- **Registry**: **[Maven Central](https://central.sonatype.com/artifact/com.opencqrs/esdb-client-spring-boot-starter)**
- **License (Apache 2.0)**: **[License file](https://github.com/open-cqrs/opencqrs/blob/main/LICENSE.txt)**
- **Issue tracker**: **[GitHub Issues](https://github.com/open-cqrs/opencqrs/issues)**