pipelogiqJava SDK reference
Artifacts, typed APIs, resource ownership, async behavior, failure boundaries and Java/.NET interoperability.
Version and distribution status
These pages describe Java SDK 0.5.0, targeting Java 17 bytecode and verified on JDK 17 and 21. Maven coordinates use com.pipelogiq; Java imports use io.pipelogiq.sdk.
The matching source archive and local installation instructions make examples reproducible without assuming this release is already available from Maven Central. Local mvn install does not publish packages publicly.
Choose only the modules you need
Start with com.pipelogiq:pipelogiq-sdk:0.5.0. Add optional integrations as needed, or use the Spring starter as the application entry dependency.
Artifact in com.pipelogiq | Purpose |
|---|---|
pipelogiq-sdk | YAML configuration, worker lifecycle, typed client, HTTP and AMQP |
pipelogiq-sdk-core | Handler contracts, typed and low-level clients, builders |
pipelogiq-sdk-http | HTTP transport for custom runtimes |
pipelogiq-sdk-amqp | AMQP transport for custom runtimes |
pipelogiq-sdk-spring-boot-starter | Spring Boot 3 configuration, stage discovery and lifecycle |
pipelogiq-sdk-agent | Agent runtime, providers, tools, approval and notification adapters |
pipelogiq-sdk-testing | Deterministic agent scenarios using production handlers |
pipelogiq-sdk-redis | Redis session and memory stores |
pipelogiq-sdk-postgres | PostgreSQL session and memory stores |
pipelogiq-sdk-observability | Optional OpenTelemetry bridge and agent metrics |
All artifacts use version 0.5.0. In the source tree, the recommended pipelogiq-sdk artifact is built by sdk-runtime. The parent POM supplies dependency management and build metadata; it is not an application runtime dependency.
Application and worker configuration
See the complete configuration table.
| API | Use |
|---|---|
Pipelogiq.worker().config(...).stages(...).run() | Separate, continuously running worker service with SDK-owned lifecycle |
Pipelogiq.connect(...) | Producer client used by a separate API, job or CLI process |
StageHandler<T> / NoInputStageHandler | Business stages with typed or absent input |
@Stage("name") | Stable producer/worker wire identity |
context.require(key, type) | Required data with structured failure classification |
context.pipelogiq() | Borrow the worker's shared typed client |
Typed operations
| Entry point | Operations |
|---|---|
client.pipeline(name) | Typed stages, labels, context and idempotency; send / sendAsync |
client.pipelines() | Get, get by idempotency key, cancel, append, wait for completion |
client.stages() | Approve or reject a waiting stage |
client.schedule(name) | Cron, interval or one-time definition; apply / applyAsync |
client.schedules() | Get, list, history, pause, resume, archive and trigger |
client.event(name, handler) | Pipeline containing a no-input event |
client.log(level, message) | Application log with optional labels |
Management operations provide named synchronous and asynchronous methods. Responses expose IDs, enums, stage lists, typed context and schedule pagination. statusName() preserves the server status string, including values unknown to this SDK. raw() returns a defensive copy of additive fields for advanced integrations; ordinary workflow code does not need JSON traversal.
StageRef<T> lets a producer share a wire name and input type without referencing worker implementation classes. StageDefinition and PipelineDefinition represent definitions rather than live executions.
API requests, futures and resource ownership
| Resource | Owner and closing rule |
|---|---|
Client from Pipelogiq.connect(...) | Application; create once for its useful lifetime and close on shutdown |
Worker from run() | SDK entry point and its JVM shutdown hook |
Client from context.pipelogiq() | Worker; borrowed by stage code and never closed by the handler |
Draft from pipeline(...) / schedule(...) | No separate connection; no closing required |
new PipelogiqClient(options) | Owns its low-level API client |
new PipelogiqClient(existingApiClient) | Borrows that API client; does not close it |
| Spring client and worker beans | Spring application context |
Async operations return CompletableFuture. Cancelling an SDK future stops the local operation/request or completion wait. It does not cancel a pipeline already created on the server. Call client.pipelines().cancel(id) for durable cancellation.
waitForCompletion requires a timeout and accepts an optional polling interval. It returns a terminal response or fails with the underlying API/contract error; an expired observation window raises PipelineWaitTimeoutException. Closing the client cancels its outstanding local completion waits. A terminal response can be FAILED or CANCELLED, so check its status.
Existing PipelogiqApiClient JSON methods, PipelineBuilder, ScheduleBuilder and transport runners remain available. These integration-level APIs need not appear in a basic worker or producer.
WorkerHandle, start() and build() support framework adapters and SDK integration tests. The Spring starter uses that lifecycle internally. Application workers should use run() or the Spring starter and remain separate from producer processes.
API errors and uncertain writes
If a connection drops after a create request reaches the server, the caller may not know whether the pipeline was created. Set a stable pipeline idempotency key and use getByIdempotencyKey(...) to reconcile, or repeat creation with the same key and intended definition.
Do not generate a new key on every retry of the same business request. Use a new key for a deliberately new execution. External effects inside a stage need their own idempotency mechanism; pipeline creation does not make a payment or database write exactly once.
Use helpers such as validationError, businessRejected, upstreamError or rateLimitExceeded for expected stage failures. See workflow retry examples.
Schedules and execution policy
Schedules run on the server. Java supports five-field cron with an IANA time zone, whole-second intervals of at least 10 seconds, and one-time execution at an instant. Typed enums select overlap and catch-up policies. Pause, resume, manual trigger, archive and history are separate operations.
Java does not run an in-process scheduler to keep definitions alive. Workers still need to be available when scheduled work is dispatched.
Java and .NET interoperability
Java and .NET workers can consume the same server contracts when handler names, input schemas and context data agree. @Stage and shared StageRef contracts make names explicit. Java uses records/POJOs and Jackson conversion; .NET uses its own type and serialization conventions. Avoid treating runtime-specific class names as a portable business schema.
Public APIs use labels for classification and context for execution data. There are no keyword or withKeyword aliases. Historical protocol field names can still contain pipelineKeywords; this preserves server compatibility without introducing a second public concept.
Java's CompletableFuture, cooperative interruption and Spring bean scopes differ from .NET tasks, cancellation tokens and dependency-injection scopes. The server owns durable workflow state in both SDKs. Store interoperability also requires matching key/table prefixes, retention settings and serialized content; concurrent session saves are not an atomic merge.
Verification boundaries
The source includes unit and HTTP fixture tests, transport/store integration suites, package-consumer checks and SDK Lab scenarios. Follow testing to choose the appropriate layer. A skipped integration test is not proof of a live operation.
Deterministic agent tests use scripted planners and tools. Provider/notification fixtures verify protocol behavior, not an external account's credentials or model availability. OpenTelemetry tests verify spans and metrics locally; exporters and collectors remain deployment-specific.