Java API Reference

The Java SDK (io.twilic:twilic) provides Dynamic, Bound, Batch, and Stateful encoding via JNI bindings to the Rust core.

Installation

<dependency>
  <groupId>io.twilic</groupId>
  <artifactId>twilic</artifactId>
  <version>0.1.0</version>
</dependency>

Requires Java 17+ and a platform-native library bundled with the JAR.

Quick start

import io.twilic.Twilic;
import io.twilic.internal.core.MapEntry;
import io.twilic.internal.core.Value;

Value value = Twilic.newMap(
    Twilic.entry("id", Twilic.newU64(1001)),
    Twilic.entry("name", Twilic.newString("alice"))
);

byte[] encoded = Twilic.encode(value);
Value decoded = Twilic.decode(encoded);

Core functions

Function	Description
Twilic.encode(Value)	Dynamic profile encode
Twilic.decode(byte[])	Dynamic profile decode
Twilic.encodeWithSchema(Schema, Value)	Bound profile encode
Twilic.encodeBatch(List<Value>)	Row batch encode
Twilic.newSessionEncoder()	Create stateful session encoder

Value constructors

Function	Type
newNull()	null
newBool(boolean)	boolean
newI64(long)	signed integer
newU64(long)	unsigned integer
newF64(double)	float
newString(String)	string
newBinary(byte[])	binary
newArray(List<Value>)	array
newMap(MapEntry...)	map
entry(String, Value)	map entry helper
equal(Value, Value)	deep equality

Session encoder

import io.twilic.Twilic;
import io.twilic.internal.core.SessionEncoder;
import io.twilic.internal.core.Value;

SessionEncoder enc = Twilic.newSessionEncoder();

byte[] full = enc.encode(currentState);
byte[] patch = enc.encodePatch(updatedState);
Value decoded = enc.decode(incomingFrame);

enc.reset(); // after disconnect — next encode is full frame

Session options

Configure via SessionEncoder constructor or options object (see SDK source for UnknownReferencePolicy).

Schema (Bound profile)

import io.twilic.internal.core.Schema;
import io.twilic.internal.core.SchemaField;

Schema schema = new Schema(
    1L,                          // schema_id
    "UserRecordV1",              // name
    List.of(
        new SchemaField(1, "id", "u64", true, null),
        new SchemaField(2, "name", "string", true, null)
    )
);

byte[] encoded = Twilic.encodeWithSchema(schema, value);

Key and base references

For advanced patch construction:

Twilic.keyRefLiteral("fieldName");
Twilic.keyRefID(42L);
Twilic.baseRefPrevious();
Twilic.baseRefID(7L);

Error handling

Decode failures throw TwilicException with error kind matching the wire spec:

Kind	Meaning
UnexpectedEof	Truncated payload
InvalidKind / InvalidTag	Corrupt wire data
UnknownReference	Missing session base
StatelessRetryRequired	Policy triggered — request full frame

Interop

Java encodes payloads readable by all other official SDKs. Run cross-language tests:

cd twilic-java
./gradlew test

Related

• Value & Schema
• Session Encoder
• Interop guide
• Java SDK overview