skip to content

In Spring WebFlux, what is the WebSocketHandler interface and what does its handle(WebSocketSession) method return, and why?

level: juniorimportance: must knowfreq 62%

answer

  1. One method: Mono<Void> handle(WebSocketSession)
  2. Framework subscribes; complete closes the session
  3. Compose receive() + send(), return the Mono
  4. Mono<Void> = completion/error only, no value
  5. Don't call .subscribe() yourself

basics

~10 s

WebSocketHandler is the reactive interface you implement to handle a WebSocket connection. Its single method handle(WebSocketSession) returns Mono<Void>, a reactive signal that completes when your handling of the session is done (which closes it).

solid answer

~40 s

In WebFlux, org.springframework.web.reactive.socket.WebSocketHandler has one method: Mono<Void> handle(WebSocketSession session). It is the reactive analog of the Servlet-stack WebSocketHandler. You don't return data; instead you build a reactive pipeline from the session — reading via session.receive() and writing via session.send(...) — and return a Mono<Void> that represents completion of that pipeline. The framework subscribes to that Mono. Because it is Mono<Void>, it carries no value, only completion or error signals: when it completes, the framework closes the session; if it errors, the session is closed with an error status. So the whole connection lifecycle is expressed as one reactive stream you compose and hand back. A trivial echo handler returns session.send(session.receive().map(...)).

code

java · 18 lines
java
import org.springframework.web.reactive.socket.WebSocketHandler;
import org.springframework.web.reactive.socket.WebSocketSession;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

@Component
public class EchoHandler implements WebSocketHandler {

    @Override
    public Mono<Void> handle(WebSocketSession session) {
        // Read inbound frames, map each to an outbound text frame, write them back.
        // The returned Mono<Void> completes when the client stops sending;
        // completion of that Mono tells the framework to close the session.
        return session.send(
            session.receive()
                   .map(msg -> session.textMessage("echo: " + msg.getPayloadAsText())));
    }
}

go deeper

for a junior

Know it's one method returning Mono<Void> and that completing it closes the session.

for a middle

Explain that the framework subscribes and that you compose receive()/send() into the returned Mono.

for a senior

Contrast with the Servlet callback model and explain error signals closing with a close status.

for a principal

Discuss lifecycle ownership, why callbacks were replaced by a single stream, and cleanup via doFinally/doOnError.

## The interface `org.springframework.web.reactive.socket.WebSocketHandler` is the reactive (non-blocking) contract for handling a WebSocket connection in Spring WebFlux. It is deliberately tiny: ```java public interface WebSocketHandler { Mono<Void> handle(WebSocketSession session); default List<String> getSubProtocols() { return Collections.emptyList(); } } ``` This is the reactive counterpart to the Servlet-stack `org.springframework.web.socket.WebSocketHandler`, but the programming model is completely different: instead of callback methods (`afterConnectionEstablished`, `handleMessage`, `afterConnectionClosed`), you get **one method** and express everything as reactive streams. ## Why Mono<Void>? `Mono<Void>` is a reactive publisher that emits **no value** — it only ever signals *completion* or *error*. It is Spring's idiom for "an asynchronous task that finishes but returns nothing." In `handle`, the returned `Mono<Void>` represents **"my handling of this session is finished."** Key consequences: - The framework (specifically `WebSocketHandlerAdapter` / the underlying `WebSocketService`) **subscribes** to the Mono you return. You must not subscribe yourself. - **When the Mono completes** → the framework closes the session with a normal close status. - **When the Mono errors** → the session is closed (with an error/close status). - **While the Mono is not yet terminated** → the session stays open. So the lifetime of the connection is tied to the lifetime of the stream you return. ## How you actually build it You don't "return messages." You compose the inbound and outbound streams and return a Mono that ties them together: - `session.receive()` → `Flux<WebSocketMessage>` of inbound frames. - `session.send(Publisher<WebSocketMessage>)` → `Mono<Void>` that completes when the outbound stream you passed completes. An echo handler: ```java public Mono<Void> handle(WebSocketSession session) { return session.send( session.receive().map(msg -> session.textMessage(msg.getPayloadAsText()))); } ``` Here `send(...)` returns a `Mono<Void>` that stays open as long as inbound messages keep arriving; when the client closes, `receive()` completes, `send()` completes, and the framework closes the session. ## Registration A `WebSocketHandler` is not picked up by URL by default. You map it to a path with a `SimpleUrlHandlerMapping` bean and enable the upgrade with a `WebSocketHandlerAdapter` bean (which internally uses `HandshakeWebSocketService`). That is covered in the mapping question. ## Gotchas for a beginner - **Don't call `.subscribe()`** on your pipeline — return it. If you subscribe yourself and return `Mono.empty()`, the framework will close the session immediately. - **Returning `Mono.empty()`** (or a completed Mono) closes the connection right away — useful only for reject/close-fast logic. - **This is not `@MessageMapping`.** `@MessageMapping` is STOMP/RSocket messaging (a different leaf). The low-level `WebSocketHandler` gives you raw frames. - **One method, whole lifecycle** — there is no separate close callback; use reactive operators like `doOnError`, `doFinally` on the stream for cleanup.

  • What happens if handle() returns Mono.empty()?
    The framework subscribes, sees immediate completion, and closes the session right away. It is only useful to fast-close a connection, not to keep it open.
  • Should you call subscribe() on your receive()/send() pipeline inside handle()?
    No. You return the Mono and the framework subscribes to it. Subscribing yourself detaches the stream from the session lifecycle and typically closes the connection prematurely.

saying these in an interview costs you the question

  • Thinking WebSocketHandler has multiple callbacks like the Servlet version (afterConnectionEstablished, handleMessage)
  • Calling .subscribe() inside handle() instead of returning the Mono
  • Believing you must return the messages from handle() as a value
  • Confusing raw WebSocketHandler with @MessageMapping/STOMP

context

resolving links…