Use the Java SDK

Applies to: current development source bundles. Obtain a matched client/server release through early-access support; registry publication is not available yet. Paths below are relative to the supplied source checkout.

Blocking Java 21+ client using the shared C transport through JNI. Works from Java and other JVM languages. Initial source release; not published to Maven Central.

Build

Install the C SDK dependencies, then:

make -C java-smkv JAVA_HOME=/path/to/jdk-21

This produces build/smkv-client.jar, libsmkv_jni, and libsmkv. Use the jar on the classpath and keep both native libraries in the same directory. Pass -Djava.library.path=/absolute/path/to/java-smkv/build when starting Java. OpenSSL and json-c must also be installed. Build native libraries for the target OS/architecture; Windows has not been qualified. pom.xml builds only the Java jar.

Usage

import com.simplemagic.smkv.*;
import java.nio.charset.StandardCharsets;
import java.util.Map;

try (var client = new Client("127.0.0.1:7379")) {
    byte[] key = "42".getBytes(StandardCharsets.UTF_8);
    client.put(key, new byte[]{0, 1}, new WriteOptions(60000L, true, false, false));
    byte[] value = client.get(key);
    var users = client.table("users");
    users.put(key, Map.of("name", "Ada", "visits", 1L), WriteOptions.DEFAULT);
    System.out.println(users.get(key));
}

Keys/raw values are byte arrays. Columns accept byte[], String, Boolean, signed integral wrappers, and Double. Reads preserve int64 as Long and float64 as Double. Table get supports projection and explicit replica reads; update accepts columns to set and a list to remove, atomically. WriteOptions exposes TTL and acknowledgment flags. Null TTL means no expiry on put and preserves expiry on update; zero expires immediately. Delete rejects a non-null TTL.

Cluster and security

Client.cluster(List.of("host:7381")) accepts management seeds. get(key, true) explicitly allows stale replica reads. Discovery occurs on the first request.

For advanced configuration, pass Map<String,Object> using the C configuration schema. Data security and management_security are separate maps; ca is a PEM path, name/token provide bearer authentication. Omit either feature when not needed. TLS always verifies CA and hostname/IP; there is no insecure mode or fallback.

Lifecycle, errors, and release scope

Use try-with-resources. Client methods are thread-safe; a client serializes requests on one connection. Use a bounded number of clients for concurrency. close() interrupts active I/O, waits for callers to exit, and releases native resources. There is no finalizer; explicitly close every client.

SmkvException.code() returns the server/client code and outcomeUnknown() indicates that a mutation may have completed. Only explicit WrongOwner is automatically retried. The default deadline is five seconds including lock wait and discovery; native DNS may exceed it. Configure timeout_ms to change it. Default limits: 1 KiB keys and 1 MiB values, adjustable to match the server. Native/library-loading errors remain normal JVM exceptions.

No async API, scans, batch operations, Windows support, or load qualification yet. See native transport limits and qualification.

Build/run examples/Basic.java with the generated jar on the classpath and the native directory in java.library.path. make test-client builds the qualification entry point; it does not publish the jar or start any server.