Skip to content
Tutorials Center
My learning

Topics

Lesson 94 of 119 ยท Architecture and Deployment

Reactive Programming

Understand reactive programming in Java - Reactive Streams, backpressure, java.util.concurrent.Flow with SubmissionPublisher, Project Reactor, WebFlux and virtual threads.

A classic Java web server gives every request its own thread. That thread runs your controller, waits for the database, waits for another service, and finally writes the response. While it waits, it does nothing useful but still costs memory (traditionally around a megabyte of stack per platform thread). With a pool of 200 threads, the 201st concurrent request has to queue, even though the CPU is mostly idle.

Reactive programming attacks this problem from a different angle. Instead of blocking a thread while waiting, you describe a pipeline of steps that react to data as it arrives: "when the book loads, combine it with the reviews, then turn it into JSON". A small number of threads run many such pipelines, because none of them ever sits waiting. Reactive libraries add a second important idea: backpressure, a way for a slow consumer to tell a fast producer to slow down.

In this lesson you will learn the Reactive Streams protocol behind every Java reactive library and run it with the JDK's own java.util.concurrent.Flow API. Then you will see Project Reactor and Spring WebFlux (read-only, since they are not available here) and, finally, compare the reactive style with virtual threads, which since Java 21 solve much of the same problem with ordinary blocking code. Familiarity with Scheduling, Caching and Async Tasks (especially CompletableFuture) and Messaging with Kafka and RabbitMQ helps.

From values to streams of values

You already know two ways to get results:

One value Many values
Synchronous (pull) T get() Iterable<T>, Stream<T>
Asynchronous (push) CompletableFuture<T> Publisher<T>

A CompletableFuture delivers one value later. A publisher delivers zero or more values over time, then either completes or fails: rows streaming from a database, price ticks, messages from Kafka, server-sent events to a browser. The consumer doesn't pull with a loop; the publisher pushes each item when it's ready.

Pushing raises an obvious danger. If a publisher produces 100,000 items per second and the subscriber can handle 1,000, where do the other 99,000 go? Buffering them all eventually exhausts memory; dropping them silently loses data. Reactive Streams solves this by letting the subscriber request exactly how many items it can handle.

The Reactive Streams protocol

Reactive Streams is a small specification, adopted into the JDK in Java 9 as the nested interfaces of java.util.concurrent.Flow:

Java
public final class Flow {
    public interface Publisher<T> { void subscribe(Subscriber<? super T> subscriber); }

    public interface Subscriber<T> {
        void onSubscribe(Subscription subscription);
        void onNext(T item);
        void onError(Throwable throwable);
        void onComplete();
    }

    public interface Subscription {
        void request(long n);   // "I can take n more items"
        void cancel();          // "stop sending"
    }

    public interface Processor<T, R> extends Subscriber<T>, Publisher<R> {}
}

The rules, simplified:

  1. A subscriber calls publisher.subscribe(subscriber). The publisher answers with onSubscribe(subscription).
  2. Nothing flows until the subscriber calls request(n). The publisher may then send at most n items with onNext. The subscriber requests more whenever it is ready. This is backpressure.
  3. The stream ends with exactly one terminal signal: onComplete() or onError(e). After that, no more signals.
  4. Signals to one subscriber are never sent concurrently, so a subscriber doesn't need locks for its own state.

You rarely implement these interfaces yourself (it's surprisingly easy to break a rule), but writing one tiny publisher makes the protocol concrete. This one emits a range of numbers and only as many as were requested:

Java A hand-written publisher that respects request(n)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The subscriber was in control the whole time: items arrived in pairs, only after each request(2), and the stream stopped when the subscriber cancelled at 7, so 8 to 10 were never produced. Requesting Long.MAX_VALUE means "send everything, I can keep up", effectively turning backpressure off. (This toy calls onNext recursively from inside request; real publishers avoid that recursion and handle concurrency, which is why you should use a library.)

SubmissionPublisher: the JDK's ready-made publisher

The JDK includes one production-quality publisher, SubmissionPublisher<T>. You call submit(item) from your code; it buffers items per subscriber and delivers them asynchronously on an Executor (by default the common ForkJoinPool). Calling close() sends onComplete after the buffered items. The JDK has no ready-made subscriber classes, so you write one, or use consume(Consumer) for the simple case.

Java SubmissionPublisher with a subscriber

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The main line may appear before, between or after the received lines, because delivery happens on another thread. That is the essence of asynchronous streams: submitting and processing are decoupled. Within one subscriber, however, the order of events is preserved.

Backpressure in action

What happens when the subscriber is slower than the producer? SubmissionPublisher gives each subscriber a bounded buffer. When the buffer is full, submit blocks the producer until the subscriber catches up. (Alternatively, offer lets you drop items or retry with a timeout instead of blocking.) The producer is automatically slowed down to the consumer's pace, and memory use stays bounded.

Java A slow subscriber slows down the producer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Twenty items at 20 ms each take about 400 ms to consume. Because the buffer holds only a few items, the producer spent most of that time blocked in submit. This is the same principle as the bounded BlockingQueue in the messaging lesson and as Kafka consumers that poll only when ready: the consumer sets the pace.

Processors: building pipelines

A Flow.Processor is both a subscriber (to the stage before it) and a publisher (to the stage after it). Chaining processors builds a pipeline: source โ†’ filter โ†’ map โ†’ sink. Extending SubmissionPublisher gives you the publishing half for free:

Java A pipeline of Flow processors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Each stage runs asynchronously, requests one item at a time from the stage before it, and passes onComplete downstream, so closing the source completes the whole pipeline. Writing operators this way is laborious, though, and you would need dozens of them (map, filter, flatMap, zip, timeout, retry, buffer...). That is what reactive libraries provide.

Project Reactor

Project Reactor is the reactive library behind Spring. It implements Reactive Streams with two publisher types:

  • Mono<T>: 0 or 1 item, like an asynchronous Optional or a lazy CompletableFuture.
  • Flux<T>: 0 to N items, possibly infinite.

Both come with a large set of operators that look like the Stream API, but work over time:

Java
Flux<String> titles = Flux.just("Dune", "Emma", "Beloved", "Ulysses")
    .filter(title -> title.length() > 4)
    .map(String::toUpperCase);

titles.subscribe(System.out::println);    // BELOVED, ULYSSES

The most important rule: nothing happens until you subscribe. Building a Flux only describes a pipeline. That laziness lets you retry a whole pipeline (re-subscribing runs it again), but it also confuses newcomers who build a Mono that saves to the database and wonder why nothing was saved: nobody subscribed.

The book-page example from the previous lesson, combining three remote calls in parallel with a timeout and a fallback, looks like this in Reactor:

Java
Mono<BookPage> page(long id) {
    return Mono.zip(catalog.book(id), reviews.summary(id), stock.availability(id))   // all three in parallel
        .map(t -> new BookPage(t.getT1(), t.getT2(), t.getT3()))
        .timeout(Duration.ofSeconds(2))
        .retryWhen(Retry.backoff(2, Duration.ofMillis(100)))
        .onErrorResume(TimeoutException.class, e -> Mono.just(BookPage.unavailable(id)));
}

Other operators you will meet constantly:

Operator Purpose
flatMap For each item, start another async call; results interleave (use concatMap to keep order)
zip, zipWith Combine results of several publishers
switchIfEmpty, defaultIfEmpty Handle "no value"
onErrorResume, onErrorReturn, retryWhen Error handling and retries
buffer, window Group items into batches
onBackpressureBuffer, onBackpressureDrop, limitRate Explicit backpressure strategies
subscribeOn, publishOn Choose which Scheduler (thread pool) runs the work
doOnNext, log Side effects and debugging without changing the stream

Spring WebFlux

Spring WebFlux is the reactive counterpart to Spring MVC. It runs on a non-blocking server (Netty by default) with a few event-loop threads, and controllers return Mono or Flux:

Java
@RestController
@RequestMapping("/books")
class BookController {

    private final BookRepository books;        // a ReactiveCrudRepository (Spring Data R2DBC)
    private final WebClient reviews;

    BookController(BookRepository books, WebClient.Builder builder) {
        this.books = books;
        this.reviews = builder.baseUrl("http://review-service").build();
    }

    @GetMapping("/{id}")
    Mono<BookDto> one(@PathVariable long id) {
        return books.findById(id)
            .switchIfEmpty(Mono.error(new ResponseStatusException(HttpStatus.NOT_FOUND)))
            .zipWith(reviews.get().uri("/reviews/summary/{id}", id).retrieve().bodyToMono(ReviewSummary.class))
            .map(t -> BookDto.from(t.getT1(), t.getT2()));
    }

    @GetMapping(value = "/new-arrivals", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    Flux<BookDto> newArrivals() {
        return books.findNewArrivals().map(BookDto::from);   // streamed to the browser as server-sent events
    }
}

Spring subscribes for you when it writes the response, and backpressure flows all the way to the network: if the client reads slowly, the database stream is read slowly too.

To get the benefit, the whole chain must be non-blocking. WebFlux pairs with WebClient for HTTP, R2DBC for relational databases (instead of JDBC), and reactive drivers for MongoDB, Redis, Cassandra and Kafka. A single blocking call (JDBC, Thread.sleep, a blocking HTTP client) on an event-loop thread stalls every request that thread serves. If you must call blocking code, move it to a separate scheduler with subscribeOn(Schedulers.boundedElastic()), and treat it as a warning sign.

Virtual threads versus reactive

Java 21 introduced virtual threads: threads managed by the JVM that cost a few hundred bytes to a few kilobytes instead of a megabyte. When a virtual thread blocks on I/O, the JVM unmounts it from its carrier (platform) thread, which immediately runs another virtual thread. You get the scalability of non-blocking I/O while writing plain blocking code.

Java Ten thousand blocking tasks on virtual threads

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Ten thousand tasks that each block for 100 ms completed in a fraction of the time a fixed pool would need, with ordinary sequential code inside each task. Spring Boot can run every request on a virtual thread with one property: spring.threads.virtual.enabled=true.

So which should you choose?

Virtual threads + blocking code Reactive (Reactor/WebFlux)
Programming model Plain sequential code, try/catch, loops Operator pipelines, callbacks
Stack traces and debugging Normal Hard to read (assembly-time vs run-time)
Libraries Everything: JDBC, JPA, any HTTP client Requires reactive drivers end to end
Scalability for I/O-bound work Excellent Excellent
Streaming with backpressure Manual (bounded queues) Built in, end to end
Learning curve Low High

For a typical request/response service that calls databases and other APIs, virtual threads are now the simpler default. Reactive programming still shines when your problem is a stream: long-lived connections (server-sent events, WebSockets), streaming large result sets with backpressure, event processing pipelines, and systems that already use WebFlux successfully. Don't migrate a working WebFlux application just because virtual threads exist, and don't start a new CRUD service in WebFlux only for performance.

Two cautions about virtual threads: they don't make CPU-bound work faster (a CPU has as many cores as it has), and a limited resource remains limited. Ten thousand virtual threads sharing a 20-connection database pool will wait for connections, so size pools and use bulkheads, as described in Microservices.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A subscriber calls request(3) in onSubscribe and never requests again. The publisher has 100 items. How many onNext calls can the subscriber receive?

    In Reactive Streams, a publisher may only send as many items as have been requested. This is how backpressure works.
  2. 2. A WebFlux handler builds Mono<Void> saved = repository.save(book).then(); but never returns or subscribes to it. What happens?

    Reactor publishers are lazy. Return the Mono to Spring (which subscribes) or compose it into the returned chain.
  3. 3. In the backpressure demo, the subscriber processes one item per 20 ms and the buffer is small. What happens to the producer calling submit()?

    SubmissionPublisher.submit blocks when the buffer is full. offer() is the alternative that can drop items or time out.
  4. 4. A WebFlux controller calls a JDBC repository directly inside a map operator. Why is that a problem?

    WebFlux uses a few event-loop threads. Blocking calls must be avoided or moved to a bounded elastic scheduler.
  5. 5. You are starting a new CRUD REST service that uses JPA and calls two other HTTP APIs. Which approach is usually the simplest that scales well?

    Virtual threads give high concurrency for I/O-bound blocking code and keep the familiar programming model and libraries like JPA.

Summary

  • Reactive programming composes asynchronous, push-based streams of values and lets few threads serve many concurrent operations.
  • Reactive Streams (java.util.concurrent.Flow): Publisher, Subscriber, Subscription, Processor. Nothing flows until request(n), at most n items are sent, and each stream ends with onComplete or onError.
  • Backpressure lets the consumer set the pace. SubmissionPublisher buffers per subscriber and blocks submit when the buffer is full; offer can drop instead.
  • Project Reactor provides Mono (0..1) and Flux (0..N) with rich operators; pipelines are lazy until subscribed.
  • Spring WebFlux runs reactive controllers on Netty and needs non-blocking libraries end to end (WebClient, R2DBC). Never block an event-loop thread.
  • Virtual threads offer similar scalability for I/O-bound work with plain blocking code. Prefer them for typical request/response services; choose reactive for true streaming and backpressure-heavy workloads.

Next: Docker for Java Developers packages your service into a container image that runs the same way everywhere.