---
title: "Java SDK reference"
description: "Artifacts, typed APIs, resource ownership, async behavior, failure boundaries and Java/.NET interoperability."
category: "Java SDK"
---

## 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](/downloads/pipelogiq-java-sdk-0.5.0-source.zip) and [local installation instructions](/docs/java/getting-started#install-the-current-sdk-from-source) 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](/docs/java/configuration#supported-settings).

| API | Use |
| --- | --- |
| `Pipelogiq.worker().config(...).stages(...).run()` | Standalone blocking worker with SDK-owned lifecycle |
| `Pipelogiq.worker().config(...).stages(...).start()` | Embedded worker; returns an owned, ready `WorkerHandle` |
| `Pipelogiq.worker().config(...).stages(...).build()` | Construct a worker without connecting |
| `Pipelogiq.connect(...)` | Application-scoped typed producer client |
| `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 |
| Handle from `start()` / `build()` | Host application; close the handle |
| Client from `context.pipelogiq()` / `worker.client()` | Worker; borrowed by business code |
| 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.

## 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](/docs/java/workflows#return-failures-that-express-intent).

## Schedules and execution policy

[Schedules](/docs/java/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](/docs/java/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.