v0.1.0 - Initial Release

v0.1.0 - Initial Release

The first public release of rstmdb-java, the official Java client library for rstmdb — a distributed state machine database.

Highlights

• Java 11+ compatible, built with Java 25 toolchain
• Single runtime dependency — only Jackson Databind required
• Async-first design with CompletableFuture<T> on every operation, plus blocking *Sync() variants
• Thread-safe single TCP connection with request multiplexing

Features

State Machine Management

• Register and update state machine definitions with putMachine()
• Retrieve machine definitions and list all registered machines
• Support for states, transitions, guards, and metadata

Instance Operations

• Create, retrieve, list, and delete state machine instances
• Filter instances by machine, state, with pagination (limit/offset)
• Apply events to trigger state transitions
• Optimistic locking via expectedState and expectedWalOffset
• Idempotency keys for safe retries on creates and event applications

Batch Operations

• Execute multiple operations in a single call with batch()
• Atomic mode — all-or-nothing semantics
• Best-effort mode — independent operations that proceed on partial failure

Real-Time Subscriptions

• watchInstance() — subscribe to changes on a specific instance
• watchAll() — subscribe to all state changes with optional filters (machines, events, from/to states)
• Multiple consumption patterns: blocking poll, iterable, callback, and Flow.Publisher (reactive streams)
• Replay from offset for historical events

Write-Ahead Log (WAL)

• Read WAL records for audit and replay
• WAL statistics (entry count, segment count, size)
• Instance snapshots with checksums
• Compaction to reclaim storage

Transport & Protocol

• RCPX binary framing with JSON payloads
• CRC32C integrity checks
• TLS/SSL support with custom SSLContext
• Configurable connect and request timeouts
• Token-based authentication
• Graceful connection shutdown

Error Handling

• Structured RstmdbException with error codes and retryable flag
• Convenience methods: isNotFound(), isConflict(), isInvalidTransition(), etc.

Modules

Module	Coordinates	Description
client	com.rstmdb:rstmdb-client	Core client library
testcontainer	com.rstmdb:rstmdb-testcontainer	Testcontainers integration for rstmdb

Installation

Gradle

implementation 'com.rstmdb:rstmdb-client:0.1.0'

// For integration testing
testImplementation 'com.rstmdb:rstmdb-testcontainer:0.1.0'

Maven

<dependency>
    <groupId>com.rstmdb</groupId>
    <artifactId>rstmdb-client</artifactId>
    <version>0.1.0</version>
</dependency>

Quick Start

var client = RstmdbClient.connect("localhost", 4400);

// Register a state machine
client.putMachineSync(PutMachineRequest.builder()
    .machine("order")
    .version("1.0")
    .definition(new MachineDefinition(/* ... */))
    .build());

// Create an instance
var result = client.createInstanceSync(CreateInstanceRequest.builder()
    .machine("order")
    .version("1.0")
    .build());

// Apply an event
client.applyEventSync(ApplyEventRequest.builder()
    .instanceId(result.getInstanceId())
    .event("confirm")
    .build());

client.close();