Skip to main content

24 posts tagged with "webflux"

View All Tags

Deep Dive Schedulers.boundedElastic()

· 12 min read

Start with a simple piece of code snippet​

kafkaReceiver.receive()
.concatMap(message -> process(message) // Step 1
.subscribeOn(Schedulers.boundedElastic())) // Step 2
.doOnNext(msg -> msg.receiverOffset().acknowledge()) // Step 3
.subscribe(); // Step 4

This is the gold-standard pattern in 2025 for consuming Kafka with Spring WebFlux + Project Reactor + Reactor Kafka when process(message) contains blocking code (JDBC, Redis sync driver, REST call with RestTemplate, file I/O, etc.).

Step-by-Step Execution Flow​

StepWhat HappensWhich Thread Pool?Why It Matters
1kafkaReceiver.receive() returns a Flux<ReceiverRecord>Runs on Netty event-loop threads (non-blocking I/O)This thread must never block or the whole reactor Netty server will starve
2concatMap waits for the **previous process() to finish before taking the next message → preserves Kafka order per partitionStill on Netty thread until…
subscribeOn(Schedulers.boundedElastic()) moves the entire upstream work (i.e. process(message)) to a boundedElastic thread→ jumps to boundedElastic thread poolThis is the only safe place to do blocking work
3After process() completes successfully, we come back to the original Netty thread to call acknowledge()Back on Netty event-loopCommit must happen on the same thread that received the record (Reactor Kafka requirement)
4.subscribe() starts the whole chain

What Is Schedulers.boundedElastic() Exactly?​

PropertyValue (Reactor 3.6+)What It Means in Practice
Thread pool typeThread-per-task + bounded queueCreates new threads on demand
Max threadsMath.max(10, CPU × 10) → usually 100–200Will never create thousands of threads
QueueBounded (default 100,000 tasks)If queue full → onError with QueueFullException
Thread name prefixboundedElastic-xEasy to spot in thread dumps
Designed forBlocking I/O (JDBC, blocking Redis, file, external sync API)This is the only scheduler you are allowed to block on

Comparison with Other Schedulers​

SchedulerUse CaseCan I block here?
Schedulers.parallel()CPU-intensive (encryption, image processing)No – will starve CPU workers
Schedulers.boundedElastic()Blocking I/O ← this is the oneYes – made for this
Schedulers.single() / immediate()Rare, very specific casesNever block

Real-Life Example – What Happens with 10,000 Messages/sec​

// BAD – blocks Netty thread → entire WebFlux app dies in seconds
.concatMap(msg -> blockingJdbc.save(msg))

// GOOD – this code you posted
.concatMap(message -> process(message) // contains JdbcTemplate, RestTemplate, etc.
.subscribeOn(Schedulers.boundedElastic()))

Without subscribeOn(boundedElastic()) → Netty event-loop threads block → TCP backlog → all WebSocket clients disconnect → outage.

With it → 150 boundedElastic threads happily do JDBC work, Netty stays responsive, throughput 10k+/sec easily.

Best Practices (2025)​

// Most common production pattern
kafkaReceiver.receive()
.concatMap(record ->
process(record.value()) // may block
.subscribeOn(Schedulers.boundedElastic()) // ← mandatory
.doOnError(ex -> log.error("...", ex))
.onErrorReturn fallbackValue) // don't stop the consumer
.doOnNext(ReceiverRecord::receiverOffset.acknowledge) // commit
.retryWhen(Retry.backoff(10, Duration.ofSeconds(1))) // survive Kafka blips
.subscribe();

Summary​

Schedulers.boundedElastic() is the only safe place to run blocking code in a WebFlux/Reactive application.
Without it, you will kill your Netty event-loop and take down the entire service.
With it, you get safe, scalable, ordered Kafka consumption even when process() talks to JDBC, Redis sync, or any legacy blocking library.

That one line .subscribeOn(Schedulers.boundedElastic()) is literally the difference between a stable 50k RPS service and a total outage.

What exactly happens under the hood when you write this line:​

process(record.value())
.subscribeOn(Schedulers.boundedElastic())

Step-by-Step Execution (Thread View)​

TimeWhat happensWhich thread does the work?Thread pool name
1Kafka record arrives on Netty event-loop threadreactor-http-nio-3 (or similar)Netty event-loop
2concatMap sees the subscribeOn(boundedElastic()) operatorStill on Netty thread
3Reactor immediately hands the entire process(...) chain to the boundedElastic scheduler→ jumps to a thread from the boundedElastic thread poolboundedElastic-1, boundedElastic-2, …
4Your process(record.value()) code runs completely on that boundedElastic threadYes – this thread can safely block (JDBC, RestTemplate, File I/O, etc.)
5When process() finishes (success or error), Reactor schedules the downstream operators (.doOnNext(acknowledge)) back on the original Netty thread (because of how Reactor Kafka is designed)Back to reactor-http-nio-3

Visual Thread Timeline​

Netty thread (reactor-http-nio-3) boundedElastic thread pool
────────────────────────────── ───────────────────────────────
receive() → concatMap → subscribeOn() ──→ boundedElastic-7 runs process()
← process() completes
→ acknowledge() runs back on Netty thread

boundedElastic Thread Pool Details (2025 defaults)​

PropertyValue (Reactor 3.6+)Meaning
Core threads10 (minimum)Always alive
Maximum threadsCPU cores × 10 → usually 100–200Grows only when queue is full
Queue size100,000 tasks (configurable)If full → rejects with exception
Thread keep-alive60 seconds (idle threads die)Saves memory
Thread name prefixboundedElastic-1, boundedElastic-2, …Easy to spot in jstack / Grafana

Real Example from Production Thread Dump​

"boundedElastic-27" #124 daemon prio=5 os_prio=0 tid=0x... nid=0x4b2c runnable
java.lang.Thread.State: RUNNABLE
at com.mysql.cj.jdbc.ClientPreparedStatement.executeQuery(...)

"boundedElastic-28" #125 daemon prio=5 os_prio=0 tid=0x... nid=0x4b2d waiting on condition
java.lang.Thread.State: WAITING (parking)
at jdk.internal.misc.Unsafe.park(Native Method)
- parking to wait for <0x...> (a java.util.concurrent.locks.AbstractQueuedSynchronizer$ConditionObject)

You can see 27 threads doing MySQL queries, 28 waiting for more work – exactly what we want.

Summary Again​

subscribeOn(Schedulers.boundedElastic()) =
“Take this whole piece of work (process(...)) and run it on a dedicated thread pool that is designed and allowed to block.
The Netty event-loop stays completely free and responsive.”

That single operator is the #1 reason reactive Spring Boot + Kafka applications survive real production traffic without melting down.

What Exactly Happens Inside Schedulers.boundedElastic() (Reactor 3.5+ / Spring Boot 3.x – 2025)​

QuestionExact Answer (Source Code Level)
Which ThreadPoolExecutor is used under the hood?BoundedElasticScheduler → wraps a custom java.util.concurrent.ThreadPoolExecutor with a very special configuration
Executor typeUnbounded core + bounded maximum + bounded queue (the only one in the JDK that behaves like this)
JDK classreactor.core.scheduler.BoundedElasticScheduler.BoundedScheduledExecutorService → extends ThreadPoolExecutor
Queue usedLinkedBlockingQueue<Runnable> with configurable capacity (default 100,000)
Thread factoryreactor.core.scheduler.SchedulerThreadFactory → names threads boundedElastic-1, boundedElastic-2, …

Exact Thread Pool Configuration (2025 defaults)​

ParameterValue (Reactor 3.6+)Formula / Meaning
corePoolSize0 (zero!)No threads kept alive when idle
maximumPoolSizeCPU × 10 (e.g. 8-core → 80, 16-core → 160, capped at ~200)Math.min(Runtime.getRuntime().availableProcessors() * 10, 100_000)
keepAliveTime60 secondsIdle threads above core (i.e. all) die after 60s
Queue capacity100,000 tasks by defaultConfigurable via -Dreactor.schedulers.boundedElastic.queueCapacity=500000
RejectedExecutionHandlerAbortPolicy → throws RejectedExecutionException when queue fullYou’ll see QueueFullException in logs if overloaded

Execution Strategy – Visualized​

corePoolSize = 0 → No threads at startup
│
└─ Task arrives → create new thread (up to maxPoolSize)
│
├─ Queue has space → enqueue task
│ (even if threads < maxPoolSize)
│
└─ Queue full + threads == maxPoolSize → REJECT
Task arrives
│
├─ threads < maxPoolSize → create new thread immediately
│
├─ threads == maxPoolSize → enqueue in 100k queue
│
└─ queue full + max threads → RejectedExecutionException → your Flux errors

This is NOT the classic “fixed + bounded queue” model.
It’s a hybrid designed specifically for blocking I/O:

  • Grow very aggressively (up to CPU×10) to handle bursty blocking calls
  • Shrink back to zero when idle → saves memory in microservices
  • Huge queue (100k) prevents rejection in normal spikes

How to Change the Limits (Production Tuning)​

# application.yml (Spring Boot)
spring:
threads:
virtual:
enabled: true # Java 21+ → switches to virtual threads automatically!

Or JVM flags:

# Increase queue to 500k
-Dreactor.schedulers.boundedElastic.queueCapacity=500000

# Force max 200 threads even on 32-core machines
-Dreactor.schedulers.boundedElastic.maxThreads=200

Java 21+ Bonus: Virtual Threads (2024–2025 reality)​

Since Java 21 + Reactor 3.6 + Spring Boot 3.2:

Schedulers.boundedElastic() // automatically uses virtual threads

→ Each task gets its own virtual thread instead of platform thread
→ maximumPoolSize becomes practically unlimited (hundreds of thousands)
→ Memory per thread drops from ~1–2 MB → ~100 KB
→ You can safely process 100k+ blocking JDBC calls concurrently

Summary One More Time​

Schedulers.boundedElastic()
= ThreadPoolExecutor(
corePoolSize = 0,
maximumPoolSize = CPU × 10,
keepAlive = 60s,
queue = LinkedBlockingQueue(100_000),
policy = AbortPolicy
)
+ (since Java 21) automatically uses virtual threads → effectively unlimited

That’s why it’s the only safe place to call JDBC, RestTemplate, blocking Redis, etc. in a WebFlux/Reactive application — and why it scales beautifully in real production systems handling 10k–100k RPS.

Real Production Code Patterns​

// 1. Classic blocking Kafka consumer (most common)
kafkaReceiver.receive()
.concatMap(record ->
processBlocking(record.value()) // JDBC, RestTemplate, etc.
.subscribeOn(Schedulers.boundedElastic()) // ← THIS SAVES YOUR APP
.doOnError(ex -> log.error("Failed {}", record, ex))
.onErrorResume(ex -> Mono.empty()) // don't kill the stream
)
.doOnNext(ReceiverRecord::receiverOffset.acknowledge)
.subscribe();

// 2. WebFlux controller calling legacy blocking service
@GetMapping("/legacy-report")
public Mono<Report> getReport() {
return Mono.fromCallable(() -> legacyBlockingService.generatePdf())
.subscribeOn(Schedulers.boundedElastic()) // safe!
.timeout(Duration.ofSeconds(30));
}

// 3. Parallel batch processing (e.g. 1000 files)
Flux)
filesFlux
.flatMap(file ->
processFile(file) // heavy CPU + blocking I/O
.subscribeOn(Schedulers.boundedElastic()),
50 // max 50 concurrent
)
.collectList()
.block();

5. Production Tuning Examples​

# Recommended JVM flags for high-throughput services (2025)
-Dreactor.schedulers.boundedElastic.maxThreads=500
-Dreactor.schedulers.boundedElastic.queueCapacity=200000
-Dreactor.schedulers.defaultBoundedElasticOnVirtualThreads=true # force virtual threads even on JDK 21+

# Or in application.yml (Spring Boot 3.2+)
spring:
threads:
virtual:
enabled: true # ← turns boundedElastic into virtual-thread heaven

6. What Happens If You Forget It? (Real Outage Stories)​

MistakeSymptomTime to Total Outage
Call JdbcTemplate directly in WebFluxNetty threads block → TCP backlog → all WebSockets disconnect10–60 seconds
Use Schedulers.parallel() for JDBCCPU workers starve → GC thrashing → OOM2–10 minutes
Use subscribeOn(boundedElastic())System stays alive at 50k+ RPSNever

Must Remember!!!​

Schedulers.boundedElastic() is the only thread pool specifically created so you can safely call blocking code (JDBC, RestTemplate, Redis sync, file I/O, etc.) inside a fully reactive Spring WebFlux application without blowing up your Netty event loop.

Can Schedulers.boundedElastic() be pre-configured?​

Yes but only via system properties (JVM flags) or Spring Boot properties — not via code like new BoundedElasticScheduler(...) in normal applications.

Here is the complete list of everything you can pre-configure in 2025 (Reactor 3.6+ / Spring Boot 3.2+):

What you want to changeHow to do it (JVM flag)Spring Boot 3.2+ equivalent (application.yml)Default value
Maximum threads (JDK ≤20)-Dreactor.schedulers.boundedElastic.maxThreads=500spring.threads.virtual.enabled=false + JVM flagCPU × 10
Queue capacity-Dreactor.schedulers.boundedElastic.queueCapacity=500000—100,000
Thread name prefix-Dreactor.schedulers.boundedElastic.threadPrefix=myapp-be—boundedElastic
TTL of cached schedulers-Dreactor.schedulers.boundedElastic.cachedSchedulerExpireAfter=300s—60s
Force virtual threads (JDK 21+)-Dreactor.schedulers.boundedElasticOnVirtualThreads=truespring.threads.virtual.enabled=true ← recommendedauto-detect
Pre-warm / init threadsNot directly possible—starts at 0

Can I Pre-create Threads?​

No
boundedElastic is intentionally designed with corePoolSize = 0.
There is no official way to pre-warm threads (create 10 threads at startup).

But here are three real-world workarounds senior teams actually use**:

Workaround 1 – Force virtual threads (JDK 21+) → problem disappears​

# application.yml – this is the 2025 gold standard
spring:
threads:
virtual:
enabled: true # ← makes boundedElastic use virtual threads

→ Each task gets its own virtual thread instantly
→ No thread creation latency
→ No need to pre-warm anything
→ This is what Netflix, Uber, Alibaba, and most new Spring Boot 3 apps do.

Workaround 2 – Custom pre-warmed scheduler (rare, but possible)​

@Configuration
public class ReactorConfig {

public static final Scheduler PREWARMED_BLOCKING = Schedulers.newBoundedElastic(
20, // core size (pre-created)
200, // max size
"myapp-blocking",
60 // keep-alive seconds
);

@PreDestroy
public void cleanup() {
PREWARMED_BLOCKING.dispose();
}
}

Then use it instead:

.subscribeOn(ReactorConfig.PREWARMED_BLOCKING)

Workaround 3 – Eager initialization at startup (hacky but works)​

@PostConstruct
public void warmupBoundedElastic() {
IntStream.range(0, 20).parallel().forEach(i ->
Schedulers.boundedElastic().schedule(() -> {
try { Thread.sleep(10); } catch (Exception ignored) {}
})
);
}

→ Forces the default boundedElastic to create 20 threads immediately.

2025 Production Recommendation​

# application.yml – copy-paste this and forget about thread pools forever
spring:
threads:
virtual:
enabled: true # ← turns boundedElastic into infinite virtual threads
task:
scheduling:
pool:
size: 50 # for @Scheduled tasks

With Java 21 + Spring Boot 3.2 + this config:

  • Schedulers.boundedElastic() becomes effectively infinite
  • Thread creation latency ≈ 0
  • Memory per blocking call ≈ 100 KB instead of 2 MB
  • You never have to pre-warm or tune anything again
GoalSolution in 2025
Pre-warm threadsNot possible with default scheduler
Make it fast + infinitespring.threads.virtual.enabled=true (JDK 21+) ← use this
Full controlCreate your own with Schedulers.newBoundedElastic(...)

99 % of teams in 2025 just enable virtual threads and never think about boundedElastic configuration again.

Mono.fromCallable(...) – The Ultimate 2025 Explanation​

(What every senior Java/Reactive engineer must know inside-out)

QuestionAnswer (Real Production Truth)
What is it?A factory method that creates a Mono<T> from a blocking, callable piece of code (Callable<T> or lambda that returns T).
When do you use it?Every time you have to call legacy blocking code (JDBC, RestTemplate, Redis sync, file I/O, external API, etc.) inside a reactive chain.
Is it blocking?Yes — the code inside runs synchronously and blocks the calling thread.
Is it safe to call directly in WebFlux?Only safe if you offload it (via .subscribeOn(...)) — otherwise you block Netty event-loop → outage.

Exact Contract & Behavior​

public static <T> Mono<T> fromCallable(Callable<? extends T> supplier)
ScenarioWhat actually happens
supplier returns a valueMono emits that value → onNext → onComplete
supplier throws exceptionMono emits onError with that exception
supplier returns nullMono emits onNext(null) → onComplete (yes, null is allowed)
You call it on Netty threadBlocks the carrier thread → bad unless you offload

The Two Correct Ways to Use It in 2025​

1. Classic way (Java 17–20) – must offload​

Mono.fromCallable(() -> jdbcTemplate.queryForObject(sql, Long.class))
.subscribeOn(Schedulers.boundedElastic()) // ← mandatory pre-Java 21
.timeout(Duration.ofSeconds(5));

2. 2025 way (Java 21 + virtual threads) – offload optional​

# application.yml
spring:
threads:
virtual:
enabled: true # ← turns boundedElastic into virtual threads
// Now perfectly safe without subscribeOn!
Mono.fromCallable(() -> jdbcTemplate.queryForObject(sql, Long.class))
.timeout(Duration.ofSeconds(5));

Real-World Examples (Copy-Paste Ready)​

// 1. Legacy JDBC call
Mono.fromCallable(() -> userRepository.findById(id)) // blocking
.subscribeOn(Schedulers.boundedElastic())

// 2. External blocking HTTP client
Mono.fromCallable(() -> restTemplate.postForEntity(url, request, String.class))
.map(HttpEntity::getBody)

// 3. File I/O
Mono.fromCallable(() -> Files.readString(Path.of("/tmp/config.json")))
.map(Json::parse)

// 4. CPU-heavy calculation (WRONG scheduler!)
Mono.fromCallable(() -> complexEncryption(data)) // CPU bound → use parallel!
.subscribeOn(Schedulers.parallel()) // ← correct

// 5. With error handling + fallback
Mono.fromCallable(() -> legacyService.getUser(id))
.onErrorResume(ex -> {
log.warn("Legacy failed, using cache", ex);
return Mono.just(cachedUser);
})

Common Mistakes Seniors Still Make​

MistakeConsequenceFix
Forgetting .subscribeOn(boundedElastic())Blocks Netty → all WebSockets disconnectAdd it (or enable virtual threads)
Using it for CPU workStarves parallel schedulerUse Mono.fromSupplier + Schedulers.parallel()
Chaining many fromCallable without limitThread explosion (one thread per call)Use .publishOn(...) or limit concurrency

Mono.fromCallable vs Alternatives (2025 Decision Table)​

Use CaseBest ChoiceWhy
Simple blocking call (DB, HTTP, file)Mono.fromCallable(...).subscribeOn(boundedElastic())Cleanest
You already have a Supplier<T>Mono.fromSupplier(...)Same as fromCallable but no checked exception
You want lazy execution only on subscribeMono.defer(() -> Mono.fromCallable(...))Prevents execution on cold publishers
Async but blocking driverPrefer true async driver (R2DBC, reactive Redis)Zero blocking

The One Rule Every Senior Lives By​

Mono.fromCallable { blocking code }
→ Always pair with .subscribeOn(Schedulers.boundedElastic())
→ Or run on Java 21+ with spring.threads.virtual.enabled=true and delete the subscribeOn forever.

Spring WebFlux Guide - 2025

· 25 min read

This is a comprehensive deep dive into the most crucial operators in Project Reactor, which is the foundation of Spring WebFlux. Understanding these operators is key to mastering non-blocking, reactive programming.

The operators are organized into functional categories, detailing their usage and real-world application.


1. 🏗️ Composition and Transformation Operators​

These operators modify the data emitted by a Publisher (Mono or Flux).

OperatorSignature & DescriptionKey DifferenceReal-World Use Case
map()T -> V (Synchronous transformation)Applies a synchronous function to each item. Returns a simple value.Converting a database entity (UserEntity) into a Data Transfer Object (UserDTO) after retrieval.
flatMap()T -> Publisher<V> (Asynchronous transformation)Applies an asynchronous function that returns a new Publisher. Essential for chaining non-blocking I/O operations.Chaining microservice calls: Get userId (Mono A) →\rightarrow Use userId to call an external service (Mono B) →\rightarrow Use result B to save to the database (Mono C).
concatMap()T -> Publisher<V> (Sequential flatMap)Similar to flatMap, but it processes and emits the results of the inner Publisher sequentially, preserving the original order of elements.Processing file uploads: Ensures that multiple files in a list are processed and saved to storage one after the other, respecting the order received, even though the I/O operations are async.
filter()T -> BooleanSelectively includes items based on a predicate.Excluding users with an isActive: false status before returning a list of clients.
cast()T -> V (Type conversion)Converts each element to a specified type.Converting an object retrieved from a generic cache (Object) to its expected type (Product).

2. 🤝 Combination and Merging Operators​

These operators combine the output from two or more source Publishers.

OperatorSignature & DescriptionKey DifferenceReal-World Use Case
merge()Publisher<T>... -> Flux<T> (Non-deterministic)Interleaves the elements from multiple sources as they arrive. The output order is not guaranteed and depends on timing.Combining real-time notifications: Combining two async streams of notifications (e.g., email and SMS alerts) into one feed where the order of arrival is acceptable.
zip()Publisher<T>, Publisher<V> -> Mono<Tuple2<T, V>> (Pairwise)Combines the n-th element from each source into a Tuple (or custom object) once all sources have emitted an element.Parallel data enrichment: Fetching a user profile (Mono<User>) and their recent transaction history (Mono<History>) concurrently, then combining both results into a single object for the API response.
combineLatest()Publisher<T>, Publisher<V> -> Flux<Tuple2<T, V>> (Emission-driven)Emits a new item whenever any source emits an item, combining the newly emitted item with the latest item from all other sources.Real-time dashboards: Combining a stream of stock prices with a stream of news headlines. A price update triggers a new emission with the latest price and the latest headline.
concat()Publisher<T>... -> Flux<T> (Sequential)Appends one Publisher after another. The second source does not start emitting until the first source completes.Fallback data loading: First attempt to load data from a fast cache (Mono A). If A completes empty, immediately execute a database query (Mono B).

3. ⏱️ Error Handling and Resilience Operators​

These operators manage exceptions and provide fallbacks.

OperatorSignature & DescriptionKey DifferenceReal-World Use Case
onErrorReturn()Class<E>, T (Simple fallback value)When an error of a specific type occurs, it immediately replaces the error signal with a default, static value and completes the sequence normally.Handling an external API timeout: If the weatherService.get() call fails with a TimeoutException, return a cached default value like "Weather Unknown" instead of propagating the error.
onErrorResume()Class<E>, Function<E, Publisher<V>> (Fallback publisher)When an error occurs, it switches to a fallback Publisher.Database failure: If the primary database query fails, switch to a fallback query that reads from a reliable but slightly stale read replica.
retry()long times (Retry N times)Resubscribes to the source Publisher upon receiving an error signal, up to a specified number of times.Transient network errors: Automatically retrying an external HTTP call up to three times to overcome temporary network hiccups before giving up.
doOnError()Consumer<Throwable> (Side effect)Allows execution of a side effect (logging, metrics tracking) when an error occurs, without modifying or consuming the error itself. The error is still passed downstream.Logging exceptions: Recording the full stack trace and metrics to a monitoring system before the error is propagated up the pipeline to be handled by an exception handler.

4. 🔗 Backpressure and Hot/Cold Operators​

These manage resource flow and execution model.

OperatorSignature & DescriptionKey DifferenceReal-World Use Case
subscribeOn()Scheduler (Where execution starts)Determines the Scheduler (thread) on which the entire source execution pipeline begins. Crucial for moving blocking operations off the main Event Loop.Moving Blocking Code: Ensuring a blocking JDBC call or a CPU-intensive synchronous task runs on Schedulers.boundedElastic().
publishOn()Scheduler (Where subsequent ops run)Changes the Scheduler used by all operators downstream of this call. Does not affect the source.Context Switching: After a heavy calculation, switching back to Schedulers.parallel() for non-blocking operations to maximize efficiency.
share()Mono<T> -> Mono<T> (Multi-subscription)Allows multiple subscribers to share a single subscription to the source Publisher, ensuring the source logic is executed only once.Caching a slow computation: Executing an expensive initialization task (e.g., loading a large configuration file) once, then providing that result to dozens of services without re-running the load logic.
delayElements()Duration (Time-based pacing)Introduces a delay between the emissions of elements, effectively implementing backpressure by time.Throttling a data stream: Pacing a fast stream of data to match the input rate required by a slower downstream component (like a legacy API with strict rate limits).

Deepseek

Spring WebFlux Operators: Comprehensive Guide

Reactive Programming Operators Deep Dive​


Table of Contents​

  1. Core Concepts & Reactor Basics
  2. Creation Operators
  3. Transformation Operators
  4. Filtering Operators
  5. Combining Operators
  6. Error Handling Operators
  7. Utility Operators
  8. Schedulers & Threading
  9. Backpressure Operators
  10. Real-World Patterns

1. Core Concepts & Reactor Basics​

Reactive Streams Specification​

// Core Interfaces
Publisher<T> // Emits data
Subscriber<T> // Consumes data
Subscription // Controls flow (backpressure)
Processor<T,R> // Both publisher and subscriber

// Reactor Implementations
Mono<T> // 0-1 element
Flux<T> // 0-N elements

Cold vs Hot Publishers​

// COLD: Each subscriber gets fresh data stream
Flux<Integer> coldFlux = Flux.range(1, 5)
.doOnSubscribe(s -> System.out.println("New subscription"));

coldFlux.subscribe(); // Prints: New subscription
coldFlux.subscribe(); // Prints: New subscription (again)

// HOT: Shares data among subscribers
ConnectableFlux<Integer> hotFlux = Flux.interval(Duration.ofSeconds(1))
.publish(); // Convert to hot publisher

hotFlux.connect(); // Start emitting
hotFlux.subscribe(v -> System.out.println("Sub1: " + v));
Thread.sleep(3000);
hotFlux.subscribe(v -> System.out.println("Sub2: " + v)); // Misses first 3 values

// Use case: Real-time stock prices
@RestController
public class StockController {
private final ConnectableFlux<StockPrice> priceStream;

public StockController() {
this.priceStream = Flux.interval(Duration.ofMillis(100))
.map(tick -> fetchStockPrice())
.publish();
this.priceStream.connect();
}

@GetMapping("/prices")
public Flux<StockPrice> streamPrices() {
return priceStream;
}
}

2. Creation Operators​

Static Creation Methods​

// 1. just() - Fixed values
Mono.just("Hello")
Flux.just("A", "B", "C")

// 2. empty() - Complete without value
Mono.empty() // Completes immediately
Flux.empty() // Completes immediately

// 3. error() - Complete with error
Mono.error(new RuntimeException("Failed"))
Flux.error(new RuntimeException("Failed"))

// 4. never() - Never completes (for testing)
Mono.never()
Flux.never()

// 5. from...() - From existing sources
Flux.fromIterable(List.of(1, 2, 3))
Flux.fromStream(Stream.of(1, 2, 3))
Flux.fromArray(new Integer[]{1, 2, 3})
Mono.fromFuture(CompletableFuture.supplyAsync(() -> "result"))
Mono.fromCallable(() -> database.query())
Mono.fromRunnable(() -> cleanup()) // Returns Mono<Void>

// 6. range() - Number sequence
Flux.range(1, 10) // 1,2,3,...,10

// 7. interval() - Periodic emissions
Flux.interval(Duration.ofSeconds(1)) // 0,1,2,3,... every second
.take(5) // 0,1,2,3,4

// 8. defer() - Deferred creation (per subscription)
Flux.defer(() -> {
if (System.currentTimeMillis() % 2 == 0) {
return Flux.just("Even");
} else {
return Flux.just("Odd");
}
});
// Each subscription gets potentially different result

// REAL-WORLD: Database connection per request
public Mono<User> getUser(String id) {
return Mono.defer(() -> {
// Create new connection per subscription
return Mono.fromCallable(() -> userRepository.findById(id))
.subscribeOn(Schedulers.boundedElastic());
});
}

Programmatic Creation​

// 9. create() - Bridge with callback APIs
Flux.create(sink -> {
// Bridge to event-based APIs
EventListener listener = event -> {
sink.next(event.getData());
if (event.isComplete()) {
sink.complete();
}
};
eventSource.register(listener);

// Cleanup on cancel
sink.onCancel(() -> eventSource.unregister(listener));
sink.onDispose(() -> eventSource.unregister(listener));
});

// REAL-WORLD: WebSocket to Flux bridge
public Flux<Message> createWebSocketStream(WebSocketSession session) {
return Flux.create(sink -> {
session.sendMessage(new TextMessage("CONNECTED"));

session.addHandler(new WebSocketHandler() {
@Override
public void handleMessage(WebSocketSession session, WebSocketMessage<?> message) {
sink.next(convert(message));
}

@Override
public void afterConnectionClosed(WebSocketSession session, CloseStatus status) {
sink.complete();
}
});

sink.onDispose(() -> session.close());
});
}

// 10. generate() - Synchronous, stateful generation
Flux.generate(
() -> 0, // Initial state
(state, sink) -> {
sink.next("Value: " + state);
if (state == 10) {
sink.complete();
}
return state + 1; // New state
}
);

// 11. push() - Single-threaded async generation (like create but single-threaded)
Flux.push(sink -> {
// For single-threaded producers
singleThreadedEventEmitter.onData(data -> sink.next(data));
singleThreadedEventEmitter.onComplete(() -> sink.complete());
});

// 12. using() - Resource management
Flux.using(
() -> database.getConnection(), // Resource supplier
connection -> Flux.fromIterable(connection.query()), // Flux factory
connection -> connection.close() // Cleanup
);

3. Transformation Operators​

Element Transformation​

// 1. map() - Synchronous 1:1 transformation
Flux<Integer> numbers = Flux.range(1, 5);
Flux<String> strings = numbers.map(n -> "Number: " + n);
// 1 → "Number: 1", 2 → "Number: 2", ...

// 2. flatMap() - Asynchronous 1:N transformation
Flux<User> users = Flux.just("user1", "user2", "user3");
Flux<Order> orders = users.flatMap(username ->
orderRepository.findByUser(username) // Returns Flux<Order>
);
// Concatenates all inner Flux emissions

// 3. concatMap() - Preserves order (slower)
users.concatMap(username ->
orderRepository.findByUser(username)
);
// Waits for each inner Flux to complete before starting next

// 4. flatMapSequential() - Preserves source order but subscribes eagerly
users.flatMapSequential(username ->
orderRepository.findByUser(username)
);

// REAL-WORLD: Parallel API calls with ordering
public Flux<Product> getProductsWithReviews(List<String> productIds) {
return Flux.fromIterable(productIds)
.flatMap(id ->
productService.getProduct(id) // Mono<Product>
.flatMap(product ->
reviewService.getReviews(id) // Mono<List<Review>>
.map(reviews -> {
product.setReviews(reviews);
return product;
})
)
);
}

// 5. switchMap() - Cancels previous inner publisher
searchInputFlux
.debounce(Duration.ofMillis(300))
.switchMap(query ->
searchService.search(query) // Cancels previous search if new query arrives
);

// 6. transform() - Operator composition
Function<Flux<String>, Flux<String>> filterAndTransform =
flux -> flux
.filter(s -> !s.isEmpty())
.map(String::toUpperCase);

Flux<String> result = Flux.just("hello", "", "world")
.transform(filterAndTransform);

Flattening Operators​

// 7. flatMap vs flatMapMany
Mono<List<Integer>> monoList = Mono.just(List.of(1, 2, 3));
Flux<Integer> flux = monoList.flatMapMany(Flux::fromIterable);

// 8. concatMap vs flatMap comparison
Flux.just(1, 2, 3)
.flatMap(i ->
Mono.just(i * 10)
.delayElement(Duration.ofMillis(i * 100))
);
// Output order: 10, 20, 30 (may vary due to delays)

Flux.just(1, 2, 3)
.concatMap(i ->
Mono.just(i * 10)
.delayElement(Duration.ofMillis(i * 100))
);
// Output order: 10, 20, 30 (guaranteed order)

// REAL-WORLD: File processing with backpressure
public Flux<String> processLargeFile(String filePath) {
return Flux.using(
() -> Files.lines(Paths.get(filePath)),
Flux::fromStream,
Stream::close
)
.flatMap(line ->
Mono.fromCallable(() -> expensiveProcessing(line))
.subscribeOn(Schedulers.boundedElastic()),
5 // Maximum concurrency
);
}

// 9. groupBy() - Group elements by key
Flux<Transaction> transactions = getTransactions();
Flux<GroupedFlux<String, Transaction>> grouped =
transactions.groupBy(tx -> tx.getCategory());

grouped.flatMap(group ->
group
.buffer(Duration.ofSeconds(1))
.map(list -> new CategorySummary(group.key(), list))
);

// 10. window() - Split into windows
Flux.range(1, 100)
.window(10) // Flux<Flux<Integer>> with windows of size 10
.flatMap(window ->
window.reduce(0, Integer::sum)
.map(sum -> "Window sum: " + sum)
);

// Time-based windowing
Flux.interval(Duration.ofMillis(100))
.window(Duration.ofSeconds(1))
.flatMap(window -> window.count())
.subscribe(count -> System.out.println("Events per second: " + count));

Buffering & Windowing​

// 1. buffer() - Collect into lists
Flux.range(1, 10)
.buffer(3) // [1,2,3], [4,5,6], [7,8,9], [10]
.subscribe(list -> System.out.println(list));

// 2. bufferTimeout() - Size OR time based
messageFlux
.bufferTimeout(100, Duration.ofSeconds(1))
.subscribe(batch -> batchProcessor.process(batch));

// 3. bufferWhile() / bufferUntil()
Flux<Integer> numbers = Flux.range(1, 10);
numbers.bufferWhile(n -> n % 2 == 0); // Buffer while even
numbers.bufferUntil(n -> n % 3 == 0); // Buffer until divisible by 3

// REAL-WORLD: Batch database inserts
public Mono<Void> saveMessages(Flux<Message> messages) {
return messages
.buffer(100) // Batch size
.delayElements(Duration.ofMillis(100)) // Throttle
.flatMap(batch ->
Mono.fromRunnable(() -> batchInsert(batch))
.subscribeOn(Schedulers.boundedElastic()),
3 // Max concurrent batches
)
.then();
}

// 4. window() vs buffer()
Flux<Integer> source = Flux.range(1, 10);
source.buffer(3); // Returns Flux<List<Integer>>
source.window(3); // Returns Flux<Flux<Integer>>

// 5. windowUntilChanged() - Window on changing values
Flux.just(1, 1, 2, 2, 1, 3, 3)
.windowUntilChanged()
.flatMap(window -> window.collectList())
// Windows: [1,1], [2,2], [1], [3,3]

4. Filtering Operators​

Basic Filtering​

// 1. filter() - Predicate-based filtering
Flux<Integer> numbers = Flux.range(1, 10);
Flux<Integer> even = numbers.filter(n -> n % 2 == 0);

// 2. ignoreElements() - Ignore all, just completion/error
Mono<Void> completion = Flux.just(1, 2, 3)
.ignoreElements(); // Only onComplete/onError signals

// 3. distinct() - Remove duplicates
Flux.just(1, 2, 2, 3, 1, 4)
.distinct() // 1, 2, 3, 4

// 4. distinctUntilChanged() - Remove consecutive duplicates
Flux.just(1, 1, 2, 2, 1, 1)
.distinctUntilChanged() // 1, 2, 1

// REAL-WORLD: Rate limiting duplicate requests
public Flux<Response> handleRequests(Flux<Request> requests) {
return requests
.distinct(Request::getId) // Ignore duplicate IDs
.filter(req -> !isBlocked(req.getIp()))
.flatMap(this::processRequest);
}

Taking & Skipping​

// 1. take(n) - Take first N elements
Flux.range(1, 100).take(5); // 1,2,3,4,5

// 2. takeLast(n) - Take last N elements
Flux.range(1, 100).takeLast(5); // 96,97,98,99,100

// 3. takeWhile(predicate) - Take while true
Flux.range(1, 10)
.takeWhile(n -> n < 5); // 1,2,3,4

// 4. takeUntil(predicate) - Take until true (inclusive)
Flux.range(1, 10)
.takeUntil(n -> n == 5); // 1,2,3,4,5

// 5. skip(n) - Skip first N elements
Flux.range(1, 10).skip(5); // 6,7,8,9,10

// 6. skipLast(n) - Skip last N elements
Flux.range(1, 10).skipLast(5); // 1,2,3,4,5

// 7. skipWhile(predicate) - Skip while true
Flux.range(1, 10)
.skipWhile(n -> n < 5); // 5,6,7,8,9,10

// 8. skipUntil(predicate) - Skip until true
Flux.range(1, 10)
.skipUntil(n -> n == 5); // 5,6,7,8,9,10

// REAL-WORLD: Pagination with take/skip
public Flux<User> getUsers(int page, int size) {
return userRepository.findAll()
.skip(page * size)
.take(size);
}

// 9. takeDuration() / skipDuration() - Time-based
Flux.interval(Duration.ofMillis(100))
.take(Duration.ofSeconds(1)) // Take for 1 second
.subscribe();

// 10. elementAt() - Get element at index
Flux.range(1, 10)
.elementAt(5); // Mono with value 6

Sampling & Throttling​

// 1. sample(Duration) - Last element in time window
Flux.interval(Duration.ofMillis(100))
.sample(Duration.ofSeconds(1)) // Emit last value every second
.subscribe(System.out::println);

// 2. sampleFirst(Duration) - First element in time window
messageFlux.sampleFirst(Duration.ofMillis(100));

// 3. sampleTimeout() - Sample with dynamic duration
Flux.interval(Duration.ofMillis(100))
.sampleTimeout(
v -> Mono.delay(Duration.ofMillis(50 + v * 10))
);

// 4. throttleFirst / throttleLast (alias for sample)
Flux.interval(Duration.ofMillis(50))
.throttleFirst(Duration.ofSeconds(1)) // First in window
.throttleLast(Duration.ofSeconds(1)) // Last in window (same as sample)

// REAL-WORLD: UI event throttling
@Component
public class SearchService {
public Flux<Result> search(Flux<String> queries) {
return queries
.filter(query -> query.length() > 2)
.debounce(Duration.ofMillis(300)) // Wait for pause
.distinctUntilChanged() // Ignore same query
.switchMap(this::executeSearch); // Cancel previous
}
}

// 5. debounce - Wait for quiet period
buttonClickFlux
.debounce(Duration.ofMillis(250)) // Prevent double clicks
.subscribe(this::handleClick);

5. Combining Operators​

Sequential Combination​

// 1. concatWith() - Sequential concatenation
Flux<Integer> flux1 = Flux.just(1, 2, 3);
Flux<Integer> flux2 = Flux.just(4, 5, 6);
flux1.concatWith(flux2); // 1,2,3,4,5,6

// 2. concat() - Static version
Flux.concat(flux1, flux2, Flux.just(7, 8));

// 3. concatDelayError() - Delay errors until end
Flux.concatDelayError(
Flux.just(1, 2).concatWith(Mono.error(new RuntimeException())),
Flux.just(3, 4)
); // Emits: 1,2,3,4 then error

// REAL-WORLD: Fallback service calls
public Flux<Product> getProducts(String category) {
return primaryService.getProducts(category)
.concatWith(secondaryService.getProducts(category))
.take(10); // Get up to 10 from either source
}

Parallel Combination​

// 1. mergeWith() - Interleave emissions
Flux<Integer> flux1 = Flux.interval(Duration.ofMillis(100))
.map(i -> i * 2);
Flux<Integer> flux2 = Flux.interval(Duration.ofMillis(150))
.map(i -> i * 2 + 1);

flux1.mergeWith(flux2); // Interleaved: 0,1,2,3,4,5,...

// 2. merge() - Static version
Flux.merge(flux1, flux2, flux3);

// 3. mergeSequential() - Subscribe in order, emit as arrive
Flux.mergeSequential(flux1, flux2); // Maintains subscription order

// 4. mergeOrdered() - Merge with ordering
Flux.mergeOrdered(
Comparator.naturalOrder(),
flux1, flux2
);

// REAL-WORLD: Aggregating multiple data sources
public Flux<StockPrice> getAllStockPrices(List<String> symbols) {
return Flux.fromIterable(symbols)
.flatMap(symbol ->
stockService.getPriceStream(symbol),
5 // Max concurrent subscriptions
);
}

Pairing Operators​

// 1. zipWith() - Pair-wise combination
Flux<Integer> numbers = Flux.range(1, 3);
Flux<String> letters = Flux.just("A", "B", "C");

numbers.zipWith(letters, (n, l) -> n + l);
// [1A, 2B, 3C]

// 2. zip() - Static version
Flux.zip(numbers, letters, more)
.map(tuple -> tuple.getT1() + tuple.getT2());

// 3. zip with combinator
Flux.zip(
obj -> new Combined((String)obj[0], (Integer)obj[1]),
flux1, flux2
);

// REAL-WORLD: Parallel API calls with aggregation
public Mono<UserProfile> getUserProfile(String userId) {
return Mono.zip(
userService.getUser(userId),
orderService.getOrders(userId),
paymentService.getPaymentMethods(userId)
).map(tuple -> new UserProfile(
tuple.getT1(),
tuple.getT2(),
tuple.getT3()
));
}

// 4. combineLatest - Latest from each
Flux.combineLatest(
flux1, flux2,
(v1, v2) -> v1 + " - " + v2
);

// REAL-WORLD: Real-time dashboard
public Flux<DashboardData> getDashboard() {
return Flux.combineLatest(
cpuMetrics,
memoryMetrics,
networkMetrics,
(cpu, memory, network) -> new DashboardData(cpu, memory, network)
);
}

Race Conditions​

// 1. firstWithSignal / firstWithValue - Race to emit
Mono<String> cache = getFromCache(key);
Mono<String> db = getFromDatabase(key);

Mono.firstWithSignal(cache, db) // First to emit any signal
.subscribe();

Mono.firstWithValue(cache, db) // First to emit a value
.subscribe();

// REAL-WORLD: Circuit breaker with fallbacks
public Mono<Response> callWithFallback(Request request) {
return primaryService.call(request)
.timeout(Duration.ofSeconds(2))
.onErrorResume(e ->
Mono.firstWithValue(
secondaryService.call(request),
Mono.just(Response.fallback())
)
);
}

// 2. amb (deprecated, use firstWithSignal)
Flux.firstWithSignal(source1, source2, source3);

6. Error Handling Operators​

Error Recovery​

// 1. onErrorReturn - Provide fallback value
Flux.just(1, 2, 3)
.map(n -> {
if (n == 2) throw new RuntimeException("Boom!");
return n;
})
.onErrorReturn(0); // 1, 0

// 2. onErrorResume - Switch to fallback publisher
Flux.error(new RuntimeException("Failed"))
.onErrorResume(e ->
Flux.just("fallback1", "fallback2")
);

// 3. onErrorContinue - Continue with next element
Flux.just(1, 2, 3, 4)
.map(n -> {
if (n == 3) throw new RuntimeException("Skip 3");
return n * 10;
})
.onErrorContinue((e, obj) ->
log.error("Skipped {} due to {}", obj, e.getMessage())
); // 10, 20, 40

// REAL-WORLD: Resilient API calls
public Flux<Product> getProductsWithRetry(List<String> ids) {
return Flux.fromIterable(ids)
.flatMap(id ->
productService.getProduct(id)
.onErrorResume(e -> {
log.warn("Failed for {}, trying fallback", id);
return fallbackService.getProduct(id);
})
.onErrorResume(e -> {
log.error("Complete failure for {}", id);
return Mono.just(Product.unavailable(id));
})
);
}

Retry Strategies​

// 1. retry() - Simple retry
Flux.error(new RuntimeException())
.retry(3); // Retry 3 times

// 2. retryWhen - Advanced retry with backoff
Flux.error(new RuntimeException())
.retryWhen(Retry.backoff(3, Duration.ofSeconds(1))
.maxBackoff(Duration.ofSeconds(10))
.jitter(0.5) // Add randomness
.doBeforeRetry(retrySignal ->
log.warn("Retrying attempt {}", retrySignal.totalRetries())
)
.onRetryExhaustedThrow((spec, signal) ->
new ServiceUnavailableException("Max retries exceeded")
)
);

// 3. retryWhen with predicate
.retryWhen(Retry.fixedDelay(5, Duration.ofSeconds(1))
.filter(e -> e instanceof TimeoutException)
.doBeforeRetry(retrySignal -> {
if (retrySignal.totalRetries() > 2) {
refreshConnection();
}
})
);

// REAL-WORLD: Exponential backoff for external APIs
private RetrySpec apiRetrySpec() {
return Retry.backoff(5, Duration.ofSeconds(1))
.maxBackoff(Duration.ofMinutes(1))
.transientErrors(true) // Retry on 5xx errors
.doBeforeRetry(retry ->
metrics.recordRetry(retry.failure())
)
.onRetryExhaustedThrow((spec, signal) ->
new ApiException("Service unavailable after retries")
);
}

public Mono<Response> callExternalApi(Request request) {
return webClient.post()
.bodyValue(request)
.retrieve()
.bodyToMono(Response.class)
.retryWhen(apiRetrySpec());
}

Timeout & Fallback​

// 1. timeout - Timeout with fallback
Flux.interval(Duration.ofSeconds(2))
.timeout(Duration.ofSeconds(1))
.onErrorResume(TimeoutException.class, e ->
Flux.just(-1L)
);

// 2. timeout with fallback publisher
slowFlux
.timeout(Duration.ofSeconds(1), fallbackFlux)
.subscribe();

// REAL-WORLD: Service call with timeout cascade
public Mono<Response> callServiceWithTimeouts(Request req) {
return primaryService.call(req)
.timeout(Duration.ofMillis(100))
.onErrorResume(TimeoutException.class, e ->
secondaryService.call(req)
.timeout(Duration.ofMillis(200))
)
.onErrorResume(TimeoutException.class, e ->
tertiaryService.call(req)
.timeout(Duration.ofMillis(500))
)
.onErrorReturn(Response.fallback());
}

Error Classification​

// 1. onErrorMap - Transform error
Flux.error(new IOException("Connection failed"))
.onErrorMap(IOException.class, e ->
new ServiceException("Service unavailable", e)
);

// 2. onErrorMap with predicate
.onErrorMap(e -> e.getMessage().contains("timeout"),
e -> new TimeoutException("Operation timed out")
);

// 3. doOnError - Side effect on error
Flux.error(new RuntimeException())
.doOnError(e ->
metrics.incrementError(e.getClass().getSimpleName())
)
.onErrorResume(e -> Mono.empty());

// REAL-WORLD: Circuit breaker pattern
@Component
public class CircuitBreakerService {
private final CircuitBreaker circuitBreaker;

public Flux<Data> getDataWithCircuitBreaker() {
return Flux.defer(() -> externalService.getData())
.transformDeferred(circuitBreaker::run)
.onErrorResume(CallNotPermittedException.class, e ->
Flux.error(new ServiceUnavailableException())
);
}
}

7. Utility Operators​

Side Effects​

// 1. doOnNext - Peek at values
Flux.range(1, 5)
.doOnNext(n -> System.out.println("Processing: " + n))
.map(n -> n * 2)
.subscribe();

// 2. doOnComplete - On completion
Flux.just(1, 2, 3)
.doOnComplete(() -> System.out.println("Done!"))
.subscribe();

// 3. doOnError - On error
Flux.error(new RuntimeException())
.doOnError(e -> log.error("Failed", e))
.subscribe();

// 4. doOnSubscribe / doOnCancel / doOnRequest
Flux.range(1, 10)
.doOnSubscribe(s -> System.out.println("Subscribed"))
.doOnRequest(n -> System.out.println("Requested: " + n))
.doOnCancel(() -> System.out.println("Cancelled"))
.subscribe();

// REAL-WORLD: Request logging
@RestController
public class ApiController {
@GetMapping("/data")
public Flux<Data> getData() {
return dataService.getData()
.doOnSubscribe(s ->
log.info("Request started at {}", Instant.now())
)
.doOnComplete(() ->
log.info("Request completed successfully")
)
.doOnError(e ->
log.error("Request failed", e)
);
}
}

Debugging & Metrics​

// 1. log() - Log all signals
Flux.range(1, 3)
.log("my.flux")
.subscribe();

// Output:
// [my.flux] onSubscribe(FluxRange.RangeSubscription)
// [my.flux] request(unbounded)
// [my.flux] onNext(1)
// [my.flux] onNext(2)
// [my.flux] onNext(3)
// [my.flux] onComplete()

// 2. checkpoint - Add trace for debugging
Flux.error(new RuntimeException("Oops"))
.checkpoint("errorSource")
.subscribe();

// Stack trace includes "errorSource" marker

// 3. metrics - Micrometer integration
Flux.range(1, 100)
.name("myFlux")
.metrics()
.subscribe();

// REAL-WORLD: Production monitoring
public Flux<Event> processEvents(Flux<Event> events) {
return events
.name("event.processor")
.tag("type", "kafka")
.metrics() // Exposes metrics to Micrometer
.doOnNext(event ->
Metrics.counter("events.processed").increment()
)
.doOnError(e ->
Metrics.counter("events.failed").increment()
);
}

Conditional Operators​

// 1. hasElements / hasElement
Mono<Boolean> hasData = Flux.just(1, 2, 3).hasElements();
Mono<Boolean> hasTwo = Flux.just(1, 2, 3).hasElement(2);

// 2. any / all
Mono<Boolean> anyEven = Flux.just(1, 3, 5).any(n -> n % 2 == 0);
Mono<Boolean> allPositive = Flux.just(1, 2, 3).all(n -> n > 0);

// 3. defaultIfEmpty
Flux.empty()
.defaultIfEmpty("default"); // Emits "default"

// 4. switchIfEmpty
Flux.empty()
.switchIfEmpty(Flux.just("fallback", "values"));

// REAL-WORLD: Cache with fallback
public Mono<User> getUser(String id) {
return cache.get(id)
.switchIfEmpty(
database.getUser(id)
.doOnNext(user -> cache.set(id, user))
)
.defaultIfEmpty(User.anonymous());
}

Collecting & Reducing​

// 1. collectList / collectMap / collectMultimap
Flux.just("a", "b", "c")
.collectList() // Mono<List<String>>
.subscribe();

Flux.just(
new Pair("key1", "value1"),
new Pair("key2", "value2")
).collectMap(Pair::getKey, Pair::getValue);

// 2. reduce - Accumulate values
Flux.range(1, 5)
.reduce(0, Integer::sum); // Mono with value 15

// 3. scan - Emit accumulation steps
Flux.range(1, 5)
.scan(0, Integer::sum); // 0,1,3,6,10,15

// 4. count
Flux.just("a", "b", "c").count(); // Mono with value 3

// REAL-WORLD: Real-time analytics
public Flux<AggregatedStats> streamStats(Flux<Event> events) {
return events
.window(Duration.ofSeconds(5))
.flatMap(window ->
window
.reduce(new StatsAccumulator(), StatsAccumulator::add)
.map(StatsAccumulator::toStats)
);
}

8. Schedulers & Threading​

Scheduler Types​

// 1. Schedulers.immediate() - Current thread
// 2. Schedulers.single() - Single dedicated thread
// 3. Schedulers.elastic() - Deprecated, use boundedElastic
// 4. Schedulers.boundedElastic() - For blocking I/O
// 5. Schedulers.parallel() - For CPU-intensive work
// 6. Schedulers.fromExecutorService() - Custom executor

// REAL-WORLD: Threading strategy by operation type
public Mono<Result> process(Request request) {
return validate(request) // Fast, use immediate
.flatMap(validated ->
Mono.fromCallable(() -> blockingIO(validated))
.subscribeOn(Schedulers.boundedElastic())
)
.flatMap(ioResult ->
Mono.fromCallable(() -> cpuIntensive(ioResult))
.subscribeOn(Schedulers.parallel())
)
.publishOn(Schedulers.single()) // Switch back to single thread
.doOnNext(result ->
// UI updates or single-threaded operations
updateUI(result)
);
}

Threading Operators​

// 1. subscribeOn - Where subscription happens
Flux.range(1, 10)
.map(n -> {
System.out.println("Map on: " + Thread.currentThread().getName());
return n * 2;
})
.subscribeOn(Schedulers.parallel())
.subscribe();

// 2. publishOn - Switch threads downstream
Flux.range(1, 10)
.map(n -> n * 2) // On subscription thread
.publishOn(Schedulers.single())
.map(n -> n + 1) // On single thread
.subscribe();

// 3. parallel / runOn - Parallel processing
Flux.range(1, 100)
.parallel(4) // Split into 4 rails
.runOn(Schedulers.parallel())
.map(n -> n * 2)
.sequential(); // Merge back to single Flux

// REAL-WORLD: Image processing pipeline
public Flux<ProcessedImage> processImages(Flux<Image> images) {
return images
.parallel(4) // 4 parallel lanes
.runOn(Schedulers.parallel()) // Each lane on parallel scheduler
.map(this::detectEdges) // CPU-intensive
.sequential() // Back to single flux
.publishOn(Schedulers.boundedElastic())
.flatMap(this::saveToStorage) // I/O intensive
.publishOn(Schedulers.single())
.doOnNext(this::notifyUI);
}

Context Propagation​

// 1. contextWrite - Write to Context
Flux.just("Hello")
.flatMap(word ->
Mono.deferContextual(ctx ->
Mono.just(word + " " + ctx.get("user"))
)
)
.contextWrite(Context.of("user", "Alice"))
.subscribe(System.out::println); // Hello Alice

// 2. transformDeferredContextual
Flux.range(1, 5)
.transformDeferredContextual((flux, ctx) ->
flux.map(n -> n + ctx.getOrDefault("offset", 0))
)
.contextWrite(Context.of("offset", 100))
.subscribe(); // 101, 102, 103, 104, 105

// REAL-WORLD: Request tracing
@Component
public class TracingFilter implements WebFilter {
@Override
public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
return chain.filter(exchange)
.contextWrite(Context.of(
"traceId", exchange.getRequest().getId(),
"userId", extractUserId(exchange)
));
}
}

@RestController
public class ApiController {
@GetMapping("/data")
public Mono<Data> getData() {
return Mono.deferContextual(ctx -> {
String traceId = ctx.get("traceId");
return dataService.getData()
.doOnSubscribe(s ->
log.info("Trace {}: Started", traceId)
);
});
}
}

9. Backpressure Operators​

Backpressure Strategies​

// 1. onBackpressureBuffer - Buffer with limits
Flux.range(1, 1000)
.onBackpressureBuffer(
100, // Buffer size
BufferOverflowStrategy.DROP_OLDEST, // Strategy
buffer -> log.warn("Buffer overflow: {}", buffer.size())
)
.subscribe();

// 2. onBackpressureDrop - Drop excess
fastProducer
.onBackpressureDrop(dropped ->
metrics.recordDropped(dropped)
)
.subscribe(slowConsumer);

// 3. onBackpressureLatest - Keep only latest
realTimeData
.onBackpressureLatest()
.subscribe(uiUpdater);

// 4. onBackpressureError - Error on overflow
Flux.interval(Duration.ofMillis(10))
.onBackpressureError()
.subscribe(
System.out::println,
e -> log.error("Backpressure overflow", e)
);

// REAL-WORLD: Adaptive backpressure
public Flux<Data> adaptBackpressure(Flux<Data> source, Consumer<Data> processor) {
return source
.onBackpressureBuffer(
1000,
BufferOverflowStrategy.DROP_OLDEST,
buffer -> {
if (buffer.size() > 800) {
// Slow down producer
adjustProducerRate(0.5);
}
}
)
.doOnNext(processor)
.doOnRequest(n -> {
// Increase rate when buffer is low
if (getBufferSize() < 200) {
adjustProducerRate(1.5);
}
});
}

Request Management​

// 1. limitRequest - Limit total request
Flux.range(1, 100)
.limitRequest(10) // Only request 10 elements
.subscribe();

// 2. limitRate - Control request batches
Flux.range(1, 1000)
.limitRate(100, 50) // Request 100, replenish at 50
.subscribe();

// 3. subscribe with request
Flux.range(1, 100)
.subscribe(
new BaseSubscriber<Integer>() {
@Override
protected void hookOnSubscribe(Subscription subscription) {
request(10); // Request first 10
}

@Override
protected void hookOnNext(Integer value) {
process(value);
if (value % 10 == 0) {
request(10); // Request more in batches
}
}
}
);

// REAL-WORLD: File streaming with backpressure
public Flux<ByteBuffer> streamFile(String path, int chunkSize) {
return Flux.using(
() -> Files.newInputStream(Paths.get(path)),
in -> {
byte[] buffer = new byte[chunkSize];
return Flux.generate(sink -> {
try {
int read = in.read(buffer);
if (read == -1) {
sink.complete();
} else if (read < buffer.length) {
sink.next(ByteBuffer.wrap(buffer, 0, read));
} else {
sink.next(ByteBuffer.wrap(buffer));
}
} catch (IOException e) {
sink.error(e);
}
});
},
in -> {
try { in.close(); } catch (IOException e) { }
}
);
}

10. Real-World Patterns​

Pattern 1: API Gateway Aggregation​

@RestController
public class AggregationController {

@GetMapping("/user-dashboard/{userId}")
public Mono<Dashboard> getUserDashboard(@PathVariable String userId) {
return Mono.zip(
userService.getUser(userId).subscribeOn(Schedulers.boundedElastic()),
orderService.getOrders(userId).collectList().subscribeOn(Schedulers.boundedElastic()),
paymentService.getPayments(userId).collectList().subscribeOn(Schedulers.boundedElastic()),
notificationService.getNotifications(userId).collectList().subscribeOn(Schedulers.boundedElastic())
)
.map(tuple -> new Dashboard(
tuple.getT1(),
tuple.getT2(),
tuple.getT3(),
tuple.getT4()
))
.timeout(Duration.ofSeconds(3))
.onErrorResume(e ->
fallbackDashboardService.getDashboard(userId)
);
}

@GetMapping("/search")
public Flux<Product> searchProducts(
@RequestParam String query,
@RequestParam(defaultValue = "10") int limit
) {
return Flux.merge(
productService.search(query).take(limit),
inventoryService.search(query).take(limit)
)
.distinct(Product::getId)
.sort(Comparator.comparing(Product::getScore).reversed())
.take(limit);
}
}

Pattern 2: Event-Driven Processing​

@Component
public class EventProcessor {

private final Flux<Event> eventStream;
private final Sinks.Many<Event> sink = Sinks.many().multicast().onBackpressureBuffer(1000);

public EventProcessor() {
this.eventStream = sink.asFlux()
.publishOn(Schedulers.parallel())
.name("event.processor")
.metrics();
}

public void processEvent(Event event) {
sink.tryEmitNext(event);
}

@PostConstruct
public void init() {
eventStream
.window(Duration.ofSeconds(1), Duration.ofMillis(500))
.flatMap(window ->
window
.groupBy(Event::getType)
.flatMap(group ->
group
.bufferTimeout(100, Duration.ofMillis(500))
.flatMap(this::processBatch)
)
)
.subscribe(
result -> log.debug("Processed: {}", result),
error -> log.error("Processing failed", error)
);
}

private Mono<ProcessResult> processBatch(List<Event> batch) {
return Mono.fromCallable(() -> {
// Batch processing logic
return new ProcessResult(batch.size());
})
.subscribeOn(Schedulers.boundedElastic())
.timeout(Duration.ofSeconds(5))
.retryWhen(Retry.backoff(3, Duration.ofSeconds(1)));
}
}

Pattern 3: Reactive Caching​

@Component
public class ReactiveCache<K, V> {

private final Cache<K, Mono<V>> cache;
private final Function<K, Mono<V>> loader;

public ReactiveCache(Function<K, Mono<V>> loader, Duration ttl) {
this.loader = loader;
this.cache = Caffeine.newBuilder()
.expireAfterWrite(ttl)
.maximumSize(1000)
.recordStats()
.build();
}

public Mono<V> get(K key) {
return Mono.defer(() -> {
Mono<V> cached = cache.getIfPresent(key);
if (cached != null) {
return cached;
}

// Use computeIfAbsent to prevent duplicate loads
return cache.get(key, k ->
loader.apply(k)
.cache() // Cache the Mono result
.doOnError(e ->
cache.invalidate(k)
)
);
});
}

// Batch loading
public Flux<V> getAll(List<K> keys) {
return Flux.fromIterable(keys)
.flatMap(this::get, 10) // Concurrent loading
.collectList()
.flatMapMany(Flux::fromIterable);
}
}

// Usage in service
@Service
public class ProductService {
private final ReactiveCache<String, Product> cache;

public ProductService(ProductRepository repository) {
this.cache = new ReactiveCache<>(
repository::findById,
Duration.ofMinutes(5)
);
}

public Mono<Product> getProduct(String id) {
return cache.get(id)
.timeout(Duration.ofSeconds(1))
.onErrorResume(e ->
repository.findById(id) // Fallback to direct call
);
}
}

Pattern 4: WebFlux Security Chain​

@Component
public class SecurityChainFilter implements WebFilter {

@Override
public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
return extractToken(exchange)
.flatMap(this::validateToken)
.flatMap(auth ->
chain.filter(exchange)
.contextWrite(Context.of("auth", auth))
)
.switchIfEmpty(
chain.filter(exchange)
.contextWrite(Context.of("auth", Authentication.anonymous()))
)
.onErrorResume(AuthenticationException.class, e ->
handleUnauthorized(exchange, e)
);
}

private Mono<Authentication> validateToken(String token) {
return Mono.fromCallable(() ->
jwtDecoder.decode(token)
)
.subscribeOn(Schedulers.boundedElastic())
.timeout(Duration.ofSeconds(2))
.retryWhen(Retry.backoff(2, Duration.ofMillis(100)))
.map(decoded -> new Authentication(decoded.getSubject()))
.onErrorMap(e -> new AuthenticationException("Invalid token"));
}
}

@RestController
public class SecureController {

@GetMapping("/secure-data")
public Mono<SecureData> getSecureData() {
return Mono.deferContextual(ctx -> {
Authentication auth = ctx.get("auth");
if (!auth.hasRole("ADMIN")) {
return Mono.error(new AccessDeniedException());
}

return secureService.getData(auth.getUserId())
.timeout(Duration.ofSeconds(5))
.retryWhen(Retry.fixedDelay(2, Duration.ofSeconds(1)));
});
}
}

Pattern 5: Database Reactive Transactions​

@Service
@Transactional
public class OrderService {

private final R2dbcEntityTemplate template;
private final ReactiveTransactionManager txManager;

public Mono<Order> createOrder(OrderRequest request) {
return Mono.usingWhen(
TransactionSynchronizationManager.forCurrentTransaction()
.flatMap(status ->
Mono.from(txManager.getReactiveTransaction(txManager))
),
transaction -> {
// Execute in transaction
return template.insert(Order.class)
.using(new Order(request))
.flatMap(order ->
Flux.fromIterable(request.getItems())
.flatMap(item ->
template.insert(OrderItem.class)
.using(new OrderItem(order.getId(), item))
)
.then(Mono.just(order))
)
.flatMap(order ->
inventoryService.reserveItems(request.getItems())
.thenReturn(order)
)
.flatMap(order ->
paymentService.processPayment(request.getPayment())
.thenReturn(order)
);
},
transaction -> txManager.commit(transaction),
(transaction, err) -> txManager.rollback(transaction),
transaction -> txManager.rollback(transaction)
);
}

// Optimistic locking with retry
public Mono<Order> updateOrder(String orderId, OrderUpdate update) {
return Mono.defer(() ->
template.select(Order.class)
.from("orders")
.matching(Query.query(where("id").is(orderId))
.with(LockMode.PESSIMISTIC_WRITE))
.one()
.flatMap(order -> {
order.applyUpdate(update);
return template.update(Order.class)
.matching(where("id").is(orderId)
.and("version").is(order.getVersion()))
.apply(Update.update("status", order.getStatus())
.set("version", order.getVersion() + 1))
.flatMap(updated -> {
if (updated == 0) {
return Mono.error(new OptimisticLockingFailureException());
}
return Mono.just(order);
});
})
)
.retryWhen(Retry.backoff(3, Duration.ofMillis(100))
.filter(OptimisticLockingFailureException.class::isInstance));
}
}

Summary Cheat Sheet​

CategoryOperatorUse CaseWhen to Use
Creationjust, from, deferInitial dataStartup, bridging
Transformationmap, flatMap, concatMapData transformation1:1, 1:N, ordered async
Filteringfilter, take, skipData selectionConditional logic
Combiningmerge, concat, zipMultiple sourcesAggregation, parallelism
Error HandlingonErrorResume, retryWhenResilienceFallbacks, retries
UtilitydoOnNext, log, metricsObservabilityDebugging, monitoring
ThreadingsubscribeOn, publishOnConcurrency controlI/O vs CPU work
BackpressureonBackpressureBuffer, limitRateFlow controlFast producer, slow consumer

Golden Rules:​

  1. Use flatMap for async, concatMap for ordered async
  2. Prefer retryWhen over simple retry for production
  3. Use defer for lazy/conditional publisher creation
  4. Apply subscribeOn early, publishOn at switching points
  5. Always handle errors in reactive chains
  6. Use backpressure strategies for unbounded streams
  7. Monitor with metrics and structured logging
  8. Test with StepVerifier for reliable tests

WebFlux Deep Dive: Operators, Types, and Real-World Use Cases

· 7 min read
  1. Core Reactive Types
  2. Creation Operators
  3. Transformation Operators
  4. Combination Operators
  5. Error Handling Operators
  6. Scheduling & Threading
  7. Advanced Patterns

Core Reactive Types​

Mono - Single Result Container​

/**
* Mono represents a stream that emits 0 or 1 element
* Perfect for: HTTP responses, database saves, single calculations
*/
public class MonoDeepDive {

// Creation examples
public void monoCreation() {
// Empty Mono
Mono<String> empty = Mono.empty();

// From value
Mono<String> staticValue = Mono.just("Hello World");

// From nullable
String possiblyNull = getFromCache();
Mono<String> nullable = Mono.justOrEmpty(possiblyNull);

// From supplier (lazy)
Mono<String> lazy = Mono.fromSupplier(() -> expensiveOperation());

// From callable
Mono<String> fromCallable = Mono.fromCallable(() -> {
return database.getUser(userId); // Potentially blocking
});

// From future
CompletableFuture<String> future = asyncHttpCall();
Mono<String> fromFuture = Mono.fromFuture(future);
}

// Real-world use case: User profile lookup
public Mono<UserProfile> getUserProfile(String userId) {
return Mono.fromCallable(() -> userRepository.findById(userId))
.filter(Optional::isPresent)
.map(Optional::get)
.switchIfEmpty(Mono.error(new UserNotFoundException(userId)));
}
}

Flux - Multiple Results Stream​

/**
* Flux represents a stream that emits 0 to N elements
* Perfect for: Collections, real-time streams, paginated results
*/
public class FluxDeepDive {

// Creation examples
public void fluxCreation() {
// From values
Flux<String> fromValues = Flux.just("A", "B", "C");

// From array
Flux<String> fromArray = Flux.fromArray(new String[]{"A", "B", "C"});

// From iterable
Flux<String> fromList = Flux.fromIterable(Arrays.asList("A", "B", "C"));

// Range
Flux<Integer> numbers = Flux.range(1, 10);

// Interval (real-time stream)
Flux<Long> ticker = Flux.interval(Duration.ofSeconds(1));

// Generate (stateful stream)
Flux<Integer> fibonacci = Flux.generate(
() -> new int[]{0, 1}, // initial state
(state, sink) -> {
sink.next(state[0]);
int next = state[0] + state[1];
state[0] = state[1];
state[1] = next;
return state;
}
);
}

// Real-world use case: Real-time stock prices
public Flux<StockPrice> getStockPrices(String symbol) {
return Flux.interval(Duration.ofMillis(100))
.flatMap(tick ->
Mono.fromCallable(() -> stockService.getCurrentPrice(symbol))
.subscribeOn(Schedulers.boundedElastic())
)
.take(100); // Only take 100 price updates
}
}

Transformation Operators​

map vs flatMap - The Critical Difference​

public class TransformationOperators {

/**
* map: Synchronous 1:1 transformation
* Use when: Transformation is fast, non-blocking, CPU-bound
*/
public void mapOperator() {
Flux<String> names = Flux.just("john", "jane", "bob");

// Synchronous transformation - stays in same thread
Flux<String> capitalized = names.map(name -> name.toUpperCase());
// Output: JOHN, JANE, BOB

// Real-world: Data enrichment (fast)
Flux<User> users = getUserIds()
.map(id -> new User(id, "user-" + id));
}

/**
* flatMap: Asynchronous 1:N transformation
* Use when: Need to call async APIs, database, external services
*/
public void flatMapOperator() {
Flux<String> userIds = Flux.just("user1", "user2", "user3");

// Asynchronous transformation - can change threads
Flux<User> users = userIds.flatMap(id ->
userRepository.findByIdAsync(id) // Returns Mono<User>
);

// Real-world: Fetch user details from multiple services
Flux<Order> orders = getOrderIds()
.flatMap(orderId ->
orderService.getOrderAsync(orderId)
.onErrorResume(e -> Mono.empty()) // Skip failed orders
);
}

/**
* flatMapMany: Convert Mono to Flux
* Use when: You have Mono that emits multiple items
*/
public void flatMapManyOperator() {
Mono<String> csvData = readCsvFile();

// Convert Mono<String> to Flux<String[]>
Flux<String[]> rows = csvData.flatMapMany(content ->
Flux.fromArray(content.split("\n"))
.map(line -> line.split(","))
);

// Real-world: Get user and their recent activities
Mono<User> user = getUserProfile(userId);
Flux<Activity> activities = user.flatMapMany(u ->
activityService.getRecentActivities(u.getId())
);
}
}

Advanced Transformation Operators​

public class AdvancedTransformations {

/**
* concatMap vs flatMap - Ordering guarantee
*/
public void orderingGuarantees() {
Flux<String> ids = Flux.just("1", "2", "3");

// flatMap - no ordering guarantee (faster)
Flux<String> unordered = ids.flatMap(id ->
asyncOperation(id).delayElement(Duration.ofMillis(randomDelay()))
);

// concatMap - preserves order (slower but ordered)
Flux<String> ordered = ids.concatMap(id ->
asyncOperation(id).delayElement(Duration.ofMillis(randomDelay()))
);

// Real-world: Processing messages with ordering requirement
Flux<Message> kafkaMessages = kafkaReceiver.receive();
kafkaMessages
.concatMap(msg -> processMessage(msg)) // Maintain message order
.subscribe();
}

/**
* switchMap - Cancel previous emissions
*/
public void switchMapOperator() {
// Real-world: Search-as-you-type
Flux<String> searchTerms = keyPressEvents();

Flux<SearchResults> results = searchTerms
.debounce(Duration.ofMillis(300)) // Wait for typing to stop
.switchMap(term ->
searchService.search(term) // Cancel previous search if new term arrives
.timeout(Duration.ofSeconds(5))
);
}

/**
* groupBy - Group elements by key
*/
public void groupByOperator() {
// Real-world: Group orders by customer
Flux<Order> orders = orderStream();

Flux<GroupedFlux<String, Order>> byCustomer = orders
.groupBy(Order::getCustomerId);

// Process each customer's orders separately
byCustomer.flatMap(group ->
group
.window(Duration.ofMinutes(5)) // Window by time
.flatMap(window -> calculateCustomerStats(window))
).subscribe();
}
}

Combination Operators​

public class CombinationOperators {

/**
* zip - Combine multiple publishers
*/
public void zipOperator() {
Mono<User> user = getUser(userId);
Mono<Profile> profile = getProfile(userId);
Mono<Preferences> prefs = getPreferences(userId);

// Wait for all to complete, then combine
Mono<UserDashboard> dashboard = Mono.zip(user, profile, prefs)
.map(tuple -> {
User u = tuple.getT1();
Profile p = tuple.getT2();
Preferences pref = tuple.getT3();
return new UserDashboard(u, p, pref);
});

// Real-world: Aggregate data from multiple microservices
Mono<OrderDetails> orderDetails = Mono.zip(
orderService.getOrder(orderId),
paymentService.getPayment(orderId),
shippingService.getTracking(orderId)
).map(t -> OrderDetails.aggregate(t.getT1(), t.getT2(), t.getT3()));
}

/**
* merge vs concat - Parallel vs sequential combination
*/
public void mergeVsConcat() {
Flux<String> stream1 = Flux.just("A", "B", "C").delayElements(Duration.ofMillis(100));
Flux<String> stream2 = Flux.just("1", "2", "3").delayElements(Duration.ofMillis(50));

// merge - interleaves as they arrive (faster)
Flux<String> merged = Flux.merge(stream1, stream2);
// Possible output: 1, A, 2, B, 3, C

// concat - waits for first to complete (ordered)
Flux<String> concatenated = Flux.concat(stream1, stream2);
// Guaranteed output: A, B, C, 1, 2, 3
}

/**
* combineLatest - Combine latest from multiple streams
*/
public void combineLatest() {
// Real-world: Real-time dashboard with multiple data sources
Flux<Double> stockPrice = stockPriceStream();
Flux<Double> exchangeRate = exchangeRateStream();
Flux<News> newsFeed = newsStream();

Flux<Dashboard> dashboard = Flux.combineLatest(
Arrays::asList,
stockPrice, exchangeRate, newsFeed
).map(data -> {
Double price = (Double) data[0];
Double rate = (Double) data[1];
News news = (News) data[2];
return new Dashboard(price, rate, news);
});
}
}

Error Handling Operators​

public class ErrorHandlingOperators {

/**
* Comprehensive error handling strategies
*/
public void errorHandling() {
Flux<String> dataStream = getDataStream();

dataStream
// 1. Timeout handling
.timeout(Duration.ofSeconds(30))

// 2. Retry with backoff
.retryWhen(Retry.backoff(3, Duration.ofSeconds(1))

// 3. Fallback values
.onErrorReturn("fallback-value")

// 4. Fallback method
.onErrorResume(error -> {
if (error instanceof TimeoutException) {
return getCachedData();
} else if (error instanceof DatabaseException) {
return getBackupData();
}
return Flux.error(error);
})

// 5. Log and continue
.doOnError(error ->
log.error("Stream processing failed", error)
)

.subscribe();
}

/**
* Circuit breaker pattern
*/
public void circuitBreaker() {
CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("backendService");

Flux<String> resilientStream = Flux.interval(Duration.ofSeconds(1))
.flatMap(tick ->
Mono.fromCallable(() -> externalService.call())
.transformDeferred(CircuitBreakerOperator.of(circuitBreaker))
.onErrorResume(e -> Mono.just("fallback"))
);
}
}

Scheduling & Threading​

public class SchedulingDeepDive {

/**
* Proper threading model for different operations
*/
public void schedulingOperators() {
// CPU-intensive work
Flux<Integer> cpuIntensive = Flux.range(1, 1000)
.parallel() // Process in parallel
.runOn(Schedulers.parallel())
.map(i -> expensiveComputation(i))
.sequential();

// I/O intensive work
Flux<String> ioIntensive = Flux.just("id1", "id2", "id3")
.flatMap(id ->
Mono.fromCallable(() -> database.query(id))
.subscribeOn(Schedulers.boundedElastic()) // Offload blocking I/O
);

// Real-time processing with different schedulers
Flux.interval(Duration.ofMillis(10))
.publishOn(Schedulers.single()) // Dedicated thread for downstream
.map(tick -> transformData(tick))
.publishOn(Schedulers.boundedElastic()) // Switch threads for I/O
.flatMap(data -> saveToDatabase(data))
.subscribeOn(Schedulers.parallel()) // Where subscription happens
.subscribe();
}

/**
* Scheduler types and when to use them
*/
public void schedulerTypes() {
// Schedulers.immediate() - Current thread
// Schedulers.single() - Single dedicated thread
// Schedulers.parallel() - Fixed pool for CPU work
// Schedulers.boundedElastic() - For blocking I/O (preferred over elastic)
// Schedulers.elastic() - Legacy, unlimited threads (avoid)
}
}

Advanced Patterns & Real-World Use Cases​

Pattern 1: API Gateway with Rate Limiting​

public class ApiGatewayService {

public Flux<ApiResponse> handleConcurrentRequests(Flux<ApiRequest> requests) {
return requests
.window(Duration.ofSeconds(1)) // Window by time
.flatMap(window ->
window
.limitRate(100) // Limit to 100 requests per second
.flatMap(this::processRequest, 10) // Max 10 concurrent
)
.onErrorResume(error ->
Flux.just(ApiResponse.error("Service unavailable"))
);
}

private Mono<ApiResponse> processRequest(ApiRequest request) {
return Mono.zip(
userService.validateToken(request.getToken()),
rateLimitService.checkLimit(request.getUserId())
)
.flatMap(tuple -> routingService.routeRequest(request))
.timeout(Duration.ofSeconds(5))
.retryWhen(Retry.fixedDelay(2, Duration.ofMillis(100)));
}
}

Pattern 2: Real-Time Data Pipeline​

public class DataPipeline {

public Flux<ProcessedData> createPipeline() {
return kafkaSource.stream()
.groupBy(message -> message.getPartitionKey()) // Maintain ordering per key
.flatMap(partitionStream ->
partitionStream
.window(Duration.ofSeconds(5)) // Batch processing
.flatMap(this::processBatch)
.flatMap(this::enrichWithExternalData)
.flatMap(this::validateAndTransform)
.buffer(100) // Buffer for bulk insert
.flatMap(this::bulkInsertToDatabase)
, 32) // Process 32 partitions concurrently
.metrics() // Monitor performance
.doOnNext(metrics::recordProcessingTime);
}

private Mono<ProcessedData> processBatch(Flux<Message> batch) {
return batch
.collectList()
.flatMap(list ->
Mono.fromCallable(() -> sparkService.processBatch(list))
.subscribeOn(Schedulers.boundedElastic())
);
}
}

Pattern 3: Resilient Service Composition​

public class ResilientServiceComposition {

public Mono<OrderResult> processOrder(Order order) {
return validateOrder(order)
.flatMap(validated ->
Mono.zip(
reserveInventory(validated).onErrorReturn(InventoryReservation.failed()),
processPayment(validated).onErrorReturn(PaymentResult.failed()),
updateShipping(validated).onErrorReturn(ShippingUpdate.failed())
)
)
.map(tuple -> {
// Compose final result from partial successes/failures
return OrderResult.fromComponents(
tuple.getT1(),
tuple.getT2(),
tuple.getT3()
);
})
.timeout(Duration.ofSeconds(30))
.retryWhen(Retry.backoff(3, Duration.ofSeconds(1)));
}
}

Performance Best Practices​

public class PerformanceBestPractices {

// 1. Avoid blocking in reactive chains
public Flux<String> badExample() {
return Flux.range(1, 100)
.map(i -> {
return blockingDatabaseCall(i); // ❌ BLOCKING!
});
}

public Flux<String> goodExample() {
return Flux.range(1, 100)
.flatMap(i ->
Mono.fromCallable(() -> blockingDatabaseCall(i))
.subscribeOn(Schedulers.boundedElastic()) // ✅ Correct
);
}

// 2. Use backpressure properly
public Flux<Data> handleBackpressure() {
return fastProducer()
.onBackpressureBuffer(1000) // Buffer up to 1000 elements
.onBackpressureDrop(dropped -> log.warn("Dropped: {}", dropped))
.concatMap(this::slowConsumer, 5); // Control concurrency
}

// 3. Monitor and tune
public void monitoring() {
Flux.range(1, 1000)
.name("processing.pipeline")
.tag("type", "batch")
.metrics()
.doOnNext(item ->
Metrics.counter("items.processed").increment()
)
.subscribe();
}
}

Reactive Programming in Spring WebFlux Series - I

· 4 min read

Overview and Fundamentals

What is Reactive Programming?​

Reactive programming is a programming paradigm oriented around data flows and the propagation of changes. Unlike traditional imperative programming, reactive programming allows you to declare data dependencies, and changes are automatically propagated when the data source changes. The core idea of reactive programming involves asynchronous data stream processing and non-blocking operations, making applications more efficient in utilizing system resources.


Why Choose Spring WebFlux?​

Spring WebFlux is an asynchronous, non-blocking web framework introduced in Spring 5 that handles non-blocking asynchronous requests. Unlike traditional Spring MVC, Spring WebFlux is built on the Reactive Streams specification and supports a fully non-blocking reactive programming model. Some key reasons to choose Spring WebFlux include:

  • Non-blocking I/O: Allows handling of more concurrent requests, improving system throughput and response times.
  • Reactive Programming Model: Offers reactive programming support based on Project Reactor, making the code more concise and maintainable.
  • Flexible Programming Model: Supports both annotation-driven and functional programming models, catering to different developer needs.
  • High Scalability: Ideal for microservices and distributed systems, making it easy to scale and integrate.

Core Concepts and Components​

1. Reactive Streams​

Reactive Streams is the foundation of reactive programming, defining the standards for asynchronous stream processing. It consists of four core interfaces:

  • Publisher: Responsible for producing data.
  • Subscriber: Consumes data.
  • Subscription: Manages the relationship between publishers and subscribers.
  • Processor: Acts as both a publisher and a subscriber.

2. Project Reactor​

Project Reactor is the underlying implementation for Spring WebFlux, providing support for reactive streams. It has two main types:

  • Mono: Represents an asynchronous sequence of 0 or 1 element.
  • Flux: Represents an asynchronous sequence of 0 to N elements.

3. WebFlux​

Spring WebFlux is an asynchronous, non-blocking web framework based on Reactive Streams API and Project Reactor. The main components include:

  • Router Functions: Define mappings between requests and handlers in a functional style.
  • Handler Functions: Handle HTTP requests and return responses.

Practical Example: Building a Simple WebFlux Application​

1. Project Setup​

Start by creating a Spring Boot project and adding the necessary dependencies:

<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
<dependency>
<groupId>io.projectreactor</groupId>
<artifactId>reactor-core</artifactId>
</dependency>
</dependencies>

2. Define Data Model​

Define a simple user data model:

public class User {
private String id;
private String name;

// Constructors, Getters and Setters
}

3. Create Handler and Router​

Create a handler function and a router function:

@Component
public class UserHandler {
public Mono<ServerResponse> getUser(ServerRequest request) {
User user = new User("1", "John Doe");
return ServerResponse.ok().body(Mono.just(user), User.class);
}
}

@Configuration
public class RouterConfig {
@Bean
public RouterFunction<ServerResponse> route(UserHandler handler) {
return RouterFunctions.route(RequestPredicates.GET("/user"), handler::getUser);
}
}

Conclusion​

In this article, we introduced the basic concepts and core components of Spring WebFlux and demonstrated how to build a simple reactive application using WebFlux.

Reactive Programming in Spring WebFlux Series - II

· 4 min read

Index​


In-depth Understanding of Reactor and Asynchronous Data Streams


Introduction to Reactor​

Reactor is at the core of Spring WebFlux, providing powerful reactive programming support based on the Reactive Streams standard. Reactor mainly offers two core classes: Mono and Flux, which are used to represent asynchronous sequences of one or multiple elements, respectively.


Mono and Flux​

Mono​

Mono represents an asynchronous sequence of 0 or 1 element. It is typically used when dealing with operations that might return a single result or no result at all.

Flux​

Flux represents an asynchronous sequence of 0 to N elements. It is suitable for cases where multiple results need to be handled, such as querying a database that returns multiple records.


Basic Operations​

Reactor provides a rich set of operators for manipulating data streams, such as transformations, filtering, and aggregations. Some of the commonly used operators include:

  • map: Transforms each element in the data stream.
  • filter: Filters elements in the data stream, retaining only those that meet the criteria.
  • flatMap: Maps each element to a new Publisher and merges these Publishers into a single Flux.
  • concatMap: Similar to flatMap but maintains the order of the elements.
  • zip: Combines multiple Publishers by pairing elements based on their indices.

Practical Example: Building a Reactive Application with Reactor​

1. Project Setup​

Ensure your project contains the following dependencies:

<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
<dependency>
<groupId>io.projectreactor</groupId>
<artifactId>reactor-core</artifactId>
</dependency>
</dependencies>

2. Define Data Model​

Define a simple user data model:

public class User {
private String id;
private String name;

// Constructors, Getters and Setters
}

3. Simulated Data Source​

Create a simulated data source to generate user data:

import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.Arrays;
import java.util.List;

public class UserRepository {
private static final List<User> users = Arrays.asList(
new User("1", "John Doe"),
new User("2", "Jane Doe"),
new User("3", "Sam Smith")
);

public Mono<User> findById(String id) {
return Mono.justOrEmpty(users.stream()
.filter(user -> user.getId().equals(id))
.findFirst());
}

public Flux<User> findAll() {
return Flux.fromIterable(users);
}
}

4. Handlers and Router Configuration​

Create handler functions and router configurations to handle HTTP requests and return responses:

import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import org.springframework.web.reactive.function.server.RouterFunctions;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import reactor.core.publisher.Mono;

@Component
public class UserHandler {
private final UserRepository userRepository;

public UserHandler(UserRepository userRepository) {
this.userRepository = userRepository;
}

public Mono<ServerResponse> getUser(ServerRequest request) {
String userId = request.pathVariable("id");
return userRepository.findById(userId)
.flatMap(user -> ServerResponse.ok().body(Mono.just(user), User.class))
.switchIfEmpty(ServerResponse.notFound().build());
}

public Mono<ServerResponse> getAllUsers(ServerRequest request) {
return ServerResponse.ok().body(userRepository.findAll(), User.class);
}
}

@Configuration
public class RouterConfig {
@Bean
public RouterFunction<ServerResponse> route(UserHandler handler) {
return RouterFunctions.route()
.GET("/user/{id}", handler::getUser)
.GET("/users", handler::getAllUsers)
.build();
}
}

Conclusion​

In this article, we took a deep dive into Reactor and its application in Spring WebFlux. By understanding Mono and Flux and how to handle asynchronous data streams with these tools, we can build more efficient reactive applications.

Reactive Programming in Spring WebFlux Series - III

· 4 min read

Error Handling and Debugging


Error Handling​

Error handling in reactive programming is different from traditional synchronous programming due to the asynchronous nature of reactive streams. In Reactor, errors are handled in various ways:

1. onErrorReturn​

This operator allows returning a default value when an error occurs. Example:

Flux<String> flux = Flux.just("A", "B", "C")
.concatWith(Flux.error(new RuntimeException("Exception occurred")))
.onErrorReturn("Default");

flux.subscribe(System.out::println);

In this example, when an error occurs, the default value "Default" is returned.

2. onErrorResume​

This operator allows switching to another Publisher when an error occurs. Example:

Flux<String> flux = Flux.just("A", "B", "C")
.concatWith(Flux.error(new RuntimeException("Exception occurred")))
.onErrorResume(e -> {
System.out.println("Error: " + e.getMessage());
return Flux.just("D", "E");
});

flux.subscribe(System.out::println);

Here, when an error occurs, it switches to another Flux sequence to continue processing new data.

3. onErrorMap​

This operator allows converting an error into a different type of error. Example:

Flux<String> flux = Flux.just("A", "B", "C")
.concatWith(Flux.error(new RuntimeException("Exception occurred")))
.onErrorMap(e -> new CustomException("Custom message", e));

flux.subscribe(System.out::println, e -> System.out.println("Error: " + e.getMessage()));

In this case, a RuntimeException is converted into a custom CustomException.


Global Error Handling in WebFlux​

In addition to handling errors in streams, Spring WebFlux also allows defining a global error handler for managing errors across the application.

1. Defining a Custom Exception Class​

public class CustomException extends RuntimeException {
public CustomException(String message) {
super(message);
}
}

2. Creating an Exception Handler​

import org.springframework.core.annotation.Order;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import org.springframework.web.reactive.function.server.ServerResponse.BodyBuilder;
import org.springframework.web.server.ServerWebExchange;
import org.springframework.web.server.WebExceptionHandler;
import reactor.core.publisher.Mono;

@Component
@Order(-2)
public class GlobalErrorHandler implements WebExceptionHandler {

@Override
public Mono<Void> handle(ServerWebExchange exchange, Throwable ex) {
BodyBuilder response = ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR)
.contentType(MediaType.APPLICATION_JSON);

if (ex instanceof CustomException) {
response = ServerResponse.status(HttpStatus.BAD_REQUEST);
}

return response.bodyValue(new ErrorResponse(ex.getMessage()))
.flatMap(resp -> resp.writeTo(exchange, new Context()));
}

private static class ErrorResponse {
private final String message;

public ErrorResponse(String message) {
this.message = message;
}

public String getMessage() {
return message;
}
}
}

Debugging Reactive Applications​

Debugging reactive applications can be more challenging than debugging traditional synchronous applications. Here are some debugging techniques:

1. Using the log Operator​

Reactor provides the log operator to output log information for each step. Example:

Flux<String> flux = Flux.just("A", "B", "C")
.concatWith(Flux.error(new RuntimeException("Exception occurred")))
.log();

flux.subscribe(System.out::println);

2. Breakpoint Debugging​

Setting breakpoints in an IDE allows you to step through the execution. Be mindful of thread switching and asynchronous execution details when debugging reactive code.

3. Using Reactor Debugger​

Reactor provides a special debug tool Hooks.onOperatorDebug to help understand and debug operations in reactive streams.

Hooks.onOperatorDebug();

Flux<String> flux = Flux.just("A", "B", "C")
.concatWith(Flux.error(new RuntimeException("Exception occurred")));

flux.subscribe(System.out::println);

Conclusion​

In this article, we explored how to handle errors and debug reactive applications in Spring WebFlux, providing techniques for both stream-level and global error handling.

Reactive Programming in Spring WebFlux Series - IV

· 4 min read

Data Stream Transformation and Operations


Data Stream Transformation​

In reactive programming, transforming and operating on data streams is a core aspect. Using different operators, we can handle data streams flexibly, applying transformations, filtering, aggregating, and more. Below are some common data stream operations and examples.

1. map Operator​

The map operator transforms each element in a data stream. It takes a function as an argument and applies it to each element.

Flux<Integer> numbers = Flux.just(1, 2, 3, 4, 5)
.map(n -> n * n);

numbers.subscribe(System.out::println); // Output: 1, 4, 9, 16, 25

2. flatMap Operator​

The flatMap operator maps each element to a new Publisher and merges them into a single Flux. It is often used for asynchronous processing.

Flux<String> ids = Flux.just("1", "2", "3");
Flux<User> users = ids.flatMap(id -> userRepository.findById(id));

users.subscribe(System.out::println);

3. filter Operator​

The filter operator filters data streams, keeping only elements that meet a certain condition.

Flux<Integer> numbers = Flux.just(1, 2, 3, 4, 5)
.filter(n -> n % 2 == 0);

numbers.subscribe(System.out::println); // Output: 2, 4

4. reduce Operator​

The reduce operator aggregates all elements in a data stream into a single value. It takes an accumulator function, combining the previous result with the current element.

Flux<Integer> numbers = Flux.just(1, 2, 3, 4, 5);
Mono<Integer> sum = numbers.reduce((a, b) -> a + b);

sum.subscribe(System.out::println); // Output: 15

Practical Example: Building a Complex Data Stream Processing Application​

Below is an example showing how to use these operators to build a complex reactive application in Spring WebFlux.

1. Project Setup​

Ensure that the following dependencies are included in your project:

<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
<dependency>
<groupId>io.projectreactor</groupId>
<artifactId>reactor-core</artifactId>
</dependency>
</dependencies>

2. Data Model​

Define a simple user data model:

public class User {
private String id;
private String name;

// Constructors, Getters and Setters
}

3. Mock Data Source​

Create a mock data source:

import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.Arrays;
import java.util.List;

public class UserRepository {
private static final List<User> users = Arrays.asList(
new User("1", "John Doe"),
new User("2", "Jane Doe"),
new User("3", "Sam Smith")
);

public Mono<User> findById(String id) {
return Mono.justOrEmpty(users.stream()
.filter(user -> user.getId().equals(id))
.findFirst());
}

public Flux<User> findAll() {
return Flux.fromIterable(users);
}
}

4. Handler Functions and Route Configuration​

Set up handler functions and route configuration:

import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import org.springframework.web.reactive.function.server.RouterFunctions;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import reactor.core.publisher.Mono;

@Component
public class UserHandler {
private final UserRepository userRepository;

public UserHandler(UserRepository userRepository) {
this.userRepository = userRepository;
}

public Mono<ServerResponse> getUser(ServerRequest request) {
String userId = request.pathVariable("id");
return userRepository.findById(userId)
.flatMap(user -> ServerResponse.ok().body(Mono.just(user), User.class))
.switchIfEmpty(ServerResponse.notFound().build());
}

public Mono<ServerResponse> getAllUsers(ServerRequest request) {
return ServerResponse.ok().body(userRepository.findAll(), User.class);
}
}

@Configuration
public class RouterConfig {
@Bean
public RouterFunction<ServerResponse> route(UserHandler handler) {
return RouterFunctions.route()
.GET("/user/{id}", handler::getUser)
.GET("/users", handler::getAllUsers)
.build();
}
}

Conclusion​

In this article, we explored how to transform and operate on data streams in Spring WebFlux. Using different operators, we can flexibly handle data streams, building complex reactive applications.

Reactive Programming in Spring WebFlux Series - IX

· 4 min read


Test


Introduction

In previous articles, we explored the foundational concepts of Spring WebFlux, Reactor, error handling, data flow transformation, reactive database access, performance optimization, complex scenarios, and security. This article delves into how to conduct testing in Spring WebFlux to ensure that our reactive applications run reliably in both development and production environments.

Why Testing is Necessary​

Testing is an indispensable part of the software development process. Through testing, we can validate code correctness, ensure individual modules function as expected, and promptly identify and resolve potential issues. For reactive applications like those built with Spring WebFlux, testing is particularly important because reactive programming introduces asynchronous and non-blocking operations, which increase the complexity of debugging and validation.

Types of Testing in Spring WebFlux​

In Spring WebFlux, there are typically three main types of tests:

  • Unit Testing: Testing individual modules or components to ensure their behavior matches expectations.
  • Integration Testing: Testing the interactions between multiple modules to ensure they work together correctly.
  • End-to-End Testing: Simulating real user actions and verifying the behavior of the entire system.

1. Unit Testing​

Unit testing is the smallest test scope, focusing on individual functionality or components. In Spring WebFlux, we commonly test controllers, services, and data access layers.

1.1 Testing Controllers with WebTestClient​

WebTestClient is a powerful tool for testing the web layer of Spring WebFlux applications.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
import org.springframework.test.web.reactive.server.WebTestClient;

@WebFluxTest(UserHandler.class)
public class UserHandlerTest {

@Autowired
private WebTestClient webTestClient;

@Test
void testGetUser() {
webTestClient.get().uri("/user/1")
.exchange()
.expectStatus().isOk()
.expectBody()
.jsonPath("$.name").isEqualTo("John Doe");
}

@Test
void testGetAllUsers() {
webTestClient.get().uri("/users")
.exchange()
.expectStatus().isOk()
.expectBodyList(User.class).hasSize(3);
}
}

This example shows how to test a controller using WebTestClient, focusing on the GET /user/1 and GET /users endpoints.

1.2 Testing Services with Mockito​

Mockito is a popular mocking framework used to create and manage dependencies in tests.

import static org.mockito.Mockito.*;
import static org.junit.jupiter.api.Assertions.*;

import org.junit.jupiter.api.Test;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.MockitoAnnotations;
import reactor.core.publisher.Mono;

public class UserServiceTest {

@Mock
private UserRepository userRepository;

@InjectMocks
private UserService userService;

public UserServiceTest() {
MockitoAnnotations.openMocks(this);
}

@Test
void testGetUser() {
User user = new User("1", "John Doe");
when(userRepository.findById("1")).thenReturn(Mono.just(user));

Mono<User> result = userService.getUser("1");
assertEquals("John Doe", result.block().getName());
}
}

In this example, we use Mockito to mock the UserRepository and verify that the UserService correctly retrieves the user.

2. Integration Testing​

Integration tests validate the interactions between multiple modules. In Spring WebFlux, we usually use the @SpringBootTest annotation to load the entire application context and use WebTestClient to perform tests.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.reactive.server.WebTestClient;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class ApplicationIntegrationTest {

@Autowired
private WebTestClient webTestClient;

@Test
void testGetUser() {
webTestClient.get().uri("/user/1")
.exchange()
.expectStatus().isOk()
.expectBody()
.jsonPath("$.name").isEqualTo("John Doe");
}

@Test
void testGetAllUsers() {
webTestClient.get().uri("/users")
.exchange()
.expectStatus().isOk()
.expectBodyList(User.class).hasSize(3);
}
}

In this example, the entire application is loaded and tested for correctness across modules using WebTestClient.

3. End-to-End Testing​

End-to-end testing simulates real user actions and verifies the behavior of the entire system. These tests are generally more complex as they involve starting the whole application and mimicking various user interaction scenarios.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.reactive.server.WebTestClient;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class EndToEndTest {

@Autowired
private WebTestClient webTestClient;

@Test
void testUserFlow() {
// Create a new user
User newUser = new User(null, "Alice");
webTestClient.post().uri("/user")
.bodyValue(newUser)
.exchange()
.expectStatus().isOk()
.expectBody()
.jsonPath("$.name").isEqualTo("Alice");

// Get all users
webTestClient.get().uri("/users")
.exchange()
.expectStatus().isOk()
.expectBodyList(User.class).hasSize(4);
}
}

This example tests the flow of creating a new user and then retrieving all users to ensure the system works end-to-end.

Conclusion​

In this article, we discussed how to perform testing in Spring WebFlux. By conducting unit tests, integration tests, and end-to-end tests, you can ensure that every part of your application functions as expected. Additionally, understanding common vulnerabilities like CSRF and XSS is crucial for building secure applications.

Reactive Programming in Spring WebFlux Series - V

· 3 min read

Reactive Database Access


Why Choose Reactive Database Access?​

Traditional database access methods are usually blocking, meaning that when a query is executing, the thread is blocked until the query is completed. This can lead to performance bottlenecks in highly concurrent environments. Reactive database access uses non-blocking I/O operations, allowing applications to handle more concurrent requests, improving system throughput and response times.


Spring Data R2DBC​

Spring Data R2DBC (Reactive Relational Database Connectivity) is a project in the Spring ecosystem that provides reactive programming support for relational databases. R2DBC is a new database connection specification designed to support reactive programming models.

1. Project Setup​

First, create a Spring Boot project and include the necessary dependencies:

<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-r2dbc</artifactId>
</dependency>
<dependency>
<groupId>io.r2dbc</groupId>
<artifactId>r2dbc-h2</artifactId>
</dependency>
</dependencies>

2. Database Connection Configuration​

Configure the H2 database in application.properties:

spring.r2dbc.url=r2dbc:h2:mem:///testdb
spring.r2dbc.username=sa
spring.r2dbc.password=
spring.r2dbc.generate-unique-name=true

spring.h2.console.enabled=true
spring.h2.console.settings.web-allow-others=true

3. Data Model​

Define a simple User entity:

import org.springframework.data.annotation.Id;
import org.springframework.data.relational.core.mapping.Table;

@Table("users")
public class User {
@Id
private Long id;
private String name;

// Getters and Setters
}

4. Creating a Repository​

Create a reactive UserRepository interface:

import org.springframework.data.repository.reactive.ReactiveCrudRepository;

public interface UserRepository extends ReactiveCrudRepository<User, Long> {
}

5. Data Initialization​

Use an initializer class to preload some data:

import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import reactor.core.publisher.Flux;

@Configuration
public class DataInitializer {

@Bean
CommandLineRunner init(UserRepository repository) {
return args -> {
Flux<User> userFlux = Flux.just(
new User(null, "John Doe"),
new User(null, "Jane Doe"),
new User(null, "Sam Smith"))
.flatMap(repository::save);

userFlux
.thenMany(repository.findAll())
.subscribe(user -> System.out.println("Saving " + user.toString()));
};
}
}

6. Handler Functions and Route Configuration​

Create handler functions and route configurations to handle HTTP requests and return responses:

import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import org.springframework.web.reactive.function.server.RouterFunctions;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import reactor.core.publisher.Mono;

@Component
public class UserHandler {
private final UserRepository userRepository;

public UserHandler(UserRepository userRepository) {
this.userRepository = userRepository;
}

public Mono<ServerResponse> getUser(ServerRequest request) {
Long userId = Long.valueOf(request.pathVariable("id"));
return userRepository.findById(userId)
.flatMap(user -> ServerResponse.ok().body(Mono.just(user), User.class))
.switchIfEmpty(ServerResponse.notFound().build());
}

public Mono<ServerResponse> getAllUsers(ServerRequest request) {
return ServerResponse.ok().body(userRepository.findAll(), User.class);
}

public Mono<ServerResponse> createUser(ServerRequest request) {
Mono<User> userMono = request.bodyToMono(User.class);
return userMono.flatMap(userRepository::save)
.flatMap(user -> ServerResponse.ok().body(Mono.just(user), User.class));
}
}

@Configuration
public class RouterConfig {
@Bean
public RouterFunction<ServerResponse> route(UserHandler handler) {
return RouterFunctions.route()
.GET("/user/{id}", handler::getUser)
.GET("/users", handler::getAllUsers)
.POST("/user", handler::createUser)
.build();
}
}

Conclusion​

In this article, we explored how to perform reactive database access in Spring WebFlux. With Spring Data R2DBC, we can easily achieve non-blocking access to relational databases, greatly improving the performance and concurrency handling of applications.

Reactive Programming in Spring WebFlux Series - VI

· 4 min read

Reactive Programming in Complex Scenarios

In previous articles, we discussed the foundational concepts of Spring WebFlux, Reactor, error handling, data flow transformation, reactive database access, and performance optimization. This article explores how to apply reactive programming in complex scenarios, including flow control, backpressure handling, and integrating external services.

Complex Scenario 1: Flow Control and Backpressure Handling​

In high-concurrency environments, controlling data flow and managing backpressure are critical for ensuring system stability. Backpressure occurs when downstream consumers cannot keep up with the speed of upstream producers, leading to data accumulation and resource exhaustion. Reactor provides various ways to handle backpressure issues.

1. Using limitRate​

The limitRate operator limits the amount of data requested at a time, thereby controlling the speed of data flow.

Flux.range(1, 1000)
.limitRate(100)
.subscribe(System.out::println);

2. Using onBackpressureBuffer​

The onBackpressureBuffer operator buffers data during backpressure until the downstream can process it.

Flux.range(1, 1000)
.onBackpressureBuffer(50)
.subscribe(System.out::println);

3. Using onBackpressureDrop​

The onBackpressureDrop operator drops data during backpressure to prevent downstream overload.

Flux.range(1, 1000)
.onBackpressureDrop()
.subscribe(System.out::println);

Complex Scenario 2: Integrating External Services​

In real projects, interactions with external services are common, such as calling REST APIs or using message queues. Spring WebFlux provides powerful integration capabilities.

1. Using WebClient to Call REST APIs​

WebClient is a non-blocking HTTP client provided by Spring WebFlux, suitable for interacting with external REST services.

import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

public class WebClientExample {
private final WebClient webClient = WebClient.create("http://example.com");

public Mono<String> fetchData() {
return webClient.get()
.uri("/data")
.retrieve()
.bodyToMono(String.class);
}
}

2. Using Reactive Kafka for Message Processing​

Spring WebFlux integrates seamlessly with Reactive Kafka to achieve non-blocking message processing.

<dependency>
<groupId>org.springframework.kafka</groupId>
<artifactId>spring-kafka</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.kafka</groupId>
<artifactId>spring-kafka-reactive</artifactId>
</dependency>
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Component;
import reactor.core.publisher.FluxSink;

@Component
public class KafkaConsumer {
private final FluxSink<String> sink;

public KafkaConsumer(FluxSink<String> sink) {
this.sink = sink;
}

@KafkaListener(topics = "example-topic", groupId = "group_id")
public void listen(String message) {
sink.next(message);
}
}

Complex Scenario 3: Handling Large Files​

When processing large files, traditional reading methods can lead to excessive memory consumption. Using Spring WebFlux allows for non-blocking, streaming file processing.

import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.http.codec.multipart.FilePart;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

public class FileHandler {
public Mono<ServerResponse> uploadFile(ServerRequest request) {
return request.multipartData()
.flatMap(parts -> {
FilePart filePart = (FilePart) parts.toSingleValueMap().get("file");
Flux<DataBuffer> content = filePart.content();
return ServerResponse.ok().body(content, DataBuffer.class);
});
}
}

Conclusion​

In this article, we explored several strategies and methods for applying Spring WebFlux in complex scenarios. By effectively managing backpressure, integrating external services, and processing large files in a streaming fashion, we can build more robust and efficient reactive applications.

Furthermore​

  1. Kubernetes for Deployment: Consider deploying your reactive applications using Kubernetes for better scalability and management.
  2. Reactive Programming Patterns: Implement design patterns such as Circuit Breaker and Rate Limiter to enhance application resilience.
  3. Monitoring with Micrometer: Use Micrometer to instrument your reactive applications for better observability and performance metrics.
  4. Serverless Architecture: Explore serverless solutions to handle unpredictable workloads efficiently, integrating with AWS Lambda or Azure Functions.