spring-projects/spring-framework

spring-websocket

Active contributors: rstoyanchev, Juergen Hoeller, Brian Clozel

Purpose

spring-websocket provides Spring's WebSocket support — both the low-level WebSocket API integration (Tomcat, Jetty, Undertow native APIs and the Jakarta WebSocket spec) and the higher-level STOMP-over-WebSocket message broker. It powers chat, real-time notification, and broker-style applications.

Directory layout

spring-websocket/
└── src/main/java/org/springframework/web/socket/
    ├── WebSocketHandler.java
    ├── WebSocketSession.java
    ├── WebSocketMessage.java
    ├── adapter/                                    # adapters to Tomcat/Jetty/Undertow native APIs
    ├── client/                                     # WebSocketClient
    ├── config/                                     # @EnableWebSocket, @EnableWebSocketMessageBroker
    ├── handler/                                    # AbstractWebSocketHandler, BroadcastingWebSocketHandler
    ├── messaging/                                  # STOMP support
    │   ├── DefaultSimpUserRegistry.java
    │   ├── StompSubProtocolHandler.java
    │   └── …
    ├── server/                                     # server-side handshake
    │   ├── HandshakeInterceptor.java
    │   ├── support/
    │   └── standard/                               # Jakarta WebSocket integration
    └── sockjs/                                     # SockJS fallback
        ├── client/
        ├── frame/
        ├── support/
        └── transport/

Key abstractions

Type	File	Role
`WebSocketHandler`	`spring-websocket/src/main/java/org/springframework/web/socket/WebSocketHandler.java`	Per-session connection handler
`WebSocketSession`	`spring-websocket/src/main/java/org/springframework/web/socket/WebSocketSession.java`	Active connection
`HandshakeInterceptor`	`spring-websocket/src/main/java/org/springframework/web/socket/server/HandshakeInterceptor.java`	Authorization / attribute setting at handshake
`WebSocketClient`	`spring-websocket/src/main/java/org/springframework/web/socket/client/WebSocketClient.java`	Client-side connect API
`@EnableWebSocketMessageBroker`	`spring-websocket/src/main/java/org/springframework/web/socket/config/annotation/EnableWebSocketMessageBroker.java`	Wires up STOMP broker support
`StompSubProtocolHandler`	`spring-websocket/src/main/java/org/springframework/web/socket/messaging/StompSubProtocolHandler.java`	Protocol decoder/encoder for STOMP frames

How it works

Two layers

graph TD
    Client[Browser / WebSocket client]
    Client -->|"WebSocket frames"| Server[Server: Tomcat / Jetty / Reactor Netty]
    Server -->|"Spring adapter"| WSH[WebSocketHandler]

    Server -->|"STOMP-on-WS"| Stomp[StompSubProtocolHandler]
    Stomp -->|"messages"| MsgBroker[Simple or external broker]
    MsgBroker -->|"@MessageMapping methods"| App[Application controllers]

Plain WebSocket — Implement WebSocketHandler and register at a path. You handle frames yourself.
STOMP — Use @EnableWebSocketMessageBroker and write @MessageMapping-annotated methods. Spring decodes STOMP frames, routes by destination, and broadcasts via either a built-in simple broker or an external broker (RabbitMQ, ActiveMQ).

STOMP destinations and routing

/app/foo      → @MessageMapping("/foo") method
/topic/news   → simple broker → all subscribers
/queue/private → user-specific destination

The routing infrastructure is in spring-messaging; spring-websocket is the WebSocket transport for it.

SockJS

SockJS is a fallback protocol for environments without WebSocket support. It uses long-polling, server-sent events, or HTTP streaming under the hood. Spring's SockJS server emulates the SockJS client protocol and presents the same WebSocketHandler interface to the application.

Integration points

Depends on spring-context, spring-core, spring-web.
Optional: spring-messaging (for STOMP), spring-webmvc (for hosting WebSocket endpoints alongside MVC).
Test integration: spring-test provides WebSocketTestServer helpers.

Entry points for modification

Custom WebSocket handler — Extend AbstractWebSocketHandler and register via WebSocketConfigurer.registerWebSocketHandlers.
Custom handshake interceptor — Implement HandshakeInterceptor for auth checks.
External broker integration — Provide a MessageBrokerRegistry configuration that points at RabbitMQ/ActiveMQ.