Skip to content

Java SDK

The SLIM Java SDK (io.agntcy.slim:slim-bindings-java) provides an idiomatic Java API for building applications on SLIM. Bindings are generated from the same Rust core as every other language binding via uniffi-bindgen-java, with synchronous methods and CompletableFuture-based async variants, and native libraries loaded through JNA.

Requirements
Runtime Java 21 or higher
Package slim-bindings-java on Maven Central
Build tools Maven 3.8+
Examples java/examples in slim-bindings

The Maven artifact bundles native libraries for Linux, macOS, and Windows on x64 and arm64. JNA loads the correct library for your platform at runtime.

Installation

Add to your pom.xml:

<dependency>
  <groupId>io.agntcy.slim</groupId>
  <artifactId>slim-bindings-java</artifactId>
  <version>1.2.0</version>
</dependency>

dependencies {
    implementation("io.agntcy.slim:slim-bindings-java:1.2.0")
}

Getting Started

The SDK tutorials build a full application step by step — initialising the service, connecting to a node, creating an app, opening sessions, receiving messages, and adding persistence — with Java snippets shown alongside every other binding.

Start with Connecting to SLIM.

API Overview

Class Description
SlimBindings Static entry point for initialisation and global service access
Service Manages connections and creates apps
App Application handle for sessions, subscriptions, and routing
Session Session for sending and receiving messages
Name Identity in org/namespace/app format
ReceivedMessage Received message with payload() (bytes) and context metadata
SessionConfig Session configuration (type, MLS, retries)
ClientConfig Client connection configuration (endpoint, TLS, transport auth)
ServerConfig Server listen configuration (endpoint, TLS, transport auth)
OidcConfig OIDC transport authentication settings
OidcPolicyConfig Claim-based access policy (Cel, Rego, RegoFile)

Async variants (*Async) returning CompletableFuture are available for all operations. With Java 21 virtual threads, blocking on .get() or .join() is inexpensive.

Session Configuration

SessionConfig sessionConfig = new SessionConfig(
        SessionType.POINT_TO_POINT,
        null,        // maxRetries — null uses the SLIM default
        null,        // interval — null uses the SLIM default
        Map.of(),    // metadata
        new MlsSettings(100, null));

Session session = app.createSessionAndWait(sessionConfig, remoteName);

The constructor is positional and takes all five fields. MlsSettings takes the header-integrity validation percentage and an optional replay-protection cache size; passing null in its place disables MLS.

Transport Authentication

Separate from the app identity passed to createAppWithSecret, the gRPC connection to a SLIM node can carry its own credentials via ClientConfig.setAuth.

OIDC (client credentials)

ClientConfig config = SlimBindings.newInsecureClientConfig("http://127.0.0.1:46357");
config.setAuth(new ClientAuthenticationConfig.Oidc(new OidcConfig(
    "https://auth.example.com",  // issuerUrl
    "my-client",                 // clientId
    "s3cr3t",                    // clientSecret
    null, null, null, null,      // audience, refreshToken, refreshTokenFile, accessTokenFile
    "openid profile",            // scope
    Duration.ofSeconds(30),        // timeout
    null, null, null)));          // jwksTtl, claimCacheTtl, policy

Long connId = service.connect(config);

For the refresh-token flow, set refreshToken (or refreshTokenFile, which is rewritten in place as tokens rotate) instead of clientSecret.

OIDC (server verification)

ServerConfig config = SlimBindings.newInsecureServerConfig("127.0.0.1:46357");
config.setAuth(new ServerAuthenticationConfig.Oidc(new OidcConfig(
    "https://auth.example.com",
    null, null,
    "slim",                      // audience — required for verification
    null, null, null, null, null,
    Duration.ofHours(1),         // jwksTtl
    Duration.ofMinutes(1),       // claimCacheTtl
    new OidcPolicyConfig.Cel("\"admin\" in claims.groups"))));

service.runServerAsync(config).get();

policy accepts OidcPolicyConfig.Cel, OidcPolicyConfig.Rego (which must define package slim.auth with default allow = false), or OidcPolicyConfig.RegoFile.

JSON configuration

SlimBindings.newConfigFromJson accepts a full gRPC client config covering TLS material, backoff, and every authentication mode:

{
  "endpoint": "http://127.0.0.1:46357",
  "tls": { "insecure": true },
  "auth": {
    "type": "oidc",
    "issuer_url": "https://auth.example.com",
    "client_id": "my-client",
    "client_secret": "s3cr3t",
    "audience": "slim",
    "policy": { "cel": "\"admin\" in claims.groups" }
  }
}

The schema matches the client configuration schema in the slim repository.

SLIMRPC

The Java SDK includes SLIMRPC support for Protobuf-based RPC over SLIM. Install the protoc-gen-slimrpc-java plugin and add it to your buf.gen.yaml alongside the standard Java protobuf plugin. See the SLIMRPC Compiler and the Serving and Client tutorials.

Generated code lives in the io.agntcy.slim.bindings.slimrpc package.

Examples

The slim-bindings/java directory includes complete working examples:

Example Description
PointToPoint 1:1 messaging with request/reply
Group Group sessions with moderator/participant roles
Server SLIM data plane server
examples/slimrpc/simple Protobuf RPC over SLIM

Point-to-point:

cd java
task examples:p2p:alice   # Receiver
task examples:p2p:bob     # Sender (in another terminal)

SLIMRPC (requires a running SLIM node and generated proto code):

task examples:rpc:server
task examples:rpc:client

Platform Support

Platform Architecture JNA directory
Linux x86_64 linux-x86-64
Linux aarch64 linux-aarch64
macOS x86_64 darwin-x86-64
macOS aarch64 darwin-aarch64
Windows x86_64 win32-x86-64
Windows aarch64 win32-aarch64

Building from Source

To build the Java SDK from the slim-bindings repository:

git clone https://github.com/agntcy/slim-bindings
cd slim-bindings/java

task generate   # regenerate Java bindings from Rust artifacts
task build
task install    # install to local Maven repository

See the java README for the full list of development tasks.

Next Steps