WebSockets and STOMP messaging

A WebSocket is a long-lived two-way connection between browser and server, so either side can send at any time.

🔎 Unravel this example Prerequisites (1)

Learn these first

Spring beans and dependency injection

At a glance

Mental model

A phone call instead of postcards.

What happens, in order

1The connection starts as a normal HTTP request that asks to upgradeAfter that, the same TCP connection carries frames in both directions.
2With STOMP, @MessageMapping("/chat") handles messages sent to /app/chat, and @SendTo("/topic/room") broadcasts the return value to every subscriber of that topic
3SimpMessagingTemplate.convertAndSend("/topic/prices", price) lets any service push to subscribers, convertAndSendToUser targets one user
4A configurer enables a simple in-memory broker (enableSimpleBroker("/topic")) or relays to RabbitMQ or ActiveMQ for several server instances

Remember

The simple broker lives inside one JVM
Authenticate during the handshake (a token in the query string or a header on the STOMP CONNECT frame), and authorise each subscription; otherwise anyone can subscribe to any topic
Spring wraps the container WebSocket API in WebSocketHandler

Watch out

Using the in-memory broker with several instancesNo authentication on the handshake or subscriptionsUnbounded message sizes or queues per clientAssuming messages are delivered exactly once

Example (highlighted lines explain it)

@Controllerpublic class ChatController {    @MessageMapping("/chat")    @SendTo("/topic/room")    public ChatMessage relay(ChatMessage in) {        return new ChatMessage(in.user(), in.text(), Instant.now());    }}

line 3 uses MessageMapping, the core of WebSockets and STOMP messaging
line 4 uses SendTo, the core of WebSockets and STOMP messaging

Read the full explanation (about 1 min)

A WebSocket is a long-lived two-way connection between browser and server, so either side can send at any time. STOMP adds topics and destinations on top, like a small publish-subscribe system.

A mental model

A phone call instead of postcards. After the first handshake both sides can speak whenever they want, without dialling again for every sentence.

How it works

The connection starts as a normal HTTP request that asks to upgrade. After that, the same TCP connection carries frames in both directions.

With STOMP, @MessageMapping("/chat") handles messages sent to /app/chat, and @SendTo("/topic/room") broadcasts the return value to every subscriber of that topic.

SimpMessagingTemplate.convertAndSend("/topic/prices", price) lets any service push to subscribers, convertAndSendToUser targets one user.

A configurer enables a simple in-memory broker (enableSimpleBroker("/topic")) or relays to RabbitMQ or ActiveMQ for several server instances.

Going deeper

The simple broker lives inside one JVM. With several instances behind a load balancer, a message sent on instance A never reaches subscribers on instance B unless a broker relay is used.

Authenticate during the handshake (a token in the query string or a header on the STOMP CONNECT frame), and authorise each subscription; otherwise anyone can subscribe to any topic.

Plan for reconnection: clients drop on mobile networks and deploys. The server should tolerate duplicates and clients should resubscribe and fetch missed state.

Under the hood

Spring wraps the container WebSocket API in WebSocketHandler. For STOMP, inbound frames travel through a clientInboundChannel (a thread pool), are routed by destination prefix to annotated methods or the broker, and outbound messages flow through clientOutboundChannel back to each session.

Common mistakes

Using the in-memory broker with several instances.
No authentication on the handshake or subscriptions.
Unbounded message sizes or queues per client.
Assuming messages are delivered exactly once.

How Unravel recognises it

When you paste code, Unravel looks for these signs of websockets and stomp messaging. Spotting them yourself is a good habit when you read unfamiliar code:

Annotations: @EnableWebSocket @EnableWebSocketMessageBroker @MessageMapping @SendTo @SendToUser @SubscribeMapping @ServerEndpoint @OnMessage @OnOpen @OnClose
Types: SimpMessagingTemplate WebSocketHandler TextWebSocketHandler WebSocketSession StompEndpointRegistry MessageBrokerRegistry WebSocketMessage WebSocketConfigurer WebSocketMessageBrokerConfigurer

Part of a learning path

Building and documenting APIs · previous: Streaming responses and Server-Sent Events · next: File upload and download

Related concepts

Streaming responses and Server-Sent EventsSpring RabbitMQ and AMQP messagingI/O and data

Frequently asked questions

What is WebSockets and STOMP messaging?

A WebSocket is a long-lived two-way connection between browser and server, so either side can send at any time. STOMP adds topics and destinations on top, like a small publish-subscribe system.

What are the most common mistakes with WebSockets and STOMP messaging?

Using the in-memory broker with several instances. No authentication on the handshake or subscriptions. Unbounded message sizes or queues per client. Assuming messages are delivered exactly once.

How can I see WebSockets and STOMP messaging in real code?

Paste your own Java into Unravel and it will point out where websockets and stomp messaging appears, explain how it works at the detail level you choose, and draw the flow of the code around it.