Package io.umadb.client

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 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. If ReadRequest.subscribe() is true, the iterator will continue to provide new events as they are appended.

      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)

    • 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