Java SDK Lifecycle

Plugin callbacks and results

The generated Main selects SourceProgram, SinkProgram or SourceAndSinkProgram, calls run, then awaitShutdown. Keep the generated factory registration under META-INF/services. Tenon launches the packaged program and provides its configuration.

Interface	Methods to implement
TenonSource	start(), quiesce(), close()
TenonSink<P>	start(), write(FlowChannel, List<P>), close()
TenonSourceAndSink<P>	All four methods on one shared object; P is the Sink payload type

The SDK calls the factory and start once. Lifecycle methods must return promptly and must not throw. Use them to signal your clients or workers; do not wait for network acknowledgements or worker termination. Quiesce stops Source production while pending Source results and any Sink interface remain available. close is not guaranteed after a crash, fatal error or forced termination.

A Source factory receives the configuration, effective channel count and a PayloadSender<P>. Call send(channelId, payload) with a zero-based index below that count and observe the returned CompletionStage<AckCode>:

• OK: the Flow's delivery boundary was reached; apply your upstream acknowledgement policy.
• RETRY: the record did not complete; decide whether and how to replay it.
• BACKPRESSURE: the channel has no free pending slot; slow production and retry later.
• ERROR: handle a record failure, such as an oversized payload.

An invalid channel throws IllegalArgumentException. A closed session completes unfinished sends exceptionally with SourceSessionClosedException. The SDK does not resend automatically. Keep synchronous completion callbacks short; use an explicit executor for asynchronous or blocking work.

Sink write receives a nonempty, ordered, immutable batch and returns CompletionStage<Void>. Calls do not overlap, but returned stages can finish out of order. Return promptly and complete the stage successfully only when every record reaches your downstream delivery guarantee. A failed stage terminates the plugin; a restart can replay unacknowledged batches, including partial external effects. Plan for duplicates.

Direction bindings

A combined Program may run as Source only, Sink only, or both. Its factory receives Optional<Ingress<S>> source and the actual Set<FlowChannel> egressChannels. Ingress<S> contains the Source channel count and its PayloadSender<S>; an empty optional means Source is not bound. An empty channel set means Sink is not bound. The SDK opens queues and runs workers only for bound directions. FlowChannel contains only flowId and channelId; Bell paths remain inside the SDK. Existing combined plugins must adapt their factory and rebuild against this SDK.