Java SDK reference

The Java SDK targets Java 17 and uses explicit constructors, factories, records and CompletableFuture. It does not require Spring or a .NET runtime. Start with the HTTP tutorial, then use this page to choose modules and configure an application.

Version and distribution status

The current source version is 0.5.0. The Maven group is com.pipelogiq; Java packages remain io.pipelogiq.sdk.*. Earlier local builds used the Maven group io.pipelogiq. Update dependency coordinates and reinstall the current source when moving from those builds; imports do not change.

Maven Central publication is being prepared. Until a published version is confirmed, the installation path is a local build from the Java SDK checkout:

./mvnw -pl sdk-http,sdk-amqp,sdk-agent,sdk-redis,sdk-postgres,sdk-testing -am install -DskipTests

This installs all seven libraries and their parent POM into the local Maven repository. It does not upload packages. Use the wrapper with JDK 17 or newer and JAVA_HOME configured; its Maven distribution is pinned to 3.9.16. Avoid running concurrent Maven builds against the same checkout's target directories.

Choose only the modules you need

All coordinates below use group com.pipelogiq and current local version 0.5.0.

An agent worker needs an agent module plus a transport module. Adding a store does not select a worker transport. Examples and integration-test modules are development projects, not consumer SDK libraries.

A Gradle application can consume the source-installed artifacts:

repositories {
    mavenLocal()
    mavenCentral()
}

dependencies {
    implementation("com.pipelogiq:pipelogiq-sdk-http:0.5.0")
}

Here mavenLocal() resolves Pipelogiq; mavenCentral() resolves third-party dependencies. This configuration is not a claim that Pipelogiq is already published to Central. Configure a Java 17 or newer toolchain in your application's existing build.

Application and worker configuration

Create a separate immutable PipelogiqOptions for each application. There is no process-global API-key override. An application key is required even when an SDK module is installed successfully.

Bootstrap supplies server-owned application/session, queue and broker configuration. A worker name is not a security boundary or an independent routing namespace. Applications that register identical handler names can have multiple competing workers.

StageOptions.timeout(Duration) configures a stage execution deadline. It is distinct from apiTimeout, which controls SDK API requests, and from a timeout on a downstream service call inside your handler. Durations accepted by stage retry/timeout settings are whole seconds; the builder validates their range.

API requests, futures and resource ownership

PipelogiqApiClient returns Jackson JsonNode values so callers can inspect additive server fields. Pipeline creation returns the pipeline, including id; idempotent creation also normalizes wasExisting. Use getPipeline(id) to observe a run. getPipelineByIdempotencyKey(key) retrieves a known logical submission.

PipelineBuilder.sendAsync() and ScheduleBuilder.applyAsync() return CompletableFuture<JsonNode>. The client also has general requestAsync methods for relative API paths. Named convenience methods are not all paired with asynchronous versions. Handlers still implement synchronous StageResult execute(T input, StageContext context); stores are also synchronous.

A builder created with PipelogiqOptions owns its API client and should be closed. A builder created with an existing PipelogiqApiClient does not close that client. Keep resources alive until a future completes:

package example;

import io.pipelogiq.sdk.core.api.PipelogiqApiClient;
import io.pipelogiq.sdk.core.builders.PipelineBuilder;
import java.math.BigDecimal;
import java.util.UUID;

public final class AsyncSubmit {
  public static void main(String[] args) {
    var options = OrdersApp.options("async-order-client");
    try (var api = new PipelogiqApiClient(options);
         var pipeline = PipelineBuilder.create("Asynchronous order submission", api)
             .withIdempotencyKey("async-order:" + UUID.randomUUID())
             .withAction("Validate", "ValidateOrder",
                 new OrdersApp.Order("async-demo", new BigDecimal("12.50")))) {
      var submission = pipeline.sendAsync();
      submission.thenAccept(created ->
          System.out.println("Accepted pipeline " + created.path("id").asLong())).join();
    }
  }
}

This submits asynchronously and waits for the submission, not pipeline completion. Keep the getting-started worker online to execute it.

You can inject a configured Java HttpClient into PipelogiqApiClient, then pass that API client to a runner. Caller-owned clients remain caller-owned. For custom TLS trust or proxies, configure the client or JVM trust store; there is no SDK-wide trust-all switch.

API errors and uncertain writes

An ApiException exposes statusCode(), body() and parsed retryAfter(). Its default message contains the HTTP status, not the raw response body. Log only the response details appropriate for your environment.

The client does not silently retry API writes. A failed or timed-out request can leave the caller uncertain whether a server accepted a write. Use pipeline idempotency for repeated creation and inspect state before replaying non-idempotent operations such as external stage appends. Retry-After is available as information; it is not an automatic request-retry loop.

Interrupted synchronous requests cancel the pending future and propagate cancellation. Closing the client cancels pending requests. Do not close an owning builder immediately after obtaining its asynchronous future and expect the request to keep running.

Schedules and execution policy

ScheduleBuilder supports cron, every and runOnceAt. It strips request credentials, creation idempotency and tracing fields from stored definitions. Use named API operations for schedule list/history, pause/resume/archive and manual trigger.

The server owns scheduling and retry behavior. A builder accepting a combination does not prove every server policy combination has been exercised by the Java test suite. See workflow recipes for concrete, observable examples.

Java and .NET interoperability

Both SDKs target the same Pipelogiq execution protocol and shared storage formats. Their public language APIs are adapted to their runtimes:

Registering a Java handler with the same wire name and input structure as another SDK is a protocol choice; it does not load that SDK's classes. Jackson supports compatible PascalCase/camelCase DTO reads and Java time types. Primitive context type hints are compatible, but arbitrary CLR assembly-qualified types do not become Java classes. Use interoperable JSON DTOs.

Redis and PostgreSQL session/memory implementations preserve shared representations and namespace rules. This enables cross-language applications to read agreed session data; it does not provide automatic conversion of arbitrary application objects. PostgreSQL and Redis also retain backend-specific retention and duplicate-entry behavior.

Java intentionally omits deprecated global credentials, keyword aliases and legacy budget aliases. Use labels for classification, context for execution data, and per-run agent budget fields. Spring integration and OpenTelemetry exporting belong to the application; neither is emulated as a .NET compatibility layer.

Verification boundaries

The SDK includes unit tests, local HTTP protocol fixtures, an agent harness, live server/transport/store tests, cross-language storage checks and independent package-consumer checks. Those layers answer different questions.

The recorded 0.5.0 release verification includes Java 17 and Java 21 runs, each reporting 182 tests without failures, errors or skips. Its provider and Telegram checks use local fixtures; they do not prove a real provider account, model quality, real Telegram delivery or sustained production throughput. Java 25 was not tested in that recorded release run.

Current Maven-group publication preparation is a separate change from those runtime test results. Registry visibility, namespace ownership and successful public consumer installation must be confirmed before switching these pages from source-install instructions to Central-install instructions.

For application code, begin with deterministic agent checks, then validate actual server workflows in an isolated application. Avoid sharing live agent handler queues across concurrently running tests with different runtime configurations.