From Synchronous HTTP to CompletableFuture: Mastering Async in Java

1. Starting from a Synchronous HTTP Call

A simple business scenario: a backend service provides an API that returns data based on latitude and longitude (reverse‑geocoding). The request URL looks like:

curl -i "http://xxx?latitude=31.08966221524924&channel=amap7a&near=false&longitude=105.13990312814713"

The response is a JSON containing the administrative code: {"adcode":"510722"} When the server makes this synchronous call, the I/O thread blocks in the native method java.net.SocketInputStream#socketRead0 until the response arrives.

Thread dump (excerpt) shows the main thread stuck in socketRead0:

"main"#1 prio=5 os_prio=31 tid=0x00007fed0c810000 nid=0x1003 runnable [0x000070000ce14000]
   java.lang.Thread.State: RUNNABLE
   at java.net.SocketInputStream.socketRead0(Native Method)
   at java.net.SocketInputStream.socketRead(SocketInputStream.java:116)
   ...

Because the thread is blocked, resources are not fully utilized, limiting throughput for I/O‑heavy workloads.

2. JDK NIO & Future

Since JDK 1.5, the java.util.concurrent (JUC) package provides the Future abstraction, allowing asynchronous computation results to be retrieved later. Some implementations, like io.netty.util.concurrent.AbstractFuture, use thread polling.

Using Future lets the main thread continue with other work (e.g., issuing another I/O request) while waiting for the first response.

3. Using Callback

Instead of making the main thread wait for the result, a callback can be registered. After the request is sent, the main thread can perform other tasks or return to a thread pool. In an HTTP server, this aligns with Servlet 3.1 asynchronous processing.

4. Callback Hell

When callbacks trigger further I/O calls, the code quickly becomes nested and hard to maintain – the classic “callback hell”. A typical example is chaining reverse‑geocoding to a weather‑lookup API.

5. JDK 1.8 CompletableFuture

Java 8 introduces CompletableFuture, which solves callback hell by allowing each I/O operation to be represented as an independent future. When the asynchronous thread completes, it calls future.complete(T) to deliver the result.

Example: wrap the reverse‑geocode callback into a CompletableFuture, then compose it with another future that fetches weather data. The composition looks like:

CompletableFuture<String> reverseCodeFuture = new CompletableFuture<>();
// in async callback
reverseCodeFuture.complete(adcode);

CompletableFuture<Weather> weatherFuture = reverseCodeFuture.thenCompose(code -> fetchWeatherAsync(code));
weatherFuture.whenComplete((w, ex) -> System.out.println(w));

Each I/O step is now a separate future, eliminating deep nesting.

6. Vert.x Future

Vert.x provides a similar abstraction called Future that uses handlers. The core execution pattern mirrors the CompletableFuture approach, allowing non‑blocking composition of asynchronous tasks.

7. Reactive Streams

Reactive Streams define a minimal set of interfaces— Publisher, Subscriber, Processor, and Subscription —to standardize asynchronous stream processing. In JDK 9 these interfaces are available as java.util.concurrent.Flow.

8. Reactor & Spring 5 & Spring WebFlux

Project Reactor implements the Reactive Streams specification with the Flux (multiple elements) and Mono (zero or one element) types. Spring 5 builds on Reactor to provide WebFlux, a non‑blocking web framework that enables fully asynchronous request handling.

Reference materials: https://www.cnblogs.com/davenkin/p/async-servlet.html https://www.baeldung.com/java-9-reactive-streams https://projectreactor.io/docs/core/3.1.0.M3/reference/index.html