So erstellen Sie einen WebSocket-Server mit der Java-API für WebSockets

Dieser Artikel wurde im August 2025 aktualisiert.

WebSocket ist ein Protokoll, das es einem Server und einem Client (wie einem Browser oder einer mobilen Anwendung) ermöglicht, in Echtzeit miteinander zu kommunizieren. Im Gegensatz zu RESTful HTTP, bei dem der Client ständig nach Aktualisierungen suchen muss (ein Prozess namens Abfrage), hält WebSocket eine konstante, bidirektionale Verbindung offen. Das bedeutet, dass der Server Aktualisierungen an den Client senden kann, sobald sich etwas ändert, so dass der Client nicht auf eine Anfrage warten muss.

In diesem Tutorial zeigen wir Ihnen, wie Sie einen WebSocket-Server in Java unter Verwendung der Jakarta WebSocket API (JSR 356) implementieren.

Voraussetzungen

• Java-Entwicklungskit (JDK) 17 oder neuer (Java 16+ wird jetzt von Gretty v4.1.6 unterstützt)

• Gradle, ausführen brew install gradle oder sdk install gradleaus, oder folgen Sie der Gradle-Installationsanleitung.

Die Java-API für WebSockets

Die in Java EE 7 eingeführte Java-API für WebSocketsoder JSR 356, ist eine Spezifikation, die Java-Entwickler verwenden können, um WebSockets in ihre Anwendungen zu integrieren.

Es ermöglicht Entwicklern, ihre WebSocket-basierte Anwendung völlig unabhängig von der Implementierung ihres Containers zu schreiben. Für diesen Leitfaden werden Sie Folgendes verwenden Tomcat. Da Sie jedoch JSR 356 verwenden werden, sollte jeder andere Web-Container, der Jakarta EE 9 oder höher unterstützt, funktionieren.

Das Projekt erstellen

Sie werden Gradle verwenden, um eine neue Java-Anwendung zu initialisieren. Sie können den folgenden Befehl verwenden, um ein Verzeichnis für Ihr Projekt zu erstellen, zu diesem Verzeichnis zu navigieren und die Anwendung zu initialisieren:

Erstellen Sie ein neues Gradle-Projekt:

1. Führen Sie aus. gradle init --type=java-application Befehl

2. Wählen Sie Groovy als Skriptsprache

3. Wählen Sie JUnit Jupiter als Test-Framework

4. Standard verlassen Project name

5. Standard verlassen Source package

Hinzufügen der Java WebSocket API-Abhängigkeit

Fügen Sie die folgende Abhängigkeit zu dem dependencies Block der app/build.gradle Datei hinzu:

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

Jakarta EE 9+ verwendet den jakarta.websocket Namespace anstelle von javax.websocket, und Tomcat 10+ folgt dieser Konvention.

Erstellen des WebSocket-Endpunkts

WebSocket-Nachrichten können sowohl Text als auch binär sein. Sie werden einen Endpunkt erstellen, der beide Arten von Nachrichten verarbeiten kann.

Die @ServerEndpoint Annotation wird verwendet, um eine Klasse zu dekorieren und sie als WebSocket-Endpunkt zu deklarieren. Die Annotation nimmt ein Pfadargument auf, das definiert, wo der Endpunkt zugänglich sein wird.

Erstellen Sie eine neue Klasse namens WebSocketEndpoint innerhalb des Ordners src/main/java/websocket/java/api Ordner und fügen Sie den folgenden Code hinzu:

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;
    }
}

Die @OnMessage Annotation verknüpft Java-Methoden mit eingehenden Text- oder binären WebSocket-Nachrichten. Die Signatur der Methode bestimmt, welche Art von Nachricht sie verarbeitet. Zum Beispiel, String wird für Text verwendet und byte[] ist für binäre Nachrichten.

In diesem Beispiel erstellen Sie einen Echo-Server, der dieselbe Nachricht zurücksendet, die er empfängt. Der maxMessageSize Parameter des Binär-Handlers ermöglicht es dem Server, große Nutzdaten wie z. B. Bilddateien zu akzeptieren. Sie werden dies mit einem browserbasierten Client im weiteren Verlauf des Tutorials testen.

Erstellen Sie einen Client zum Testen Ihrer Anwendung

Sie müssen einen Client erstellen, um Ihren WebSocket-Server zu testen. Sie werden testen wollen, ob Sie sowohl Text- als auch Binärnachrichten senden können. Dies lässt sich mit einer einfachen, in HTML und JavaScript geschriebenen Anwendung bewerkstelligen.

Erstellen Sie den webapp Ordner innerhalb des src/main Ordners.

Fügen Sie folgendes zu index.html innerhalb des Ordners src/main/webapp Ordners hinzu:

<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>

Tomcat einbinden und konfigurieren

Im Gegensatz zu Erstellen eines WebSocket-Servers mit Spring Bootoder Erstellen eines WebSocket-Servers mit dem Spark-Frameworkgibt es zunächst keinen eingebetteten Server, auf dem Ihre Anwendung läuft.

Die Gretty Plugin für Gradle kann verwendet werden, um eine Vielzahl von Containern einzubetten.

Wenden Sie zunächst das Gretty-Plugin auf die build.gradle Datei an, indem Sie dies zu Ihrem plugins Block hinzufügen:

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

Zweitens müssen Sie Gretty so konfigurieren, dass Tomcat als Servlet-Container verwendet wird, und den Kontextpfad auf / der Einfachheit halber.

Fügen Sie den folgenden Block zu build.gradle:

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

Gretty 3.0.5+ unterstützt tomcat10 für die Kompatibilität mit Jakarta EE 9+ (jakarta.* Namespaces).

Beachten Sie, dass Gretty standardmäßig Jetty als Servlet-Container verwendet. Dieselbe Anleitung wird auch in Jetty ausgeführt, aber das ist derselbe Container, den sowohl Spring Boot als auch das Spark-Framework einbetten, und ich wollte etwas anderes zeigen.

Starten Sie die Anwendung

Ihr WebSocket-Server ist nun vollständig. Starten Sie Ihre Anwendung mit dem gradle appRun Befehl innerhalb des Verzeichnisses der Anwendung.

Stellen Sie sicher, dass Ihr JAVA_HOME auf JDK 21 eingestellt ist, bevor Sie die Anwendung ausführen:

Lassen Sie das Terminalfenster geöffnet.

Sie können auf Ihre Bewerbung zugreifen, indem Sie http://localhost:8080 URL im Browser öffnen.

Sie werden mit der folgenden Seite begrüßt:

Sample JavaScript-enabled client for testing the WebSocket serverDie Meldung "connected" zeigt an, dass der JavaScript-Client eine Verbindung herstellen konnte.

Versuchen Sie, eine Textnachricht zu senden, indem Sie in das Eingabefeld tippen und auf die Schaltfläche "Senden" klicken. Versuchen Sie auch, ein Bild hochzuladen. In beiden Fällen sollten Sie die gleiche Nachricht und das gleiche Bild zurückerhalten.

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

Schlussfolgerung

Sie haben erfolgreich einen WebSocket-Server unter Verwendung der Java-API für WebSockets (JSR 356) erstellt, ihn mit Gretty in einen Tomcat-Container eingebettet und mit einem einfachen HTML- und JavaScript-Client getestet.

Mit dieser Einrichtung können Sie die Zwei-Wege-Kommunikation zwischen Ihrem Server und den Clients in Echtzeit sowohl mit Text- als auch mit Binärdaten abwickeln.

Die nächsten Schritte könnten das Hinzufügen von Authentifizierung, die Verarbeitung weiterer Nachrichtentypen oder die Integration in Ihre bestehenden Java Applications sein.