Como criar um servidor WebSocket com a API Java para WebSockets

Este artigo foi atualizado em agosto de 2025

WebSocket é um protocolo que permite que um servidor e um cliente (como um navegador ou aplicativo móvel) se comuniquem em tempo real. Ao contrário do HTTP RESTful, em que o cliente precisa verificar constantemente se há atualizações (um processo chamado polling), o WebSocket mantém uma conexão bidirecional constante aberta. Isso significa que o servidor pode enviar atualizações ao cliente sempre que algo mudar, de modo que não há necessidade de esperar que o cliente solicite.

Neste tutorial, vamos explicar passo a passo como implementar um servidor WebSocket em Java usando a API Jakarta WebSocket (JSR 356).

Pré-requisitos

• Kit de Desenvolvimento Java (JDK) 17 ou mais recente (o Java 16+ agora é compatível com o Gretty v4.1.6)

• Gradle, execute brew install gradle ou sdk install gradle, ou siga o guia de instalação do Gradle.

A API Java para WebSockets

Introduzida no Java EE 7, a API Java para WebSockets, ou JSR 356, é uma especificação que os desenvolvedores Java podem usar para integrar WebSockets em suas aplicações.

Isso permite que os desenvolvedores criem suas aplicações baseadas em WebSocket de forma totalmente independente da implementação do contêiner. Neste guia, você utilizará o o Tomcat. No entanto, como você utilizará a JSR 356, qualquer outro contêiner web compatível com o Jakarta EE 9 ou versões posteriores deve funcionar.

Criar o projeto

Você usará o Gradle para inicializar um novo aplicativo Java. É possível usar o comando a seguir para criar um diretório para o seu projeto, acessar esse diretório e inicializar o aplicativo:

Crie um novo projeto Gradle:

1. Execute gradle init --type=java-application o comando

2. Selecione Groovy como linguagem de script

3. Selecione JUnit Jupiter como estrutura de testes

4. Manter o padrão Project name

5. Manter o padrão Source package

Adicionar a dependência da API WebSocket do Java

Adicione a seguinte dependência ao dependencies bloco do app/build.gradle arquivo:

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

O Jakarta EE 9+ utiliza o jakarta.websocket namespace em vez de javax.websocket, e o Tomcat 10+ segue essa convenção.

Criar o ponto de extremidade do WebSocket

As mensagens WebSocket podem ser tanto de texto quanto binárias. Você vai criar um endpoint capaz de lidar com ambos os tipos de mensagem.

A @ServerEndpoint anotação é usada para decorar uma classe e declará-la como um ponto de extremidade WebSocket. A anotação recebe um argumento de caminho que define onde o ponto de extremidade estará acessível.

Crie uma nova classe chamada WebSocketEndpoint dentro da src/main/java/websocket/java/api pasta e adicione o seguinte código:

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

A @OnMessage anotação vincula métodos Java a mensagens WebSocket de texto ou binárias recebidas. A assinatura do método determina qual tipo de mensagem ele processa. Por exemplo, String é usado para texto e byte[] é para binário.

Neste exemplo, você está criando um servidor “echo” que retorna a mesma mensagem que recebe. O maxMessageSize parâmetro no manipulador binário permite que o servidor aceite cargas úteis grandes, como arquivos de imagem. Você testará isso usando um cliente baseado em navegador mais adiante neste tutorial.

Crie um cliente para testar seu aplicativo

Você precisará criar um cliente para testar seu servidor WebSocket. É recomendável testar o envio tanto de mensagens de texto quanto de mensagens binárias. Isso pode ser feito com um aplicativo simples escrito em HTML e JavaScript.

Crie a webapp pasta dentro da src/main pasta.

Adicione o seguinte ao index.html dentro da src/main/webapp pasta:

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

Incorporar e configurar o Tomcat

Ao contrário de Criação de um servidor WebSocket com Spring Boot, ou Criação de um servidor WebSocket com o Spark Framework, inicialmente não há nenhum servidor embutido para executar sua aplicação.

O plug-in para o Gradle pode ser usado para incorporar diversos tipos de contêineres.

Primeiro, aplique o plugin Gretty ao build.gradle arquivo, adicionando isto ao seu plugins bloco:

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

Em segundo lugar, você precisará configurar o Gretty para usar o Tomcat como contêiner de servlets e definir o caminho de contexto como / por uma questão de simplicidade.

Adicione o bloco a seguir a build.gradle:

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

O Gretty 3.0.5+ oferece suporte tomcat10 compatibilidade com o Jakarta EE 9+ (jakarta.* namespaces).

Observe que, por padrão, o Gretty usa o Jetty como contêiner de servlets. Este mesmo guia também funcionaria no Jetty, mas esse é o mesmo contêiner que tanto o Spring Boot quanto a estrutura Spark incorporam, e eu queria mostrar algo diferente.

Iniciar o aplicativo

Seu servidor WebSocket já está pronto. Inicie seu aplicativo usando o gradle appRun comando dentro do diretório do aplicativo.

Certifique-se de que seu JAVA_HOME esteja configurado para o JDK 21 antes de executar o aplicativo:

Deixe a janela do terminal aberta.

Você pode acessar seu aplicativo abrindo http://localhost:8080 no navegador.

Você será direcionado para a seguinte página:

Sample JavaScript-enabled client for testing the WebSocket serverA mensagem “conectado” indica que o cliente JavaScript conseguiu estabelecer uma conexão.

Tente enviar uma mensagem de texto digitando no campo de entrada e clicando no botão “Enviar”. Tente também fazer o upload de uma imagem. Em ambos os casos, você deverá ver a mesma mensagem e a mesma imagem exibidas de volta.

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

Conclusão

Você criou com sucesso um servidor WebSocket usando a API Java para WebSockets (JSR 356), incorporou-o a um contêiner Tomcat com o Gretty e o testou com um cliente simples em HTML e JavaScript.

Essa configuração permite que você gerencie a comunicação bidirecional em tempo real entre o servidor e os clientes, tanto com dados de texto quanto com dados binários.

Os próximos passos poderiam incluir a adição de autenticação, o tratamento de mais tipos de mensagens ou a integração com suas aplicações Java existentes.