or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

dsl-api.mdinbound-endpoints.mdindex.mdoutbound-endpoints.mdxml-configuration.md
tile.json

index.mddocs/

Spring Integration WebFlux

Spring Integration WebFlux provides reactive HTTP integration capabilities for Spring Integration applications. It enables both inbound (receiving HTTP requests) and outbound (making HTTP requests) message processing in a fully reactive, non-blocking manner using Spring WebFlux and Project Reactor.

Package Information

  • Package Name: spring-integration-webflux
  • Package Type: maven
  • Group ID: org.springframework.integration
  • Artifact ID: spring-integration-webflux
  • Version: 7.0.0
  • Language: Java
  • Installation:

Maven:

<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-webflux</artifactId>
    <version>7.0.0</version>
</dependency>

Gradle:

implementation 'org.springframework.integration:spring-integration-webflux:7.0.0'

Key Information for Agents

Required Dependencies:

  • spring-webflux must be on classpath (provides WebClient and WebHandler)
  • spring-integration-core is required
  • reactor-core is required (provided transitively)
  • Spring WebFlux infrastructure must be configured (RouterFunction or WebHandler chain)

Default Behaviors:

  • Inbound gateways: expectReply=true by default (request-reply pattern)
  • Outbound gateways: extractPayload=true by default (extracts body from ResponseEntity)
  • Outbound gateways: extractRequestPayload=true by default (extracts payload from Message)
  • Inbound gateways: extractReplyPayload=true by default (extracts payload from reply Message)
  • Outbound gateways: replyPayloadToFlux=false by default (resolves Mono to single value)
  • Default HTTP method: POST for outbound endpoints
  • No CORS by default (must be explicitly configured)
  • No validation by default (must be explicitly configured)
  • Default charset: UTF-8

Threading Model:

  • All operations are non-blocking and execute on reactive scheduler threads
  • No thread blocking during HTTP I/O operations
  • Backpressure is properly handled through reactive streams
  • Reactor Context is propagated through message headers (IntegrationMessageHeaderAccessor.REACTOR_CONTEXT)

Lifecycle:

  • Inbound endpoints implement WebHandler and integrate with WebFlux's handler chain
  • Endpoints are registered when bean is initialized
  • autoStartup=true by default
  • Graceful shutdown supported through lifecycle callbacks

Exceptions:

  • WebClientException - WebClient request failures
  • HttpServerErrorException - 5xx server errors
  • HttpClientErrorException - 4xx client errors
  • WebExchangeBindException - validation failures (inbound)
  • HttpMessageNotReadableException - request body conversion failures
  • HttpMessageNotWritableException - response body conversion failures

Edge Cases:

  • If expectReply=false for inbound gateway, returns 202 Accepted immediately
  • If replyPayloadToFlux=true, response is always Flux even for single values
  • If extractPayload=false, full ResponseEntity is available in message payload
  • Empty request body: payload is null or empty Mono
  • Empty response body: payload is null or empty Mono
  • Publisher payloads (Flux/Mono) require publisherElementType configuration
  • URI variables not provided: IllegalArgumentException at runtime

Core Imports

// Java DSL factory
import org.springframework.integration.webflux.dsl.WebFlux;
import org.springframework.integration.webflux.dsl.WebFluxMessageHandlerSpec;
import org.springframework.integration.webflux.dsl.WebFluxInboundEndpointSpec;

// Inbound endpoints
import org.springframework.integration.webflux.inbound.WebFluxInboundEndpoint;

// Outbound handlers
import org.springframework.integration.webflux.outbound.WebFluxRequestExecutingMessageHandler;

// WebFlux infrastructure
import org.springframework.web.reactive.function.client.WebClient;
import org.springframework.web.reactive.function.client.WebClientResponseException;
import org.springframework.web.server.ServerWebExchange;
import org.springframework.web.server.WebHandler;

// Reactive types
import reactor.core.publisher.Mono;
import reactor.core.publisher.Flux;

// HTTP types
import org.springframework.http.HttpMethod;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.http.codec.ServerCodecConfigurer;
import org.springframework.web.reactive.function.BodyExtractor;
import org.springframework.web.reactive.function.client.ClientHttpResponse;

// Integration types
import org.springframework.integration.dsl.IntegrationFlow;
import org.springframework.integration.support.MessageBuilder;
import org.springframework.messaging.Message;
import org.springframework.messaging.MessageChannel;

Basic Usage

Simple Outbound Gateway (Making HTTP Requests)

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.integration.dsl.IntegrationFlow;
import org.springframework.integration.webflux.dsl.WebFlux;
import org.springframework.http.HttpMethod;

@Configuration
public class WebFluxOutboundConfig {

    @Bean
    public IntegrationFlow webFluxOutboundFlow() {
        return IntegrationFlow
            .from("requestChannel")
            .handle(WebFlux.outboundGateway("https://api.example.com/users/{id}")
                .uriVariable("id", "payload.userId")
                .httpMethod(HttpMethod.GET)
                .expectedResponseType(User.class))
            .channel("responseChannel")
            .get();
    }
}

Simple Inbound Gateway (Receiving HTTP Requests)

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.integration.dsl.IntegrationFlow;
import org.springframework.integration.webflux.dsl.WebFlux;
import org.springframework.http.HttpMethod;

@Configuration
public class WebFluxInboundConfig {

    @Bean
    public IntegrationFlow webFluxInboundFlow() {
        return IntegrationFlow
            .from(WebFlux.inboundGateway("/api/orders")
                .requestMapping(m -> m.methods(HttpMethod.POST))
                .requestPayloadType(Order.class))
            .handle("orderService", "processOrder")
            .get();
    }
}

Architecture

Spring Integration WebFlux is built around several key components:

Entry Points

  • WebFlux DSL - Factory class providing fluent Java DSL for creating both inbound and outbound endpoints
  • Direct Bean Configuration - Alternative approach using WebFluxInboundEndpoint and WebFluxRequestExecutingMessageHandler directly
  • XML Configuration - Traditional XML-based configuration using the int-webflux namespace

Core Components

  • WebFluxInboundEndpoint - Receives HTTP requests reactively and routes them to integration flows. Implements WebHandler interface.
  • WebFluxRequestExecutingMessageHandler - Executes outbound HTTP requests using WebClient. Extends AbstractHttpRequestExecutingMessageHandler.
  • Infrastructure Beans - Auto-configured handler mappings and result handlers

Integration Points

  • Spring Integration Channels - Messages flow through standard Spring Integration channels
  • WebClient - Uses Spring WebFlux's reactive HTTP client for outbound requests
  • WebHandler - Implements WebFlux's WebHandler interface for inbound request handling
  • Project Reactor - Full integration with Reactor types (Mono, Flux) throughout

Reactive Features

  • Non-blocking I/O - All HTTP operations are fully reactive and non-blocking
  • Backpressure - Proper reactive streams backpressure support
  • Reactor Context - Reactor Context propagation through message headers (IntegrationMessageHeaderAccessor.REACTOR_CONTEXT)
  • Async by Default - All operations execute asynchronously on reactive scheduler threads
  • Publisher Support - Can send/receive Flux and Mono as request/response bodies

Capabilities

Inbound Endpoints (Server-side)

Receive HTTP requests reactively and route them to Spring Integration message channels. Supports both one-way adapters (no response) and request-reply gateways.

// Create inbound channel adapter (no response)
public static WebFluxInboundEndpointSpec inboundChannelAdapter(String... path)

// Create inbound gateway (request-reply)
public static WebFluxInboundEndpointSpec inboundGateway(String... path)

Key features:

  • Reactive request handling with Spring WebFlux
  • Content negotiation and custom codecs
  • Request mapping with path patterns, HTTP methods, headers
  • CORS support
  • Form data and multipart handling
  • Path variables and query parameters via SpEL
  • Validation support
  • Custom status code expressions
  • Reactive type support (Mono, Flux responses)

Inbound Endpoints

Outbound Endpoints (Client-side)

Execute HTTP requests reactively using WebClient and handle responses in Spring Integration flows. Supports both fire-and-forget adapters and request-reply gateways.

// Create outbound channel adapter (fire-and-forget)
public static WebFluxMessageHandlerSpec outboundChannelAdapter(String uri)
public static WebFluxMessageHandlerSpec outboundChannelAdapter(String uri, WebClient webClient)
public static <P> WebFluxMessageHandlerSpec outboundChannelAdapter(
    Function<Message<P>, ?> uriFunction)
public static WebFluxMessageHandlerSpec outboundChannelAdapter(Expression uriExpression)

// Create outbound gateway (request-reply)
public static WebFluxMessageHandlerSpec outboundGateway(String uri)
public static WebFluxMessageHandlerSpec outboundGateway(String uri, WebClient webClient)
public static <P> WebFluxMessageHandlerSpec outboundGateway(
    Function<Message<P>, ?> uriFunction)
public static WebFluxMessageHandlerSpec outboundGateway(Expression uriExpression)

Key features:

  • Reactive HTTP client with WebClient
  • Dynamic URI construction with SpEL or Functions
  • Publisher support (send Flux/Mono as request body)
  • Custom body extractors for response processing
  • Flux vs Mono reply control
  • All HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)
  • Custom WebClient configuration
  • URI variable substitution
  • Header mapping patterns
  • Cookie transfer support

Outbound Endpoints

Java DSL API

Fluent Java DSL for configuring WebFlux integration endpoints with a rich set of configuration options.

// Main factory class
public final class WebFlux {
    // Outbound factory methods
    public static WebFluxMessageHandlerSpec outboundGateway(String uri);
    public static WebFluxMessageHandlerSpec outboundGateway(String uri, WebClient webClient);
    public static <P> WebFluxMessageHandlerSpec outboundGateway(
        Function<Message<P>, ?> uriFunction);
    public static WebFluxMessageHandlerSpec outboundGateway(Expression uriExpression);
    public static WebFluxMessageHandlerSpec outboundChannelAdapter(String uri);
    public static WebFluxMessageHandlerSpec outboundChannelAdapter(String uri, WebClient webClient);
    public static <P> WebFluxMessageHandlerSpec outboundChannelAdapter(
        Function<Message<P>, ?> uriFunction);
    public static WebFluxMessageHandlerSpec outboundChannelAdapter(Expression uriExpression);

    // Inbound factory methods
    public static WebFluxInboundEndpointSpec inboundGateway(String... path);
    public static WebFluxInboundEndpointSpec inboundChannelAdapter(String... path);
}

The DSL provides spec builders that enable fluent configuration of all aspects of inbound and outbound endpoints including HTTP methods, headers, URI variables, codecs, and reactive behaviors.

Java DSL API

XML Configuration

Traditional Spring XML-based configuration using the int-webflux namespace for teams preferring XML over Java configuration.

<int-webflux:inbound-gateway
    request-channel="requestChannel"
    path="/api/endpoint"/>

<int-webflux:outbound-gateway
    request-channel="requestChannel"
    url="https://api.example.com/resource"/>

Supports all features available in the Java DSL with equivalent XML attributes and sub-elements.

XML Configuration

Common Use Cases

Making Reactive HTTP API Calls

Use outbound gateways to call external REST APIs reactively within integration flows:

@Bean
public IntegrationFlow callExternalApi() {
    return IntegrationFlow
        .from("apiRequestChannel")
        .handle(WebFlux.outboundGateway("https://api.service.com/data/{id}")
            .uriVariable("id", "headers.entityId")
            .httpMethod(HttpMethod.GET)
            .expectedResponseType(ApiResponse.class))
        .transform(ApiResponse::getData)
        .channel("processedDataChannel")
        .get();
}

Exposing Reactive HTTP Endpoints

Use inbound gateways to expose HTTP endpoints that trigger integration flows:

@Bean
public IntegrationFlow exposeHttpEndpoint() {
    return IntegrationFlow
        .from(WebFlux.inboundGateway("/api/process")
            .requestMapping(m -> m
                .methods(HttpMethod.POST)
                .consumes("application/json"))
            .requestPayloadType(ProcessRequest.class))
        .handle("processingService", "process")
        .get();
}

Streaming Data with Reactive Publishers

Send or receive streaming data using Flux:

@Bean
public IntegrationFlow streamDataFlow() {
    return IntegrationFlow
        .from("dataStreamChannel")
        .handle(WebFlux.outboundGateway("https://stream.service.com/ingest")
            .httpMethod(HttpMethod.POST)
            .publisherElementType(DataEvent.class)
            .replyPayloadToFlux(true))
        .channel("streamResultChannel")
        .get();
}

Custom WebClient Configuration

Configure WebClient with custom settings like authentication, timeouts, and codecs:

@Bean
public WebClient customWebClient() {
    return WebClient.builder()
        .baseUrl("https://api.example.com")
        .defaultHeader("Authorization", "Bearer token")
        .defaultHeader("Accept", "application/json")
        .clientConnector(new ReactorClientHttpConnector(
            HttpClient.create()
                .responseTimeout(Duration.ofSeconds(10))
        ))
        .build();
}

@Bean
public IntegrationFlow customClientFlow(WebClient customWebClient) {
    return IntegrationFlow
        .from("requestChannel")
        .handle(WebFlux.outboundGateway("/resource/{id}", customWebClient)
            .uriVariable("id", "payload.id"))
        .get();
}

Error Handling with Reactive Types

Handle errors reactively:

@Bean
public IntegrationFlow errorHandlingFlow() {
    return IntegrationFlow
        .from("requestChannel")
        .handle(WebFlux.outboundGateway("https://api.example.com/data")
            .extractPayload(false))
        .handle((payload, headers) -> {
            ResponseEntity<?> response = (ResponseEntity<?>) payload;
            if (response.getStatusCode().is2xxSuccessful()) {
                return response.getBody();
            } else {
                return Mono.error(new ApiException(
                    "Request failed: " + response.getStatusCode()));
            }
        })
        .get();
}

Types

WebFlux Factory

package org.springframework.integration.webflux.dsl;

/**
 * Main entry point for creating WebFlux integration components using Java DSL.
 * Provides static factory methods for creating inbound and outbound endpoints.
 */
public final class WebFlux {
    // Factory methods documented in DSL API section
}

WebFluxInboundEndpoint

package org.springframework.integration.webflux.inbound;

import org.springframework.integration.http.inbound.BaseHttpInboundEndpoint;
import org.springframework.web.server.WebHandler;
import reactor.core.publisher.Mono;

/**
 * Main inbound endpoint for receiving HTTP requests reactively.
 * Implements WebHandler to integrate with Spring WebFlux infrastructure.
 */
public class WebFluxInboundEndpoint extends BaseHttpInboundEndpoint
                                     implements WebHandler {
    public WebFluxInboundEndpoint();
    public WebFluxInboundEndpoint(boolean expectReply);

    public void setCodecConfigurer(ServerCodecConfigurer codecConfigurer);
    public void setRequestedContentTypeResolver(RequestedContentTypeResolver resolver);
    public void setReactiveAdapterRegistry(ReactiveAdapterRegistry registry);

    public Mono<Void> handle(ServerWebExchange exchange);
}

WebFluxRequestExecutingMessageHandler

package org.springframework.integration.webflux.outbound;

import org.springframework.integration.http.outbound.AbstractHttpRequestExecutingMessageHandler;
import org.springframework.web.reactive.function.BodyExtractor;

/**
 * Message handler that executes HTTP requests using WebClient reactively.
 * Supports both adapter (fire-and-forget) and gateway (request-reply) patterns.
 */
public class WebFluxRequestExecutingMessageHandler
       extends AbstractHttpRequestExecutingMessageHandler {
    public WebFluxRequestExecutingMessageHandler(String uri);
    public WebFluxRequestExecutingMessageHandler(Expression uriExpression);
    public WebFluxRequestExecutingMessageHandler(String uri, WebClient webClient);

    public void setReplyPayloadToFlux(boolean replyPayloadToFlux);
    public void setBodyExtractor(BodyExtractor<?, ?> bodyExtractor);
    public void setPublisherElementType(Class<?> publisherElementType);
    public void setPublisherElementTypeExpression(Expression expression);
    public void setAttributeVariablesExpression(Expression expression);
    public void setEncodingMode(DefaultUriBuilderFactory.EncodingMode encodingMode);
}

Thread Safety and Reactive Context

All components are designed for reactive environments:

  • Non-blocking Operations - No thread blocking during HTTP I/O
  • Reactor Context Propagation - Reactor Context available in message headers under IntegrationMessageHeaderAccessor.REACTOR_CONTEXT
  • Backpressure Support - Proper handling of reactive streams backpressure
  • Thread-Safe - All components are thread-safe and suitable for concurrent use
  • Async Execution - Operations execute asynchronously on reactive scheduler threads

Integration with Spring Ecosystem

Spring Integration WebFlux integrates seamlessly with:

  • Spring Integration - Full messaging infrastructure support
  • Spring WebFlux - Native WebFlux integration
  • Spring Security - Security context propagation (requires spring-security-webflux)
  • Spring Boot - Auto-configuration support
  • Project Reactor - Core reactive programming model
  • Spring MVC - Can coexist with traditional Spring MVC in the same application (different ports/contexts)