Skip to content

ESDB Client

The esdb-client module provides helper classes, encapsulating the communication with the EventSourcingDB. This relieves the user from dealing with the database's HTTP-based API directly. It provides the following key functionalities:

  • Publishing events using EventCandidate instances
  • Reading of published events as Event instances
  • Querying published events using EventQL
  • Continuously observing published events
  • Monitoring the ESDB health status

All these operations provide suitable client exceptions in case of an error.

Info

The key functionalities of the client SDK are provided using core JDK classes, e.g. using java.net.http.HttpClient for HTTP communication. However, the JDK does not provide suitable support for JSON marshalling. The Marshaller defines the necessary JSON transformation operations. JacksonMarshaller provides an implementation of this interface, requiring an additional Jackson dependency.

Configuration

The ESDB client functionality is implemented within the EsdbClient Java class. An instance of this class can be obtained, either by manually instantiating it or using Spring Boot autoconfiguration.

Tip

In either case it is required to make sure Jackson Databind is included as dependency, unless a custom Marshaller implementation is used.

Manual Configuration

An instance of EsdbClient can be created providing the necessary configuration properties:

  • a java.net.URI pointing to the EventSourcingDB instance to connect to
  • an API token to authenticate
  • a Marshaller instance responsible for serializing and deserializing events
  • a java.net.http.HttpClient.Builder instance

The following example shows, how to instantiate an EsdbClient using the built-in JacksonMarshaller.

import com.fasterxml.jackson.databind.ObjectMapper;
import com.opencqrs.esdb.client.jackson.JacksonMarshaller;

import java.net.URI;
import java.net.http.HttpClient;

public class EsdbClientConfiguration {

    public static EsdbClient esdbClient() {
        return new EsdbClient(
                URI.create("http://localhost:3000"),
                "<api token>",
                new JacksonMarshaller(new ObjectMapper()),
                HttpClient.newBuilder()
        );
    }
}

The correct configuration can be confirmed, by calling authenticate(), e.g. as follows:

public static void main(String[] args){
    EsdbClientConfiguration.esdbClient().authenticate();
}

Spring Boot Auto-Configuration

For Spring Boot applications using the esdb-client-spring-boot-starter module and Jackson Databind EsdbClientAutoConfiguration provides a fully configured EsdbClient Spring bean. The following Spring Boot configuration properties must be provided, e.g. via a suitable application.properties file:

esdb.server.uri=http://localhost:3000
esdb.server.api-token=<api token>
With that configuration in place the auto-configured EsdbClient instance can be auto-wired within any other Spring bean, if needed. The configuration can be further customized by:

  • overriding the EsdbClient Spring bean with an application-defined one
  • by providing a custom Marshaller Spring bean
  • by providing a custom java.net.http.HttpClient.Builder Spring bean

Tip

In order to make sure the EventSourcingDB connection is configured properly, it is recommended to include Spring Boot Actuator in the dependencies. EsdbHealthContributorAutoConfiguration will then make sure the Spring Boot application regularly checks the ESDB health and will expose this information via the context path /actuator/health/esdb.