In this article, we will delve deep into the world of WebSockets and STOMP, exploring their necessity, underlying protocols, and how to implement them using Spring Boot. By the end of this guide, you'll have a thorough understanding of these technologies and how to leverage them to build a functional real-time chat application.

Understanding HTTP vs. WebSockets

HTTP: The Foundation of the Web

HyperText Transfer Protocol (HTTP) is the backbone of data communication on the World Wide Web. It operates on a request-response model, where a client (typically a web browser) sends a request to a server, and the server responds with the requested data. This model is stateless and unidirectional, meaning each request is independent, and the server cannot initiate communication.

Key Characteristics of HTTP:

• Stateless: Each request is independent; the server does not retain any session information between requests.

• Unidirectional: Communication flows from client to server.

• Request-Response Cycle: The client must initiate each interaction.

WebSockets: Breaking the Mold

WebSockets provide a way to establish a persistent, full-duplex communication channel between the client and server. Unlike HTTP, WebSockets allow both parties to send messages independently at any time, facilitating real-time, bidirectional data exchange.

Key Characteristics of WebSockets:

• Stateful: Maintains an open connection, allowing continuous communication.

• Bidirectional: Both client and server can send messages independently.

• Full-Duplex Communication: Simultaneous two-way data transfer.

• Low Latency: Minimal overhead after the initial connection, enabling near-instantaneous communication.

Why Use WebSockets? The Need for Real-Time Communication

In applications where real-time data exchange is crucial, traditional HTTP falls short. Consider the following scenarios:

1. Chat Applications: Users expect instant message delivery without the need for constant polling.

2. Live Sports Updates: Scores and events need to be updated in real-time.

3. Collaborative Editing: Multiple users editing a document simultaneously require immediate synchronization.

4. Online Gaming: Real-time interactions are essential for a seamless gaming experience.

5. Live Dashboards: Financial markets, system monitoring, and other real-time dashboards benefit from instant data updates.

In these cases, WebSockets provide the necessary infrastructure to handle continuous, low-latency communication efficiently, enhancing user experience and application performance.

An Overview of the WebSocket Protocol

The WebSocket protocol is standardized as RFC 6455 and operates over TCP. It begins with an HTTP handshake to establish the connection, which is then upgraded to a WebSocket connection. Once established, the protocol switches from HTTP to a bidirectional communication channel using WebSocket frames.

Key Components of WebSocket:

1. Handshake: An initial HTTP request that upgrades the connection to WebSocket.

1. Frames: The basic units of communication, encapsulating data and control messages.

2. Full-Duplex Communication: Allows simultaneous sending and receiving of messages.

3. Persistent Connection: Maintains an open connection until explicitly closed by either party.

WebSocket Frames:

Each frame contains the following components:

• FIN Bit: Indicates if the frame is the final fragment in a message.

• Opcode: Defines the type of frame (e.g., text, binary, close, ping, pong).

• Masking Key: Used to obfuscate payload data (client-to-server frames must be masked).

• Payload Data: The actual data being transmitted.

Introducing STOMP: Simplifying Messaging

While WebSockets provide a robust communication channel, they operate at a low level, handling only the exchange of frames without any messaging semantics. This is where STOMP (Simple Text Oriented Messaging Protocol) comes into play.

STOMP is a lightweight, text-based messaging protocol designed to work with message brokers. It adds a layer of messaging semantics on top of WebSockets, enabling structured message routing, subscriptions, and acknowledgments.

Key Features of STOMP:

• Command-Based Communication: Defines specific commands like SEND, SUBSCRIBE, MESSAGE, ACK, NACK, and DISCONNECT.

• Destination-Based Routing: Messages are sent to destinations (topics or queues) where clients can subscribe.

• Subscription Management: Clients can subscribe or unsubscribe from specific destinations.

• Message Acknowledgment: Supports various acknowledgment modes to ensure reliable message delivery.

  Example STOMP Frame:

    SEND
    destination:/topic/chatroom
    content-type:text/plain
  
    Hello, Chatroom!
  

  • Command: SEND

  • Headers: destination, content-type

  • Body: Hello, Chatroom!

Why Use STOMP with WebSockets?

While WebSockets excel at enabling real-time, bidirectional communication, managing messaging semantics like routing, subscriptions, and message types can become cumbersome. STOMP simplifies this process by providing a standardized way to handle messaging patterns commonly required in real-time applications.

Benefits of Combining STOMP with WebSockets:

1. Structured Messaging: STOMP commands and headers provide a clear structure for messages, making them easier to manage and debug.

2. Destination-Based Routing: Easily route messages to specific topics or queues, facilitating both publish-subscribe and point-to-point messaging models.

3. Subscription Management: Clients can dynamically subscribe or unsubscribe from destinations, allowing flexible message consumption.

4. Message Acknowledgments: Ensure reliable message delivery with acknowledgment mechanisms, preventing message loss.

5. Integration with Message Brokers: STOMP seamlessly integrates with message brokers like RabbitMQ, ActiveMQ, or Spring's built-in message broker, enhancing scalability and reliability.

Establishing a WebSocket Connection: From HTTP Upgrade to Full-Duplex Communication

Establishing a WebSocket connection involves several steps, starting with an HTTP request and culminating in a persistent, bidirectional communication channel. Let's walk through the process.

1. Client Initiates Handshake

The client sends an HTTP request to the server, requesting an upgrade to the WebSocket protocol. The request includes specific headers indicating the desire to establish a WebSocket connection.

Example Handshake Request:

GET /chat HTTP/1.1
Host: localhost:8080
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13

2. Server Responds with Upgrade Confirmation

If the server supports WebSockets and accepts the request, it responds with a 101 Switching Protocols status, confirming the upgrade.

Example Handshake Response:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=

3. WebSocket Connection Established

Once the handshake is successful, the protocol switches from HTTP to WebSocket. The connection remains open, allowing both client and server to send messages independently.

4. Full-Duplex Communication

Both parties can now send messages at any time without the need for additional HTTP requests. Messages are encapsulated in WebSocket frames, ensuring efficient data transfer.

Diagram: WebSocket Connection Flow

Client                               Server
  |                                     |
  |----- HTTP Upgrade Request --------> |
  |                                     |
  |<----- HTTP Upgrade Response --------|
  |                                     |
  |-------- WebSocket Frames ---------->|
  |<------- WebSocket Frames -----------|
  |                                     |
  |-------- WebSocket Frames ---------->|
  |<------- WebSocket Frames -----------|
  |                                     |
  |-------- Close Frame ----------------|
  |<------- Close Frame ----------------|
  |                                     |

Building a Real-Time Chat Application with Spring Boot, WebSockets, and STOMP

With a solid understanding of WebSockets and STOMP, let's apply this knowledge to build a real-time chat application using Spring Boot. This section will guide you through the entire process, from setting up the project to implementing backend and frontend functionalities.

Backend Configuration

Setting Up Spring Boot with WebSockets

To begin, the backend is powered by Spring Boot and leverages STOMP over WebSockets to facilitate real-time communication between the client and server. Here's a step-by-step breakdown of how we achieve this.

Add Dependencies

In your pom.xml, make sure to include the necessary Spring dependencies for WebSockets and messaging.

<dependencies>
    <!-- Spring Boot Starter for WebSockets -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-websocket</artifactId>
    </dependency>

    <!-- Spring Boot Starter for Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring Boot Starter for Messaging (STOMP support) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-websocket</artifactId>
    </dependency>
</dependencies>

1. WebSocket Configuration

To set up WebSockets in Spring Boot, you need to configure the WebSocket message broker and define WebSocket endpoints. This is done using the @EnableWebSocketMessageBroker annotation and implementing the WebSocketMessageBrokerConfigurer interface.

package com.gautam.ChatApplication.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.messaging.simp.config.MessageBrokerRegistry;
import org.springframework.web.socket.config.annotation.*;

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/ws") // WebSocket endpoint
                .setAllowedOrigins("*") // Allow cross-origin requests
                .withSockJS(); // Enable SockJS fallback options
    }

    @Override
    public void configureMessageBroker(MessageBrokerRegistry config) {
        config.enableSimpleBroker("/topic", "/queue"); // In-memory message broker
        config.setApplicationDestinationPrefixes("/app"); // Prefix for application destinations
    }
}

Explanation:

• @Configuration and @EnableWebSocketMessageBroker: Indicates that this class contains Spring configuration and enables WebSocket message handling, backed by a message broker.

• registerStompEndpoints: Defines the /ws endpoint that clients will use to connect to the WebSocket. withSockJS() enables fallback options for browsers that don’t support WebSockets.

• configureMessageBroker: Configures the message broker. The simple in-memory broker is enabled for destinations prefixed with /topic and /queue. Messages sent to destinations starting with /app are routed to message-handling methods.

2. Chat Controller

The ChatController handles incoming WebSocket messages and routes them to the appropriate destinations.

package com.gautam.ChatApplication.chat;

import org.springframework.messaging.handler.annotation.MessageMapping;
import org.springframework.messaging.handler.annotation.Payload;
import org.springframework.messaging.handler.annotation.SendTo;
import org.springframework.messaging.simp.SimpMessageHeaderAccessor;
import org.springframework.stereotype.Controller;

@Controller
public class ChatController {

    @MessageMapping("/chat.sendMessage")
    @SendTo("/topic/public")
    public ChatMessage sendMessage(@Payload ChatMessage chatMessage) {
        return chatMessage;
    }

    @MessageMapping("/chat.addUser")
    @SendTo("/topic/public")
    public ChatMessage addUser(@Payload ChatMessage chatMessage,
                               SimpMessageHeaderAccessor headerAccessor) {
        // Add username to WebSocket session
        headerAccessor.getSessionAttributes().put("username", chatMessage.getSender());
        return chatMessage;
    }
}

Explanation:

• @Controller: Marks the class as a Spring MVC Controller to handle WebSocket messages.

• @MessageMapping: Maps incoming messages to specific methods based on the destination. For example, messages sent to /app/chat.sendMessage are handled by sendMessage().

• @SendTo: Specifies the destination to which the return value will be sent. In this case, messages are broadcasted to /topic/public.

• @Payload: Binds the message payload to a method parameter.

• SimpMessageHeaderAccessor: Allows access to the message headers, enabling the addition of session attributes like username.

3. Chat Message Model

The ChatMessage class represents the structure of chat messages exchanged between clients and the server.

package com.gautam.ChatApplication.chat;

public class ChatMessage {
    private String sender;
    private String content;
    private MessageType type;

    // Constructors
    public ChatMessage() {
    }

    public ChatMessage(String sender, String content, MessageType type) {
        this.sender = sender;
        this.content = content;
        this.type = type;
    }

    public ChatMessage(String sender, MessageType type) {
        this.sender = sender;
        this.type = type;
    }

    // Getters and Setters
    public String getSender() {
        return sender;
    }

    public void setSender(String sender) {
        this.sender = sender;
    }

    public String getContent() {
        return content;
    }

    public void setContent(String content) {
        this.content = content;
    }

    public MessageType getType() {
        return type;
    }

    public void setType(MessageType type) {
        this.type = type;
    }
}

4. Message Type Enum

The MessageType enum defines the types of messages that can be exchanged, such as chat messages, user join, and user leave events.

package com.gautam.ChatApplication.chat;

public enum MessageType {
    CHAT,
    JOIN,
    LEAVE
}

5. Handling WebSocket Events

To manage user connections and disconnections, an event listener is implemented. This listener captures disconnection events and notifies other users when someone leaves the chat.

package com.gautam.ChatApplication.config;

import com.gautam.ChatApplication.chat.ChatMessage;
import com.gautam.ChatApplication.chat.MessageType;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.event.EventListener;
import org.springframework.messaging.simp.SimpMessageSendingOperations;
import org.springframework.messaging.simp.stomp.StompHeaderAccessor;
import org.springframework.stereotype.Component;
import org.springframework.web.socket.messaging.SessionDisconnectEvent;

@Component
@RequiredArgsConstructor
@Slf4j
public class WebSocketEventListener {

    private static final Logger log = LoggerFactory.getLogger(WebSocketEventListener.class);

    private final SimpMessageSendingOperations messageTemplate;

    @EventListener
    public void handleWebSocketDisconnect(SessionDisconnectEvent event) {
        StompHeaderAccessor headerAccessor = StompHeaderAccessor.wrap(event.getMessage());
        String username = (String) headerAccessor.getSessionAttributes().get("username");
        if (username != null) {
            log.info("User disconnected: {}", username);
            ChatMessage chatMessage = new ChatMessage(username, MessageType.LEAVE);
            messageTemplate.convertAndSend("/topic/public", chatMessage);
        }
    }
}

Explanation:

• @Component: Marks the class as a Spring bean for component scanning.

• @RequiredArgsConstructor: Lombok annotation to generate a constructor for messageTemplate, enabling dependency injection.

• @Slf4j: Lombok annotation to generate a logger instance.

• @EventListener: Listens for SessionDisconnectEvent, which is triggered when a WebSocket session is closed.

• handleWebSocketDisconnect(): Retrieves the username from session attributes and broadcasts a leave message to /topic/public.

Frontend: Using SockJS and STOMP in JavaScript

For the frontend, we can use SockJS and STOMP to connect to the WebSocket server. Here’s how you can set up the basic client-side logic.

// Connecting to WebSocket
const socket = new SockJS('http://localhost:8080/ws');  // Connect to the WebSocket endpoint
const stompClient = Stomp.over(socket);

// Function to connect to the WebSocket server
stompClient.connect({}, function (frame) {
    console.log('Connected: ' + frame);

    // Subscribe to the topic where messages will be broadcast
    stompClient.subscribe('/topic/messages', function (message) {
        const msgContent = JSON.parse(message.body);
        showMessage(msgContent.content, msgContent.sender); // Display received message
    });
});

// Function to send messages
function sendMessage() {
    const messageContent = document.getElementById('message').value;
    const sender = document.getElementById('sender').value;

    stompClient.send("/app/chat", {}, JSON.stringify({
        'content': messageContent,
        'sender': sender
    }));
}

// Function to display messages on the page
function showMessage(message, sender) {
    const messagesDiv = document.getElementById('messages');
    messagesDiv.innerHTML += `<p><strong>${sender}:</strong> ${message}</p>`;
}

• SockJS('http://localhost:8080/ws'): This connects to the WebSocket endpoint defined in the Spring Boot backend.

• stompClient.subscribe('/topic/messages', ...): Subscribes to the broadcast channel where messages are sent by the server.

• stompClient.send(...): Sends a message to the server.

Explanation of SockJS Functions

• SockJS: Provides WebSocket fallback options for browsers that don’t natively support WebSockets.

• Stomp.over(socket): Uses the WebSocket connection to communicate using the STOMP protocol.

• stompClient.connect(): Establishes the connection between the client and server.

• stompClient.subscribe(): Listens for messages broadcast from the server.

• stompClient.send(): Sends a message from the client to the server.

This is the basic setup for real-time communication using WebSockets on the client side.

Connect with me

For a complete implementation, please check my GitHub and LinkedIn:

• GitHub

• LinkedIn