ZLink Framework for Kotlin -- Documentation¶
This set is the ZLink Framework documentation for
Kotlin(Spring Boot) users.zlink-framework-kotlinis a thin coroutine-idiom layer that reuses the Javazlink-frameworkruntime as-is. The Java surface follows the Java spec, and the Kotlin-specific public contract is fixed in the Kotlin spec. Internal criteria are shared with the Java/Kotlin documentation. The Kotlin usage guide will be rewritten as Kotlin-specific once the 11.0 public interface and samples are finalized. Common meaning follows the common spec.
The common meaning of async execution, CompletionStage, and the Kotlin coroutine wrapper
follows the Async Execution And Coroutine Policy.
Sample and E2E config files, the ban on environment variables, and
@ConfigurationProperties-binding criteria follow the
Sample/E2E Configuration Policy.
Coroutine usage for the client libraries used separately from the server framework is found in the HTTP client guide and the Stream connector guide.
0. The Kotlin Surface At A Glance¶
zlink-framework-kotlin doesn't create a new transport. It only adds a coroutine surface
on top of the same channel/Spot/actor/stream the Java framework exposes.
| Java surface | Kotlin surface |
|---|---|
ZLinkRequestHandler<T, R> (returns plain TReply) |
ZLinkSuspendingRequestHandler<T, R> (suspend fun handle) |
ZLinkSendHandler / ZLinkFanoutHandler |
ZLinkSuspendingSendHandler / ZLinkSuspendingPublishHandler |
ZLinkSpot<TActor> / ZLinkEntrySpot<TActor> |
ZLinkSuspendingSpot<TActor> / ZLinkSuspendingEntrySpot<TActor> (handles actor admission, joined, leave as suspend) |
| The Java relocation policy and opaque byte adapter | ZLinkRelocationPolicy.snapshot(Adapter::class.java) |
ZLinkSession |
ZLinkSuspendingSession (onConnectedSuspending, etc.) |
client.requestToChannel(...).submit(R::class.java) |
client.request<R>(channel, msg) / call.awaitReply<R>() |
The connector.on(name) { ... } callback |
connector.kotlin().messages(name): Flow<...> |
The exact signature of coroutine handler configuration is owned by the Kotlin interfaces.
2. Public Contract Spec¶
Kotlin adds a coroutine extension on top of the same Spring Boot runtime. Java types used
as-is follow the Java spec, and suspend, Flow, and adapter signatures newly exposed in
Kotlin follow the Kotlin spec.
| Document | Scope |
|---|---|
| Kotlin spec table of contents | The list of Kotlin-specific public-contract documents |
| Kotlin interfaces | The exact public signature for coroutines/DSL |
| Java spec table of contents | The Java public contract Kotlin uses as-is |
| Java interfaces | The canonical Java types and builders Kotlin reuses |
| Channel messaging | Channel registration, the outbound client, and dispatch |
| Spot | Spot lifecycle and factory |
| Actor | The actor factory, relocation adapter, and bound session |
| STREAM | The stream node and header session |
| stream-connector | The Java/Kotlin Stream Connector |
| Location and maintenance | Discovery, authority, and relocation |
| Monitoring | Runtime events and typed handlers |
3. Internal Criteria -- Shared With Java/Kotlin¶
Since they use the same runtime, implementation structure, lifecycle, and regression
criteria share the Java/Kotlin internals/.
| Document | Scope |
|---|---|
| backend-dependency-policy | Java binding dependency isolation |
| Common Internals | Runtime architecture decisions shared across all four languages |
| regression-test-matrix | JVM contract, E2E, and performance smoke criteria |
4. Samples (Kotlin)¶
The samples provide the same scenario set as Java, implemented with Kotlin coroutines. The 6 canonical ones are per-app documents; feature-axis samples are kept as separate documents.
The 6 canonical samples' server roles, message contracts, state transitions, and completion criteria are owned by the common sample. The Kotlin documents don't restate this contract.
| Document | Scope |
|---|---|
| samples README | Java/Kotlin sample structure and how to run them |