Skip to main content

Spring WebSocket

Introduction to WebSockets​

WebSocket is a communication protocol that provides full-duplex communication channels over a single TCP connection. Unlike traditional HTTP, which is unidirectional where the client requests and the server responds, WebSockets allow for bi-directional, real-time communication between the client and server.

Spring Framework provides robust support for WebSocket through its Spring WebSocket module. This technology is particularly useful when you need to build applications requiring real-time updates such as:

  • Chat applications
  • Live notifications
  • Collaborative editing tools
  • Live data dashboards
  • Online gaming
  • Real-time analytics

In this guide, we'll explore how to implement WebSockets in Spring applications, starting from the basic concepts and moving to practical implementations.

Prerequisites​

Before diving into Spring WebSocket, make sure you have:

  • Basic knowledge of Spring Framework
  • Java Development Kit (JDK) 8 or higher
  • Maven or Gradle for dependency management
  • A code editor or IDE (like IntelliJ IDEA or Eclipse)

Getting Started with Spring WebSocket​

Setting Up a Spring WebSocket Project​

First, let's set up a basic Spring Boot project with WebSocket support. We'll use Maven for dependency management.

Add the following dependencies to your pom.xml:

xml
<dependencies>
    <!-- Spring Boot Starter WebSocket -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-websocket</artifactId>
    </dependency>
    
    <!-- Spring Boot Starter Web (for the web application) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- Optional: STOMP messaging -->
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>stomp-websocket</artifactId>
        <version>2.3.4</version>
    </dependency>
    
    <!-- Optional: SockJS for WebSocket emulation -->
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>sockjs-client</artifactId>
        <version>1.5.1</version>
    </dependency>
</dependencies>

WebSocket Configuration​

In Spring, WebSocket functionality needs to be explicitly configured. Let's create a configuration class:

java
package com.example.websocketdemo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.messaging.simp.config.MessageBrokerRegistry;
import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker;
import org.springframework.web.socket.config.annotation.StompEndpointRegistry;
import org.springframework.web.socket.config.annotation.WebSocketMessageBrokerConfigurer;

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void configureMessageBroker(MessageBrokerRegistry config) {
        // Enable a simple in-memory message broker
        config.enableSimpleBroker("/topic");
        
        // Set prefix for controller mapping
        config.setApplicationDestinationPrefixes("/app");
    }

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        // Register the "/ws" endpoint, enabling SockJS fallback options
        registry.addEndpoint("/ws").withSockJS();
    }
}

Let's understand this configuration:

  1. @EnableWebSocketMessageBroker enables WebSocket message handling backed by a message broker.
  2. configureMessageBroker():
    • enableSimpleBroker("/topic") - Enables a simple, in-memory message broker to carry messages back to client on destinations prefixed with "/topic"
    • setApplicationDestinationPrefixes("/app") - Messages prefixed with "/app" will be routed to message-handling methods in @Controller classes
  3. registerStompEndpoints() - Registers "/ws" as the WebSocket endpoint that clients will use to connect

Creating Message Models​

Now, let's define the message models that will be exchanged between client and server:

java
package com.example.websocketdemo.model;

// Incoming chat message from client
public class ChatMessage {
    private String content;
    private String sender;

    // Getters and setters
    public String getContent() {
        return content;
    }

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

    public String getSender() {
        return sender;
    }

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

Creating the WebSocket Controller​

Now we'll create a controller to handle WebSocket messages:

java
package com.example.websocketdemo.controller;

import com.example.websocketdemo.model.ChatMessage;
import org.springframework.messaging.handler.annotation.MessageMapping;
import org.springframework.messaging.handler.annotation.Payload;
import org.springframework.messaging.handler.annotation.SendTo;
import org.springframework.stereotype.Controller;

@Controller
public class ChatController {

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

In this controller:

  • @MessageMapping("/chat.sendMessage") - Messages sent to /app/chat.sendMessage will be routed to this method
  • @SendTo("/topic/public") - After processing, the returned message will be broadcast to clients subscribed to /topic/public
  • @Payload - Indicates that the method parameter should be bound to the payload of the message

Creating the Client-Side​

Let's now create a simple HTML and JavaScript frontend that will interact with our WebSocket server:

html
<!DOCTYPE html>
<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
    <title>Spring WebSocket Chat Application</title>
    <link rel="stylesheet" href="/css/main.css" />
    <script src="https://cdnjs.cloudflare.com/ajax/libs/sockjs-client/1.5.1/sockjs.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/stomp.js/2.3.3/stomp.min.js"></script>
</head>
<body>
    <div id="chat-container">
        <div class="chat-header">
            <h2>Spring WebSocket Chat</h2>
        </div>
        <div class="connecting">
            Connecting...
        </div>
        <ul id="messageArea">
        </ul>
        <form id="messageForm" name="messageForm">
            <div class="form-group">
                <div class="input-group clearfix">
                    <input type="text" id="message" placeholder="Type a message..." autocomplete="off" class="form-control"/>
                    <button type="submit" class="primary">Send</button>
                </div>
            </div>
        </form>
    </div>

    <script>
        var messageForm = document.querySelector('#messageForm');
        var messageInput = document.querySelector('#message');
        var messageArea = document.querySelector('#messageArea');
        var connectingElement = document.querySelector('.connecting');

        var stompClient = null;
        var username = 'User_' + Math.floor(Math.random() * 1000);

        function connect() {
            var socket = new SockJS('/ws');
            stompClient = Stomp.over(socket);

            stompClient.connect({}, onConnected, onError);
        }

        function onConnected() {
            // Subscribe to the Public Topic
            stompClient.subscribe('/topic/public', onMessageReceived);

            connectingElement.classList.add('hidden');
        }

        function onError(error) {
            connectingElement.textContent = 'Could not connect to WebSocket server. Please refresh this page to try again!';
            connectingElement.style.color = 'red';
        }

        function sendMessage(event) {
            var messageContent = messageInput.value.trim();
            if(messageContent && stompClient) {
                var chatMessage = {
                    sender: username,
                    content: messageContent
                };
                stompClient.send("/app/chat.sendMessage", {}, JSON.stringify(chatMessage));
                messageInput.value = '';
            }
            event.preventDefault();
        }

        function onMessageReceived(payload) {
            var message = JSON.parse(payload.body);
            
            var messageElement = document.createElement('li');

            var usernameElement = document.createElement('span');
            usernameElement.textContent = message.sender + ': ';
            messageElement.appendChild(usernameElement);

            var textElement = document.createElement('span');
            textElement.textContent = message.content;
            messageElement.appendChild(textElement);

            messageArea.appendChild(messageElement);
        }

        messageForm.addEventListener('submit', sendMessage, true);

        // Start the connection
        connect();
    </script>
</body>
</html>

This HTML file includes JavaScript for:

  1. Establishing a WebSocket connection using SockJS
  2. Subscribing to the public chat topic
  3. Sending messages to the server
  4. Receiving and displaying messages from the server

Advanced WebSocket Features​

User-Specific Messaging​

To send messages to specific users, we can use the SimpMessagingTemplate:

java
@Controller
public class PrivateChatController {
    
    @Autowired
    private SimpMessagingTemplate messagingTemplate;
    
    @MessageMapping("/private-message")
    public void processPrivateMessage(@Payload PrivateMessage privateMessage) {
        // Send to a specific user
        messagingTemplate.convertAndSendToUser(
            privateMessage.getRecipient(),
            "/queue/private-messages",
            privateMessage
        );
    }
}

With this configuration, messages will be sent to /user/{username}/queue/private-messages, which is a user-specific destination.

WebSocket Security​

To secure WebSocket communications, Spring Security can be integrated. Here's a basic configuration:

java
@Configuration
@EnableWebSocketSecurity
public class WebSocketSecurityConfig extends AbstractSecurityWebSocketMessageBrokerConfigurer {

    @Override
    protected void configureInbound(MessageSecurityMetadataSourceRegistry messages) {
        messages
            .simpDestMatchers("/app/**").authenticated()
            .simpSubscribeDestMatchers("/user/**", "/topic/**").authenticated()
            .anyMessage().denyAll();
    }
    
    @Override
    protected boolean sameOriginDisabled() {
        return true;
    }
}

Integrating with External Message Brokers​

For production applications, you might want to use an external message broker like RabbitMQ or ActiveMQ:

java
@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void configureMessageBroker(MessageBrokerRegistry registry) {
        // Use RabbitMQ as the external message broker
        registry.enableStompBrokerRelay("/topic", "/queue")
                .setRelayHost("localhost")
                .setRelayPort(61613)
                .setClientLogin("guest")
                .setClientPasscode("guest");
                
        registry.setApplicationDestinationPrefixes("/app");
    }
    
    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/ws").withSockJS();
    }
}

Real-World Application: Building a Live Dashboard​

Now, let's implement a practical example: a real-time dashboard that displays server metrics.

Server-Side Metric Generator​

First, let's create a scheduled task to simulate server metrics:

java
@Component
public class ServerMetricGenerator {

    @Autowired
    private SimpMessagingTemplate messagingTemplate;
    
    private final Random random = new Random();
    
    @Scheduled(fixedRate = 5000)  // Every 5 seconds
    public void sendServerMetrics() {
        ServerMetric metric = new ServerMetric();
        metric.setCpuUsage(random.nextInt(100));  // 0-100%
        metric.setMemoryUsage(random.nextInt(100));  // 0-100%
        metric.setActiveUsers(random.nextInt(500));  // 0-500 users
        metric.setTimestamp(System.currentTimeMillis());
        
        messagingTemplate.convertAndSend("/topic/metrics", metric);
    }
}

Server Metric Model​

java
public class ServerMetric {
    private int cpuUsage;
    private int memoryUsage;
    private int activeUsers;
    private long timestamp;
    
    // Getters and setters
    // ...
}

Client-Side Dashboard​

html
<!DOCTYPE html>
<html>
<head>
    <title>Real-time Server Dashboard</title>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/chart.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/sockjs-client/1.5.1/sockjs.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/stomp.js/2.3.3/stomp.min.js"></script>
    <style>
        .dashboard {
            display: flex;
            flex-direction: column;
            width: 800px;
            margin: 0 auto;
        }
        .metric-chart {
            margin: 20px 0;
            height: 200px;
        }
    </style>
</head>
<body>
    <div class="dashboard">
        <h1>Server Metrics Dashboard</h1>
        <div class="metric-chart">
            <canvas id="cpuChart"></canvas>
        </div>
        <div class="metric-chart">
            <canvas id="memoryChart"></canvas>
        </div>
        <div class="metric-chart">
            <canvas id="usersChart"></canvas>
        </div>
    </div>

    <script>
        // Initialize charts
        const cpuChart = new Chart(
            document.getElementById('cpuChart'),
            {
                type: 'line',
                data: {
                    labels: [],
                    datasets: [{
                        label: 'CPU Usage (%)',
                        data: [],
                        borderColor: 'rgb(75, 192, 192)',
                        tension: 0.1
                    }]
                },
                options: {
                    scales: {
                        y: {
                            beginAtZero: true,
                            max: 100
                        }
                    }
                }
            }
        );
        
        // Similar initialization for memory and users charts
        // ...
        
        // Connect to WebSocket
        const socket = new SockJS('/ws');
        const stompClient = Stomp.over(socket);
        
        stompClient.connect({}, function() {
            console.log('Connected to WebSocket');
            
            stompClient.subscribe('/topic/metrics', function(message) {
                const metric = JSON.parse(message.body);
                
                // Format timestamp for display
                const time = new Date(metric.timestamp).toLocaleTimeString();
                
                // Update CPU chart
                if (cpuChart.data.labels.length > 10) {
                    cpuChart.data.labels.shift();
                    cpuChart.data.datasets[0].data.shift();
                }
                cpuChart.data.labels.push(time);
                cpuChart.data.datasets[0].data.push(metric.cpuUsage);
                cpuChart.update();
                
                // Update other charts similarly
                // ...
            });
        });
    </script>
</body>
</html>

This example demonstrates:

  1. Using a scheduled task to simulate real-time data
  2. Broadcasting this data to all clients subscribed to a topic
  3. Visualizing the data in real-time using Chart.js

Common Pitfalls and Best Practices​

Pitfalls to Avoid​

  1. Not implementing fallbacks: Not all browsers support WebSockets. Always use SockJS or a similar library to provide fallbacks.

  2. Overusing WebSockets: WebSockets maintain an open connection, which consumes server resources. Use them only when real-time communication is necessary.

  3. Not handling reconnections: Network disruptions can occur. Implement reconnection logic on the client side.

  4. Ignoring scalability: Simple brokers work for development but might not handle production loads. Consider external message brokers.

Best Practices​

  1. Message validation: Always validate incoming messages to prevent malicious inputs.

  2. Use STOMP for structure: STOMP provides a structured messaging protocol on top of WebSockets.

  3. Secure your connections: Use authentication and authorization for WebSocket connections.

  4. Implement heartbeats: To keep connections alive and detect disconnections.

  5. Monitor WebSocket usage: Monitor the number of connections and message throughput.

Summary​

In this guide, we've learned:

  1. The basics of WebSockets and how they differ from traditional HTTP
  2. How to set up Spring WebSocket in a Spring Boot application
  3. Creating controllers to handle WebSocket messages
  4. Building a client to connect to our WebSocket server
  5. Advanced features like user-specific messaging and security
  6. A real-world example of a real-time dashboard

WebSockets provide powerful capabilities for building real-time features in web applications. Spring's WebSocket support makes it straightforward to implement these features in your Java applications.

Further Resources​

To deepen your understanding of Spring WebSocket:

  1. Official Spring WebSocket Documentation
  2. Spring WebSocket Guide
  3. STOMP Protocol Specification

Exercises​

  1. Basic Chat: Extend the chat application to show when users join or leave.

  2. User Status: Create a feature that shows which users are online.

  3. Typing Indicator: Implement a "user is typing" indicator.

  4. Message History: Store and display recent message history when a user joins.

  5. Advanced: Implement a collaborative drawing application using WebSockets where multiple users can draw on the same canvas in real-time.

Happy coding!


If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)