Product Updates

Java async support: Native non-blocking SDKs with reactive streaming

Vishal Gowda

September 3, 2025 - 5 min read

Product Updates

---

Java SDKs, now async‑native: CompletableFuture + Reactive Streams

Java’s ecosystem has steadily shifted toward asynchronous, event‑driven programming. Reactive architectures are increasingly adopted by major platforms¹, while CompletableFuture is ubiquitous in modern APIs. For key reactive concepts, see the Reactive Manifesto glossary . SDKs should match this async‑first reality—without forcing teams to abandon familiar synchronous code.

What’s new

• Async native: CompletableFuture<T> returned by standard methods.
• Streaming built‑in: Reactive Streams Publisher<T> for pagination, SSE, JSONL, and file I/O.
• Dual SDK: Synchronous by default; opt in with .async() per call‑site or service.
• Blob: A light, framework‑agnostic byte‑stream abstraction for efficient uploads/downloads.

Why async

Traditional blocking SDKs dedicate one thread per in‑flight request. That results in idle threads, wasted memory, and hard‑to‑tune pools. Especially under high concurrency and variable network latency. Async I/O scales with a small, fixed number of threads without sacrificing composition² or backpressure ³.

When async provides the most value

Here’s how this works in practice. We expose both sync and async interfaces from one SDK:

Implementation deep‑dive

Our HTTP stack uses Java 11’s HttpClient async APIs and NIO.2  primitives (ByteBuffer, AsynchronousFileChannel, AsynchronousSocketChannel) for end‑to‑end non‑blocking I/O.

Our SDKs go to lengths to ensure there is as little as possible thread blocking work. For standard JSON responses, we collect and decode bytes asynchronously using thenApply/thenCompose. For streams, we hook into Flow.Publisher<List<ByteBuffer>>.

Async iterables via Reactive Streams

For async iterables (pagination, streaming responses), we represent them as Reactive Streams  [Publisher<T>](https://github.com/reactive-streams/reactive-streams-jvm/blob/v1.0.4/README.md#1-publisher-code ). Traditional Java collections or custom iterators aren’t feasible for async scenarios—they can’t express non‑blocking backpressure  or handle variable consumption rates gracefully. Using Publisher<T> is an increasingly common idiom in modern Java applications, providing seamless interoperability with mature reactive ecosystems like Project Reactor , RxJava , Akka Streams , Vert.x , and Quarkus Mutiny . We keep dependencies light by implementing JDK‑native operators (map, mapAsync, concat, wrap, flatten) through custom publishers, subscribers, and subscriptions.

Protocol‑aware streaming

• SSE & JSONL: Custom publishers bridge raw byte streams to protocol parsers, yielding typed events on backpressure‑aware Publisher<T>
• Pagination: A generic, non‑blocking pagination publisher drives page fetches using pluggable ProgressTrackerStrategy to parse cursors and termination conditions

Retries, timeouts, and hooks

• Async retries use ScheduledExecutorService for non‑blocking exponential backoff with jitter
• Timeouts/cancellation⁴ are surfaced with CompletableFuture#orTimeout, completeExceptionally, and cancellation propagation to HTTP requests
• Hook transformations leverage CompletableFuture for zero‑blocking customization points

Efficient payloads with Blob

Blob is our core abstraction for working with streams of ByteBuffer:

Multipart uploads concatenate publishers—each part (form field or file) is its own stream. Downloads expose Blob so you can stream to disk without buffering whole payloads.

Reactive streaming patterns

Reactor

RxJava

Akka Streams

On Virtual Threads

Virtual threads  make synchronous code scale far better by reducing the cost of blocking. They’re a great fit for simple request/response flows and can be used with the synchronous SDK today. Our async SDK still adds value where you need backpressure, streaming, cancellation, and composition across multiple concurrent I/O operations—patterns that CompletableFuture/Publisher express naturally.

For API Producers: the unified paradigm advantage

• Broader reach: Works for Spring MVC (sync) and WebFlux/Quarkus (async)
• Migration flexibility: Adopt async gradually without replacing integrations
• Lower maintenance: One codebase; two clean interfaces
• Consistent DX: Same auth, errors, and config everywhere

Getting started

Enable the following flag in your .speakeasy/gen.yaml:

Then run speakeasy run to regenerate your SDK.

For existing SDKs, see our migration guide  for step-by-step instructions on enabling async support for your SDKs.

Looking ahead

This release lays the groundwork for the full spectrum of modern Java patterns—from cloud‑native microservices to real‑time streaming systems. Ready to unlock the benefits of non‑blocking I/O? Regenerate your Java SDK  and try it today.