Interface UmaDbClient

All Known Implementing Classes:

UmaDbClientImpl

public interface UmaDbClient

Main interface for interacting with the UmaDb event store.

Clients use this interface to append events, read events, and manage the connection to the UmaDb server. Implementations handle all network communication, serialization, and concurrency internally.

Method Summary

Modifier and Type	Method	Description
static UmaDbClientBuilder	builder()	Creates a new UmaDbClientBuilder for constructing an UmaDbClient instance.
void	connect()	Establishes a connection to the UmaDb server.
long	getHeadPosition()	Returns the position of the most recent event in the event store.
Optional<Long>	getTrackingInfo(String source)	Returns the last recorded position for a named source.
AppendResponse	handle(AppendRequest appendRequest)	Handles an append request, writing events to the event store.
Iterator<ReadResponse>	handle(ReadRequest readRequest)	Handles a read request, returning an iterator over ReadResponse objects.
void	shutdown()	Shuts down the client, closing any active connections and releasing resources.
Iterator<SubscribeResponse>	subscribe(SubscribeRequest subscribeRequest)	Opens a continuous subscription, returning an iterator over SubscribeResponse batches.

Method Details

builder

static UmaDbClientBuilder builder()

Creates a new UmaDbClientBuilder for constructing an UmaDbClient instance.

The builder allows configuring:

• Server host and port
• TLS using a custom Certificate Authority (CA)
• API key authentication

UmaDbClient client = UmaDbClient.builder()
    .withHostAndPort("localhost", 50051)
    .withTls("/path/to/ca.pem")
    .withApiKey("my-api-key")
    .build();

Returns:

a new UmaDbClientBuilder

connect

void connect()

Establishes a connection to the UmaDb server.

This method must be called before performing any operations such as appending or reading events.

Throws:

UmaDbException - if the connection cannot be established

handle

AppendResponse handle(AppendRequest appendRequest)

Handles an append request, writing events to the event store.

The AppendRequest may include optional AppendConditions that enforce conditional appends. Returns an AppendResponse containing the position of the last appended event.

Parameters:

appendRequest - the request describing the events to append

Returns:

the response containing the position of the last appended event

Throws:

UmaDbException - if the append fails (e.g., due to conditional constraints, serialization errors, or server issues)

handle

Iterator<ReadResponse> handle(ReadRequest readRequest)

Handles a read request, returning an iterator over ReadResponse objects.

Each ReadResponse contains a batch of sequenced events and optionally the head position of the event stream at the time of the response. The iterator is exhausted once the head position captured at request time has been reached; to keep receiving events as they are appended, use subscribe(SubscribeRequest) instead.

Parameters:

readRequest - the request describing which events to read

Returns:

an iterator over ReadResponse batches

Throws:

UmaDbException - if the read fails (e.g., network error or serialization failure)

subscribe

Iterator<SubscribeResponse> subscribe(SubscribeRequest subscribeRequest)

Opens a continuous subscription, returning an iterator over SubscribeResponse batches.

The subscription first replays already-recorded events matching the request and then blocks, yielding further batches as new events are appended. The iterator does not terminate on its own; call shutdown() to end the stream.

Parameters:

subscribeRequest - the request describing which events to subscribe to

Returns:

an iterator over SubscribeResponse batches

Throws:

UmaDbException - if the subscription fails (e.g., network error)

getTrackingInfo

Optional<Long> getTrackingInfo(String source)

Returns the last recorded position for a named source.

Sources are checkpointed by attaching TrackingInfo to an AppendRequest.

Parameters:

source - the unique identifier of the consumer or projection

Returns:

the position the source has processed up to, or Optional.empty() if no tracking info exists for it

Throws:

UmaDbException - if the lookup fails

getHeadPosition

long getHeadPosition()

Returns the position of the most recent event in the event store.

This value can be used for optimistic concurrency control, checkpointing, or as a reference point for subsequent reads.

Returns:

the sequence number of the latest event

Throws:

UmaDbException.IoException - if the position cannot be retrieved

shutdown

void shutdown()

Shuts down the client, closing any active connections and releasing resources.

After calling this method, the client should not be used for any further operations.

Throws:

UmaDbException - if the connection cannot be closed properly