Kiponos Java SDK 5.0 What’s New - Developer Guide

Summary for busy engineers

5.0 productizes client reliability using a classic state pattern behind a stable facade:

Public entry remains:

Kiponos kiponos = Kiponos.createForCurrentTeam();

You do not receive mode instances as the API surface. Modes switch internally. Query with:

kiponos.getCurrentMode();
kiponos.isReadyMode();
kiponos.isOfflineMode();
kiponos.isSafeMode();

Install

Gradle - Boot 3

repositories {
    mavenCentral()
}
dependencies {
    implementation 'io.kiponos:sdk-boot-3:5.0.0.260710'
}

Gradle - Boot 2

implementation 'io.kiponos:sdk-boot-2:5.0.0.260710'

Runtime inputs

Tokens and profile come from the Kiponos Connect screen for your team. sdk-common is not a separate app dependency for consumers - boot jars include shared classes (fat-jar pattern).

Architecture (state pattern)

Application code
│
▼
Kiponos / KiponosBase ◄── stable facade (one reference for app lifetime)
│
▼ volatile SdkState
├── ReadyMode* → live WebSocket + full Folder ops
├── OfflineMode* → LKG reads only
└── SafeMode* → fail-closed + safe diagnostic dump

Design rule: never return Ready/Offline/Safe objects to callers. Returning a mode freezes the application on that mode forever.

Boot modules stay thin adapters (ReadyModeBoot3, connection controllers) over sdk-common cores.

Folder API (the surface you code against)

Root:

KiponosFolder root = kiponos.getRootFolder();

Navigation

KiponosFolder server = root.path("server", "http");
// or stepwise:
KiponosFolder s = root.folder("server").folder("http");

Useful members (conceptual contract):

• path(String... folders)
• folder(String folderName)
• folderOrCreate(String folderName)
• createFolder / renameFolder / deleteFolder / hasFolder
• getFolderName / getFolders
• get(String key)
• get(String key, String def)
• getInt(String key)
• set(String key, String value)
• hasKey(String keyName)

Recommended reads

// Prefer typed getters on the SDK surface
int port = kiponos.getRootFolder()
    .path("server", "http")
    .getInt("port");

String region = kiponos.getRootFolder()
    .path("deploy")
    .get("region", "eu-west-1");

Avoid Integer.parseInt(folder.get("port")) for normal integer keys - use getInt.

Writes (Ready mode)

kiponos.getRootFolder()
    .path("feature-flags")
    .set("checkout-v2", "true");

In Offline/Safe modes, mutations are intentionally no-ops (do not assume silent remote write).

Last Known Good (LKG)

Intent: When the hub is unreachable, apps should continue with a known good snapshot, not hang and not invent random defaults.

Behavior sketch (5.0)

LKG resolution conceptually prefers: live memory → backup → on-disk LKG file under the SDK dump location.

App guidance

• Treat Offline as read-only truth of last good
• Do not assume writes succeed without Ready
• Use mode queries if UI or probes must show "degraded but serving LKG"

Lifecycle

Kiponos kiponos = Kiponos.createForCurrentTeam();
try {
    // work
} finally {
    kiponos.disconnect();
}

Notes:

• Always disconnect on orderly shutdown.
• Intentional disconnect can remain in Offline rather than surprising flip back to Ready (verify against your mode transition policy).
• Reconnect recovery continues to improve (see §10 open items).

Upgrade from 4.4.x

Breaking risk: low for pure read apps. Behavioral change is improved offline safety; re-validate anything that depended on exceptions during disconnect.

Example: Spring-friendly service skeleton

import io.kiponos.sdk.Kiponos;
import io.kiponos.sdk.configs.KiponosFolder;
import org.springframework.stereotype.Component;
import javax.annotation.PreDestroy; // or jakarta.annotation.PreDestroy on Boot 3

@Component
public class CheckoutLimits {
    private final Kiponos kiponos;
    private final KiponosFolder limits;

    public CheckoutLimits() {
        this.kiponos = Kiponos.createForCurrentTeam();
        this.limits = kiponos.getRootFolder().path("checkout", "limits");
    }

    public int maxCartItems() {
        return limits.getInt("max-cart-items");
    }

    public String currency() {
        return limits.get("currency", "USD");
    }

    @PreDestroy
    public void shutdown() {
        kiponos.disconnect();
    }
}

Dashboard changes to checkout/limits/* propagate live while Ready; Offline continues serving LKG values.

Example config tree (dashboard)

# Illustrative tree under your profile base
checkout:
  limits:
    max-cart-items: 50
    currency: USD
    soft-hold-seconds: 120
server:
  http:
    host: api.example.com
    port: 8080
feature-flags:
  checkout-v2: "true"
  dark-launch-percent: 15

Operators edit in the Kiponos web UI; apps read via Folder navigation - no redeploy.

Known follow-ups (honest roadmap)

These are not blockers for adopting 5.0:

Verification checklist

• [ ] Dependency resolves from Maven Central
• [ ] App starts with Connect tokens + profile
• [ ] getInt / path reads match dashboard
• [ ] Dashboard edit appears without restart (Ready)
• [ ] Disconnect does not hang process (Offline or Safe)
• [ ] disconnect() on shutdown
• [ ] Optional: game demo on SDK 5.0 for stakeholder demo

Live demo: Kiponos Game Samples hub: kiponos-io/kiponos-io

Further reading

• Developer Quickstart: GETTING-STARTED.md
• Product tour: Maven io.kiponos:sdk-boot-3
• Milestone announcement: devto-sdk-5-state-pattern.md

Bottom line for engineers: bump to 5.0.0.260710, keep using getRootFolder().path(...).getInt(...), and treat modes + LKG as the supported reliability model - not an optional cache you reinvent.