DEV Community

Cover image for Kiponos Java SDK 5.0 What’s New — Developer Guide
Moshe Avdiel
Moshe Avdiel

Posted on • Originally published at github.com

Kiponos Java SDK 5.0 What’s New — Developer Guide

#api #java #springboot #tutorial

Kiponos Java SDK 5.0 What’s New — Developer Guide

This is the technical companion to the 5.0 milestone announcement: what changed, how modes behave, how to read config with the Folder API, and how to upgrade cleanly.
Version 5.0.0.260710
Maven group io.kiponos
Artifacts sdk-boot-3 (recommended), sdk-boot-2 (legacy)
Released 2026-07-12 (Maven Central)

Happy product story: SDK 5.0 milestone post.

1. Summary for busy engineers

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

Mode When Config reads Mutations / hooks Notes
Ready Connected to hub Live in-memory tree Full Production happy path
Offline Disconnected but LKG available Last Known Good (read-only) No-op / ignored Survives hub blips without inventing values
Safe Fail-closed Empty / null-safe No-op Diagnostic dumps must not overwrite LKG

Public entry remains:

Kiponos kiponos = Kiponos.createForCurrentTeam();
Enter fullscreen mode Exit fullscreen mode

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

kiponos.getCurrentMode();
kiponos.isReadyMode();
kiponos.isOfflineMode();
kiponos.isSafeMode();
Enter fullscreen mode Exit fullscreen mode

2. Install

Gradle — Boot 3 

repositories { mavenCentral() }

dependencies {
    implementation 'io.kiponos:sdk-boot-3:5.0.0.260710'
}
Enter fullscreen mode Exit fullscreen mode

Gradle — Boot 2 

implementation 'io.kiponos:sdk-boot-2:5.0.0.260710'
Enter fullscreen mode Exit fullscreen mode

Runtime inputs

Input Mechanism
Identity env KIPONOS_ID
Access env KIPONOS_ACCESS
Profile / tree slice JVM -Dkiponos="['App']['1.0.0']['dev']['base']"

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).

3. 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
Enter fullscreen mode Exit fullscreen mode

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.

4. Folder API (the surface you code against)

Root:

KiponosFolder root = kiponos.getRootFolder();
Enter fullscreen mode Exit fullscreen mode

Navigation 

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

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)
Enter fullscreen mode Exit fullscreen mode

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");
Enter fullscreen mode Exit fullscreen mode

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

Writes (Ready mode) 

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

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

5. 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)

Event Behavior
Live tree healthy Ready serves live data; LKG can be refreshed from good state
Disconnect / unreachable Prefer Offline with LKG reads
No trustworthy backup Safe fail-closed
Safe diagnostic dump Writes safe-dump-* style artifacts — never overwrites LKG

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”

6. Lifecycle 

Kiponos kiponos = Kiponos.createForCurrentTeam();
try {
    // work
} finally {
    kiponos.disconnect();
}
Enter fullscreen mode Exit fullscreen mode

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).

7. Upgrade from 4.4.x

Step Action
1 Change dependency version to 5.0.0.260710
2 Rebuild / run tests against staging hub
3 Replace parseInt(get(...)) with getInt where applicable
4 Re-test disconnect / reconnect paths (unit + one live smoke)
5 Optional: surface getCurrentMode() in health/admin endpoints
6 Confirm no code assumed “throw and hang” as the only offline strategy

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

8. 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();
    }
}
Enter fullscreen mode Exit fullscreen mode

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

9. 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
Enter fullscreen mode Exit fullscreen mode

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

10. Known follow-ups (honest roadmap)

These are not blockers for adopting 5.0:

Item Notes
Mode-change hooks e.g. onRecovered, onSwitchToSafeMode for app callbacks
Safe → Ready recovery polish Explicit policy after fail-closed recovery
Full live multi-mode matrix in CI Broader than unit Offline/Safe matrix
Boot2 modes parity Boot3 is the recommended surface

11. 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

12. Further reading

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.

Top comments (0)