Comment créer un serveur WebSocket avec l'API Java pour WebSockets

Cet article a été mis à jour en août 2025

WebSocket est un protocole qui permet à un serveur et à un client (comme un navigateur ou une application mobile) de communiquer en temps réel. Contrairement à RESTful HTTP, où le client doit constamment vérifier les mises à jour (un processus appelé polling), WebSocket maintient une connexion bidirectionnelle constante. Cela signifie que le serveur peut envoyer des mises à jour au client chaque fois que quelque chose change, et qu'il n'est donc pas nécessaire d'attendre que le client le demande.

Dans ce tutoriel, nous allons vous expliquer comment mettre en œuvre un serveur WebSocket en Java en utilisant l'API Jakarta WebSocket (JSR 356).

Conditions préalables

• Kit de développement Java (JDK) 17 ou plus récent (Java 16+ est maintenant supporté par Gretty v4.1.6)

• Gradle, exécuter brew install gradle ou sdk install gradleou suivez le guide d'installation de Guide d'installation de Gradle.

L'API Java pour les WebSockets

Introduite dans Java EE 7, l Java API for WebSocketsou JSR 356, est une spécification que les développeurs Java peuvent utiliser pour intégrer les WebSockets dans leurs Applications.

Il permet aux développeurs d'écrire leur application basée sur WebSocket de manière totalement indépendante de l'implémentation de leur conteneur. Pour ce guide, vous utiliserez Tomcat. Cependant, étant donné que vous utiliserez la JSR 356, tout autre conteneur web supportant Jakarta EE 9 ou une version ultérieure devrait fonctionner.

Créer le projet

Vous allez utiliser Gradle pour initialiser une nouvelle application Java. Vous pouvez utiliser la commande suivante pour créer un répertoire pour votre projet, naviguer vers ce répertoire et initialiser l'application :

Créer un nouveau projet Gradle :

1. Exécuter gradle init --type=java-application commande

2. Sélectionner Groovy comme langue de script

3. Sélectionner JUnit Jupiter comme cadre de test

4. Laisser la valeur par défaut Project name

5. Laisser la valeur par défaut Source package

Ajouter la dépendance de l'API Java WebSocket

Ajoutez la dépendance suivante au bloc dependencies du fichier app/build.gradle de fichier :

implementation 'jakarta.websocket:jakarta.websocket-api:2.1.1'

Jakarta EE 9+ utilise l'espace de noms jakarta.websocket au lieu de javax.websocketet Tomcat 10+ suit cette convention.

Créer le point de terminaison WebSocket

Les messages WebSocket peuvent être à la fois textuels et binaires. Vous allez créer un point de terminaison capable de gérer ces deux types de messages.

L'annotation @ServerEndpoint est utilisée pour décorer une classe et la déclarer comme point de terminaison WebSocket. L'annotation prend un argument de chemin qui définit l'endroit où le point de terminaison sera accessible.

Créer une nouvelle classe appelée WebSocketEndpoint dans le dossier src/main/java/websocket/java/api et ajoutez le code suivant :

import jakarta.websocket.server.ServerEndpoint;
import jakarta.websocket.OnMessage;

@ServerEndpoint("/socket")
public class WebSocketEndpoint {
    @OnMessage
    public String handleTextMessage(String message) {
        System.out.println("New Text Message Received");
        return message;
    }

    @OnMessage(maxMessageSize = 1024000)
    public byte[] handleBinaryMessage(byte[] buffer) {
        System.out.println("New Binary Message Received");
        return buffer;
    }
}

L'annotation @OnMessage lie les méthodes Java aux messages WebSocket textuels ou binaires entrants. La signature de la méthode détermine le type de message qu'elle traite. Par exemple, String est utilisée pour le texte et byte[] est utilisé pour les messages binaires.

Dans cet exemple, vous créez un serveur d'écho qui renvoie le même message que celui qu'il reçoit. Le paramètre maxMessageSize du gestionnaire binaire permet au serveur d'accepter des charges utiles volumineuses telles que des fichiers images. Vous testerez ceci en utilisant un client basé sur un navigateur plus tard dans le tutoriel.

Créer un client pour tester votre application

Vous devrez créer un client pour tester votre serveur WebSocket. Vous voudrez tester l'envoi de messages textuels et binaires. Ceci peut être réalisé avec une simple application écrite en HTML et JavaScript.

Créez le dossier webapp à l'intérieur du dossier src/main à l'intérieur du dossier

Ajoutez ce qui suit à index.html à l'intérieur du dossier src/main/webapp à l'intérieur du dossier

<html>
<head>
    <style>
        #messages {
            text-align: left;
            width: 50%;
            padding: 1em;
            border: 1px solid black;
        }
    </style>
    <title>Sample WebSocket Client</title>
</head>
<body>
<div class="container">
    <div id="messages" class="messages"></div>
    <div class="input-fields">
        <p>Type a message and hit send:</p>
        <input id="message"/>
        <button id="send">Send</button>

        <p>Select an image and hit send:</p>
        <input type="file" id="file" accept="image/*"/>

        <button id="sendImage">Send Image</button>
    </div>
</div>
</body>
<script>
    const messageWindow = document.getElementById("messages");

    const sendButton = document.getElementById("send");
    const messageInput = document.getElementById("message");

    const fileInput = document.getElementById("file");
    const sendImageButton = document.getElementById("sendImage");

    const socket = new WebSocket("ws://localhost:8080/socket");
    socket.binaryType = "arraybuffer";

    socket.onopen = function (event) {
        addMessageToWindow("Connected");
    };

    socket.onmessage = function (event) {
        if (event.data instanceof ArrayBuffer) {
            addMessageToWindow('Got Image:');
            addImageToWindow(event.data);
        } else {
            addMessageToWindow(`Got Message: ${event.data}`);
        }
    };

    sendButton.onclick = function (event) {
        sendMessage(messageInput.value);
        messageInput.value = "";
    };

    sendImageButton.onclick = function (event) {
        let file = fileInput.files[0];
        sendMessage(file);
        fileInput.value = null;
    };

    function sendMessage(message) {
        socket.send(message);
        addMessageToWindow("Sent Message: " + message);
    }

    function addMessageToWindow(message) {
        messageWindow.innerHTML += `<div>${message}</div>`
    }

    function addImageToWindow(image) {
        let url = URL.createObjectURL(new Blob([image]));
        messageWindow.innerHTML += `<img src="${url}"/>`
    }
</script>
</html>

Intégrer et configurer Tomcat

Contrairement à Créer un serveur WebSocket avec Spring Bootou Créer un serveur WebSocket avec Spark Framework, il n'y a initialement pas de serveur embarqué pour exécuter votre application.

Les Gretty pour Gradle peut être utilisé pour intégrer une variété de conteneurs.

Tout d'abord, appliquez le plugin Gretty au fichier build.gradle en ajoutant ceci à votre plugins bloc :

plugins {
    id 'org.gretty' version '4.1.7'
}

Deuxièmement, vous devrez configurer Gretty pour qu'il utilise Tomcat comme conteneur de servlet, et définir le chemin du contexte à / pour des raisons de simplicité.

Ajouter le bloc suivant à build.gradle:

gretty {
    servletContainer = 'tomcat10'
    contextPath = '/'
}

Gretty 3.0.5+ supporte tomcat10 pour la compatibilité avec Jakarta EE 9+ (jakarta.* espaces de noms).

Notez que, par défaut, Gretty utilisera Jetty comme conteneur de servlet. Ce même guide s'exécutera également dans Jetty, mais c'est le même conteneur que Spring Boot et le framework Spark intègrent et je voulais montrer quelque chose de différent.

Démarrer l'application

Votre serveur WebSocket est maintenant terminé. Démarrez votre application en utilisant la commande gradle appRun dans le répertoire de l'application.

Assurez-vous que votre JAVA_HOME est défini sur JDK 21 avant d'exécuter l'application :

Laissez la fenêtre du terminal ouverte.

Vous pouvez accéder à votre application en ouvrant http://localhost:8080 dans le navigateur.

La page suivante s'affiche :

Sample JavaScript-enabled client for testing the WebSocket serverLe message "connecté" indique que le client JavaScript a pu établir une connexion.

Essayez d'envoyer un message texte en tapant dans le champ de saisie et en cliquant sur le bouton d'envoi. Essayez également de télécharger une image. Dans les deux cas, vous devriez voir le même message et la même image renvoyés.

Sample JavaScript-enabled client showing a text and binary message echoed back.

Conclusion

Vous avez réussi à créer un serveur WebSocket en utilisant l'API Java pour les WebSockets (JSR 356), à l'intégrer dans un conteneur Tomcat avec Gretty et à le tester avec un simple client HTML et JavaScript.

Cette configuration vous permet de gérer une communication bidirectionnelle en temps réel entre votre serveur et vos clients avec des données textuelles et binaires.

Les prochaines étapes pourraient consister à ajouter l'authentification, à gérer davantage de types de messages ou à s'intégrer à vos applications Java existantes.