Skip to content

Latest commit

 

History

History
234 lines (170 loc) · 8.91 KB

README.md

File metadata and controls

234 lines (170 loc) · 8.91 KB
Raw

Oxia Java Client

A JDK based client for Oxia.

Features

  • Request batching
  • Asynchronous operation
  • Notifications callback
  • Record caching

Usage

See the included integration test for executable examples.

Get and Put

var client = new OxiaClientBuilder("localhost:6648").asyncClient().join();
var value = client.get("key").join().getValue();
// This Put is unconditional
var version = client.put("key", "hello".getBytes(), PutOptions.none()).join().getVersion();

Put — conditional on key absence

try {
  var result = client.put(
        "key", value, PutOption.IfRecordDoesNotExist
  ).join();
} catch (KeyAlreadyExistsException e) {
  ...
}

Put — conditional on version ID

try {
  var result = client.put(
    "key", value, PutOption.ifVersionIdEquals(1L)
  ).join();
} catch (UnexpectedVersionIdException e) {
  ...
}

Put — ephemeral record

var result = client.put(
  "key", value, PutOption.AsEphemeralRecord
).join();

Delete — unconditional

var deleted = client.delete("key").join();

Delete — conditional on version ID

try {
  var deleted = client.delete(
    "key", DeleteOption.ifVersionIdEquals(1L)
  ).join();
} catch (UnexpectedVersionIdException e) {
  ...
}

Delete Range

Consult the Oxia documentation for detail concerning the ordering of keys.

client.deleteRange("aStartInc", "bEndExc").join();

List Key Range

Consult the Oxia documentation for detail concerning the ordering of keys.

var keys = client.list("aStartInc", "bEndExc").join();

Subscribe to notifications

A stream of record change notifications that can be consumed.

client.notifications(
  notification -> switch (notification) {
    case KeyCreated c -> System.out.println("Created " + c.key() + ":" + c.version());
    case KeyDeleted d -> System.out.println("Deleted " + d.key());
    case KeyModified m -> System.out.println("Modified " + m.key() + ":" + m.version());
  }
);

Configuration

Option Default value Description
serviceAddress - Address of Oxia cluster — <host>:<port>
namespace default The Oxia namespace that this client should use
requestTimeout 30s GRPC Request timeout
batchLinger 5ms Max time to wait for new operations before closing batch
maxRequestsPerBatch 1,000 Max number of operations in a batch
recordCacheCapacity 10,000 Number or records that can be cached by the client
sessionTimeout 15s Period of inactivity after which session will be closed
clientIdentifier String that uniquely identifies this client instance

Metrics

The Oxia Java client collects various metrics about the operations being performed. There is an API and an OpenTelemetry implementation is provided.

There are various categories of metrics captured:

Operation Metrics

Name Description
oxia_client_operation_timer The time an operation takes to be executed from request submission to response
oxia_client_operation_size The record value size. Only applicable for put and get

Attributes

Name Description Values
type The operation type put, delete, delete_range, get, list
result The operation result success, failure

Batch Metrics

Name Description
oxia_client_batch_total_timer The time a batch takes to be completed from creation to response
oxia_client_batch_exec_timer The time a batch takes to be completed from submission to response
oxia_client_batch_size The size of all the record values in a batch
oxia_client_batch_requests The count of requests in a batch

Attributes

Name Description Values
type The operation type write, read
result The operation result success, failure

Cache Metrics

Name Description
oxia_client_cache_load_timer The time it took to load a record in to the cache
oxia_client_cache_hits Counts of cache hits and misses
oxia_client_cache_evictions Counts of record evictions from the cache

Attributes

Name Description Values Notes
type The operation type load, hit, eviction
result The operation result success, failure
removal_cause See: RemovalCause explicit, replaced, collected, expired, size Applies to type: eviction only

Session Metrics

Name Description
oxia_client_session_keepalive Status of the session keep-alive heartbeats

Attributes

Name Description Values
result The heartbeat result success, failure

Notification Metrics

Name Description
oxia_client_notification Status of the notification stream
oxia_client_notification_event Count of record change events

Attributes

oxia_client_notification_event
Name Description Values
type batch
result The stream status success, failure
oxia_client_notification
Name Description Values
type The notification type key_created, key_deleted, key_modified

Shard Assignment Metrics

Name Description
oxia_client_shard_assignment Status of the shard assignments stream
oxia_client_shard_assignment_change Count of assignment changes

Attributes

oxia_client_shard_assignment
Name Description Values
type event
result The stream status success, failure
oxia_client_shard_assignment_change
Name Description Values
type The assignment type added, removed, reassigned