Package io.oxia.client.api

package io.oxia.client.api
The public API for interacting with Oxia.

Getting started

Every client is created through OxiaClientBuilder. The builder lets you produce either a blocking or non-blocking client; both speak to the same Oxia cluster and expose the same operations. Pick whichever fits your code style — if in doubt, start with the synchronous one.

Synchronous client


 try (SyncOxiaClient client = OxiaClientBuilder.create("localhost:6648")
         .namespace("my-namespace")
         .syncClient()) {

     PutResult put = client.put("my-key", "my-value".getBytes(StandardCharsets.UTF_8));

     GetResult got = client.get("my-key");
     if (got != null) {
         String value = new String(got.value(), StandardCharsets.UTF_8);
     }

     boolean wasPresent = client.delete("my-key");
 }

Asynchronous client


 AsyncOxiaClient client = OxiaClientBuilder.create("localhost:6648")
         .namespace("my-namespace")
         .asyncClient()
         .join();

 client.put("my-key", "my-value".getBytes(StandardCharsets.UTF_8))
         .thenCompose(put -> client.get("my-key"))
         .thenAccept(got -> System.out.println(new String(got.value(), StandardCharsets.UTF_8)));

Conditional puts and optimistic concurrency

Operations can be made conditional by passing options. Conditional writes that fail produce an UnexpectedVersionIdException. 


 // Only insert if the key does not already exist.
 client.put("my-key", value, Set.of(PutOption.IfRecordDoesNotExist));

 // Read-modify-write with version check.
 GetResult current = client.get("my-key");
 client.put("my-key", newValue, Set.of(PutOption.IfVersionIdEquals(current.version().versionId())));

Listing and scanning ranges


 List<String> keys = client.list("a", "z");

 try (CloseableIterable<GetResult> scan = client.rangeScan("a", "z")) {
     for (GetResult r : scan) {
         // process r
     }
 }

Watching for changes


 client.notifications(n -> {
     switch (n) {
         case Notification.KeyCreated c  -> { /* ... *\/ }
         case Notification.KeyModified m -> { /* ... *\/ }
         case Notification.KeyDeleted d  -> { /* ... *\/ }
         case Notification.KeyRangeDelete r -> { /* ... *\/ }
     }
 });

Package layout

See Also: