Package io.oxia.client.api

Interface OxiaClientBuilder

public interface OxiaClientBuilder
Entry point for creating an Oxia client.

Obtain a builder via create(String) with the address of an Oxia server, configure it fluently, and then call syncClient() or asyncClient() to produce a SyncOxiaClient or AsyncOxiaClient. 


 SyncOxiaClient client = OxiaClientBuilder.create("localhost:6648")
         .namespace("my-namespace")
         .requestTimeout(Duration.ofSeconds(10))
         .syncClient();

Most settings have defaults that work well for typical workloads — only override what you need.

  • Method Details

    • create

      static OxiaClientBuilder create(String serviceAddress)
      Create a new client builder.
      Parameters:
      serviceAddress - the address of the Oxia server
      Returns:
      the client builder instance

    • syncClient

      SyncOxiaClient syncClient() throws OxiaException
      Create a synchronous client.

      This method is blocking while the client initializes and talks to the server.

      Returns:
      the synchronous client instance
      Throws:
      OxiaException - if failed to create the client

    • asyncClient

      CompletableFuture<AsyncOxiaClient> asyncClient()
      Create an asynchronous client.
      Returns:
      a future to retrieve the client instance, when ready

    • requestTimeout

      OxiaClientBuilder requestTimeout(Duration requestTimeout)
      Specify a custom timeout for all requests.

      Default is 30 secs.

      Parameters:
      requestTimeout - the timeout duration
      Returns:
      the builder instance

    • batchLinger

      @Deprecated(since="0.9.0", forRemoval=true) OxiaClientBuilder batchLinger(Duration batchLinger)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Batching is adaptive: operations are grouped while a batch is in progress and a batch is flushed as soon as no more operations are pending, so this setting has no effect.
      Specify the maximum time to wait for a batch to be sent.
      Parameters:
      batchLinger - the batch linger duration
      Returns:
      the builder instance

    • maxRequestsPerBatch

      OxiaClientBuilder maxRequestsPerBatch(int maxRequestsPerBatch)
      Specify the maximum number of requests to include in a batch.

      Default is 1000.

      Parameters:
      maxRequestsPerBatch - the maximum number of requests per batch
      Returns:
      the builder instance

    • maxPendingBytes

      OxiaClientBuilder maxPendingBytes(long maxPendingBytes)
      Specify the maximum total size of the operations that the client has accepted and not yet completed. When the limit is reached, further operations block the calling thread until enough pending operations complete, providing backpressure to the application.

      Default is 256 MiB. A value of 0 disables the limit.

      Parameters:
      maxPendingBytes - the maximum total size of pending operations, or 0 to disable
      Returns:
      the builder instance

    • batchingThreads

      OxiaClientBuilder batchingThreads(int batchingThreads)
      Specify the number of threads dedicated to assembling operation batches, shared by all the shards.

      Default is 1.

      Parameters:
      batchingThreads - the number of batching threads
      Returns:
      the builder instance

    • namespace

      OxiaClientBuilder namespace(String namespace)
      Specify the Oxia namesace to use for this client instance.

      Default is "default".

      Parameters:
      namespace - the namespace to use
      Returns:
      the builder instance

    • sessionTimeout

      OxiaClientBuilder sessionTimeout(Duration sessionTimeout)
      Specify the session timeout for this client instance.

      Default is 15 secs.

      Parameters:
      sessionTimeout - the session timeout duration
      Returns:
      the builder instance
      See Also:

    • clientIdentifier

      OxiaClientBuilder clientIdentifier(String clientIdentifier)
      Specify the client identifier for this client instance.

      Default is a random UUID.

      Parameters:
      clientIdentifier - the client identifier
      Returns:
      the builder instance
      See Also:

    • clientIdentifier

      OxiaClientBuilder clientIdentifier(Supplier<String> clientIdentifier)
      Specify the client identifier for this client instance.

      Default is a random UUID.

      Parameters:
      clientIdentifier - the client identifier supplier
      Returns:
      the builder instance
      See Also:

    • openTelemetry

      OxiaClientBuilder openTelemetry(OpenTelemetry openTelemetry)
      Specify the OpenTelemetry instance to use for this client instance.

      By default, the client will use the global OpenTelemetry instance if available.

      Parameters:
      openTelemetry - an OpenTelemetry instance
      Returns:
      the builder instance

    • authentication

      OxiaClientBuilder authentication(Authentication authentication)
      Configure the authentication plugin and its parameters.
      Parameters:
      authentication - the authentication instance
      Returns:
      the builder instance

    • connectionBackoff

      OxiaClientBuilder connectionBackoff(Duration minDelay, Duration maxDelay)
      Configure the connection backoff policy.

      Defaults are min=100millis, max=30sec.

      Parameters:
      minDelay - the minimum delay between retries
      maxDelay - the maximum delay between retries
      Returns:
      the builder instance

    • maxConnectionPerNode

      OxiaClientBuilder maxConnectionPerNode(int connections)
      Configure the maximum number of connections to each Oxia server node.

      Default is 1.

      Parameters:
      connections - the maximum number of connections
      Returns:
      the builder instance

    • connectionKeepAliveTimeout

      OxiaClientBuilder connectionKeepAliveTimeout(Duration connectionKeepAliveTimeout)
      Configure the keep alive timeout for the connection.

      Default is 3 sec.

      Parameters:
      connectionKeepAliveTimeout - the keep alive timeout duration
      Returns:
      the builder instance

    • connectionKeepAliveTime

      OxiaClientBuilder connectionKeepAliveTime(Duration connectionKeepAlive)
      Configure the keep alive interval for the connection.

      Default is 10 sec.

      Parameters:
      connectionKeepAlive - the keep alive interval duration
      Returns:
      the builder instance

    • authentication

      OxiaClientBuilder authentication(String authPluginClassName, String authParamsString) throws UnsupportedAuthenticationException
      Configure the authentication plugin and its parameters.
      Parameters:
      authPluginClassName - the class name of the authentication plugin
      authParamsString - the parameters of the authentication plugin
      Returns:
      the OxiaClientBuilder instance
      Throws:
      UnsupportedAuthenticationException - if the authentication plugin is not supported

    • enableTls

      OxiaClientBuilder enableTls(boolean enableTls)
      Configures whether to enable TLS (Transport Layer Security) for the client connection.
      Parameters:
      enableTls - true to enable TLS, false to disable it
      Returns:
      the builder instance for method chaining

    • loadConfig

      OxiaClientBuilder loadConfig(String configPath)
      Load the configuration from the specified configuration file.
      Parameters:
      configPath - the path of the configuration file
      Returns:
      the OxiaClientBuilder instance

    • loadConfig

      OxiaClientBuilder loadConfig(File configFile)
      Load the configuration from the specified configuration file.
      Parameters:
      configFile - the configuration file
      Returns:
      the OxiaClientBuilder instance

    • loadConfig

      OxiaClientBuilder loadConfig(Properties properties)
      Load the configuration from the specified properties.
      Parameters:
      properties - the properties
      Returns:
      the OxiaClientBuilder instance