Interface UmaDbAsyncClient

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
UmaDbAsyncClientImpl
public interface UmaDbAsyncClient extends AutoCloseable
Non-blocking counterpart to UmaDbClient.

Unary operations return a CompletableFuture; the two server-streaming operations deliver their batches to a UmaDbStreamObserver and return a UmaDbStream handle for flow control and cancellation. 

UmaDbAsyncClient client = UmaDbClient.builder()
    .withHostAndPort("localhost", 50051)
    .buildAsync();

client.connect();

Error handling

Unlike the blocking client, which throws UmaDbException directly, failures here arrive wrapped: a future completes exceptionally with a CompletionException (or ExecutionException from get()) whose cause is the UmaDbException. Streaming failures are delivered unwrapped to UmaDbStreamObserver.onError(UmaDbException).

Argument validation is the exception to that rule: passing a null observer or a blank source throws immediately, because those are programming errors rather than remote failures.

Threading

Futures are completed on a gRPC callback thread, so any continuation attached with thenApply and friends runs there too. Use the *Async variants with your own executor for anything expensive. The same applies to UmaDbStreamObserver callbacks.

See Also:

  • Method Details

    • connect

      void connect()
      Establishes a connection to the UmaDB server.

      This method must be called before performing any operations. It is idempotent.

      Throws:
      UmaDbException - if the connection cannot be established

    • handle

      CompletableFuture<AppendResponse> handle(AppendRequest appendRequest)
      Appends events to the event store.
      Parameters:
      appendRequest - the request describing the events to append
      Returns:
      a future completing with the position of the last appended event, or completing exceptionally with a UmaDbException cause

    • getHeadPosition

      CompletableFuture<Long> getHeadPosition()
      Returns the position of the most recent event in the event store.
      Returns:
      a future completing with the sequence number of the latest event

    • getTrackingInfo

      CompletableFuture<Optional<Long>> getTrackingInfo(String source)
      Returns the last recorded position for a named source.
      Parameters:
      source - the unique identifier of the consumer or projection
      Returns:
      a future completing with the position the source has processed up to, or Optional.empty() if no tracking info exists for it
      Throws:
      IllegalArgumentException - if source is null or blank

    • handle

      UmaDbStream handle(ReadRequest readRequest, UmaDbStreamObserver<ReadResponse> observer)
      Reads events, delivering each batch to the given observer.

      The stream ends, with UmaDbStreamObserver.onCompleted(), once the head position captured when the request was received has been reached. To keep receiving events as they are appended, use subscribe(SubscribeRequest, UmaDbStreamObserver) instead.

      Parameters:
      readRequest - the request describing which events to read
      observer - receives the batches; must not be null
      Returns:
      a handle for controlling demand and cancelling the stream
      Throws:
      IllegalArgumentException - if observer is null

    • subscribe

      UmaDbStream subscribe(SubscribeRequest subscribeRequest, UmaDbStreamObserver<SubscribeResponse> observer)
      Opens a continuous subscription, delivering each batch to the given observer.

      The subscription replays already-recorded events matching the request and then continues to deliver new events as they are appended. It does not end on its own — call UmaDbStream.cancel() or shutdown() to stop it.

      Parameters:
      subscribeRequest - the request describing which events to subscribe to
      observer - receives the batches; must not be null
      Returns:
      a handle for controlling demand and cancelling the subscription
      Throws:
      IllegalArgumentException - if observer is null

    • shutdown

      void shutdown()
      Shuts the client down, cancelling any live streams and closing the connection.

      Idempotent. After calling this the client should not be used again; further calls fail through the returned future or the observer rather than by throwing.

      Throws:
      UmaDbException - if the connection cannot be closed properly

    • close

      default void close()
      Equivalent to shutdown(), so the client can be used in a try-with-resources block.
      Specified by:
      close in interface AutoCloseable