Class UmaDbClientBuilder

java.lang.Object
io.umadb.client.UmaDbClientBuilder
public final class UmaDbClientBuilder extends Object
Builder for creating UmaDbClient instances.

This builder supports configuring:

  • Target host and port
  • TLS using a custom Certificate Authority (CA)
  • API key authentication (sent as a Bearer token)

Security model

If an API key is configured, TLS must also be enabled. The client will refuse to send API keys over non-TLS connections.

Typical usage

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

This class is mutable and not thread-safe. It is intended for one-time configuration during client construction.

  • Constructor Details

    • UmaDbClientBuilder

      public UmaDbClientBuilder()

  • Method Details

    • withHostAndPort

      public UmaDbClientBuilder withHostAndPort(String host, int port)
      Sets both the host and port for the UmaDB server.
      Parameters:
      host - the server hostname or IP address
      port - the server port
      Returns:
      this builder instance

    • withHost

      public UmaDbClientBuilder withHost(String host)
      Sets the host for the UmaDB server.
      Parameters:
      host - the server hostname or IP address
      Returns:
      this builder instance

    • withPort

      public UmaDbClientBuilder withPort(int port)
      Sets the port for the UmaDB server.
      Parameters:
      port - the server port
      Returns:
      this builder instance

    • withTlsEnabled

      public UmaDbClientBuilder withTlsEnabled()
      Enables TLS with default settings.
      Returns:
      this builder instance

    • withCertificateAuthority

      public UmaDbClientBuilder withCertificateAuthority(String caFilePath)
      Enables TLS using a custom Certificate Authority (CA) certificate.

      This is typically required when connecting to servers using self-signed certificates or private PKI setups.

      Parameters:
      caFilePath - path to the CA certificate file (PEM format)
      Returns:
      this builder instance

    • withApiKey

      public UmaDbClientBuilder withApiKey(String apiKey)
      Configures API key authentication.

      The API key will be sent as an Authorization: Bearer <token> header on all gRPC requests.

      Note: TLS is automatically enabled when using an API key.

      Parameters:
      apiKey - the API key to use for authentication
      Returns:
      this builder instance

    • withExecutor

      public UmaDbClientBuilder withExecutor(Executor executor)
      Sets the executor on which gRPC invokes callbacks.

      This governs the threads that complete the futures and invoke the UmaDbStreamObserver callbacks of a UmaDbAsyncClient, and it is therefore mainly of interest for the asynchronous client. gRPC keeps the callbacks of any single call serialized regardless of the executor used, so event ordering is preserved.

      On a recent JDK, Executors.newVirtualThreadPerTaskExecutor() is a good choice. If left unset, gRPC's own default executor is used.

      Parameters:
      executor - the executor to dispatch callbacks on
      Returns:
      this builder instance

    • build

      public UmaDbClient build()
      Builds a new UmaDbClient using the configured settings.
      Returns:
      a fully configured UmaDbClient
      Throws:
      IllegalArgumentException - if required configuration is missing or if an API key is configured without TLS

    • buildAsync

      public UmaDbAsyncClient buildAsync()
      Builds a new UmaDbAsyncClient using the configured settings.

      The asynchronous client is independent of any client returned by build(): it opens and owns its own connection, and shutting one down does not affect the other.

      Returns:
      a fully configured UmaDbAsyncClient
      Throws:
      IllegalArgumentException - if required configuration is missing or if an API key is configured without TLS