Table of Contents

Expose a WebSocket Server in a Micronaut Application

Build a chat application by exposing a WebSocket Server with the Micronaut Framework

Authors: Dan Hollingsworth, Sergio del Amo

Micronaut Version: 4.6.3

1. Getting Started

In this guide, we will create a Micronaut application written in Java.

The WebSocket Protocol allows for web browsers to establish interactive sessions with a server that are event-driven. This technology is ideal for applications that need state changes without the overhead and latency of polling the server. The article "Introduction to WebSockets" explains the benefits of WebSocket in more depth, along with a discussion of the client-side WebSocket API.

This guide will take you through the creation of an event-driven chat application utilizing Micronaut WebSocket.

2. What you will need

To complete this guide, you will need the following:

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

4. Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide \
    --features=yaml,websocket,validation,reactor,awaitility,graalvm \
    --build=gradle \
    --lang=java \
    --test=junit
If you don’t specify the --build argument, Gradle with the Kotlin DSL is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.
If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

If you use Micronaut Launch, select Micronaut Application as application type and add yaml, websocket, validation, reactor, awaitility, and graalvm features.

If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features, and apply those changes to your application.

Diff

Setup IntelliJ IDEA to develop Micronaut Applications.

4.1. Static Resources

Update application.yml to add static resource configuration:

Since Micronaut Framework 4.0, to use YAML configuration, you have to add the YAML dependency.
src/main/resources/application.yml
micronaut:
    router:
        static-resources: (1)
            default:
                enabled: true
                mapping: /**
                paths: classpath:public
1 Configure the Framework to look for static resources in src/main/resources/public.

4.2. Front End

4.2.1. HTML

Add the HTML page to be the user interface for the chat client in the browser:

src/main/resources/public/index.html
<!DOCTYPE html>
<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>WebSocket Demo</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
<div id="chatControls">
    <input id="message" placeholder="Type your message">
    <button id="send">Send</button>
</div>
<ul id="userlist"> <!-- Built by JS --> </ul>
<div id="chat">    <!-- Built by JS --> </div>
<script src="websocketDemo.js"></script>
</body>
</html>

4.2.2. Javascript

Write JavaScript to parse the URL for the chat topic and username, handle the message body, broadcast the chat, and keep the DOM updated with the latest messages:

src/main/resources/public/websocketDemo.js
//Establish the WebSocket connection and set up event handlers
var hash = document.location.hash.split("/");

if (hash.length !== 3) {
    alert("Specify URI with a topic and username. "
    + "Example http://localhost:8080#/stuff/bob")
}

var webSocket = new WebSocket("ws://" +
    location.hostname +
    ":" +
    location.port +
    "/ws/chat/" +
    hash[1] +
    "/" +
    hash[2]);
webSocket.onmessage = function (msg) { updateChat(msg); };
webSocket.onclose = function () { alert("WebSocket connection closed") };

//Send message if "Send" is clicked
id("send").addEventListener("click", function () {
    sendMessage(id("message").value);
});

//Send message if enter is pressed in the input field
id("message").addEventListener("keypress", function (e) {
    if (e.keyCode === 13) { sendMessage(e.target.value); }
});

//Send a message if it's not empty, then clear the input field
function sendMessage(message) {
    if (message !== "") {
        webSocket.send(message);
        id("message").value = "";
    }
}

//Update the chat-panel, and the list of connected users
function updateChat(msg) {
    insert("chat", msg.data);
}

//Helper function for inserting HTML as the first child of an element
function insert(targetId, message) {
    id(targetId).insertAdjacentHTML("afterbegin", "<p>" + message + "</p>");
}

//Helper function for selecting element by id
function id(id) {
    return document.getElementById(id);
}

4.2.3. CSS

Style the page so that the messages are properly displayed:

src/main/resources/public/style.css
* {
    box-sizing: border-box;
}

html {
    overflow-y: scroll;
}

body {
    font-family: monospace;
    font-size: 14px;
    max-width: 480px;
    margin: 0 auto;
    padding: 20px;
}

input {
    width: 100%;
    padding: 5px;
    margin: 5px 0;
}

button {
    float: right;
}

li {
    margin: 5px 0;
}

#chatControls {
    overflow: auto;
    margin: 0 0 5px 0;
}

#userlist {
    position: fixed;
    left: 50%;
    list-style: none;
    margin-left: 250px;
    background: #f0f0f9;
    padding: 5px 10px;
    width: 150px;
    top: 11px;
}

#chat p {
    margin: 5px 0;
    font-weight: 300;
}

#chat .timestamp {
    position: absolute;
    top: 10px;
    right: 10px;
    font-size: 12px;
}

#chat article {
    background: #f1f1f1;
    padding: 10px;
    margin: 10px 0;
    border-left: 5px solid #aaa;
    position: relative;
    word-wrap: break-word;
}

#chat article:first-of-type {
    background: #c9edc3;
    border-left-color: #74a377;
    animation: enter .2s 1;
}

@keyframes enter {
    from { transform: none;        }
    50%  { transform: scale(1.05); }
    to   { transform: none;        }
}

4.3. Chat server

Our chat server is very simple. It merely allows you to connect and broadcast messages to subscribers of the topic. There’s also a special topic called "all" that can make announcements and receive messages from all topics.

src/main/java/example/micronaut/ChatServerWebSocket.java
package example.micronaut;

import io.micronaut.websocket.WebSocketBroadcaster;
import io.micronaut.websocket.WebSocketSession;
import io.micronaut.websocket.annotation.OnClose;
import io.micronaut.websocket.annotation.OnMessage;
import io.micronaut.websocket.annotation.OnOpen;
import io.micronaut.websocket.annotation.ServerWebSocket;
import org.reactivestreams.Publisher;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.function.Predicate;

@ServerWebSocket("/ws/chat/{topic}/{username}") (1)
public class ChatServerWebSocket {

    private static final Logger LOG = LoggerFactory.getLogger(ChatServerWebSocket.class);

    private final WebSocketBroadcaster broadcaster;

    public ChatServerWebSocket(WebSocketBroadcaster broadcaster) { (2)
        this.broadcaster = broadcaster;
    }

    @OnOpen (3)
    public Publisher<String> onOpen(String topic, String username, WebSocketSession session) {
        log("onOpen", session, username, topic);
        if (topic.equals("all")) { (4)
            return broadcaster.broadcast(String.format("[%s] Now making announcements!", username), isValid(topic));
        }
        return broadcaster.broadcast(String.format("[%s] Joined %s!", username, topic), isValid(topic));
    }

    @OnMessage (5)
    public Publisher<String> onMessage(
            String topic,
            String username,
            String message,
            WebSocketSession session) {

        log("onMessage", session, username, topic);
        return broadcaster.broadcast(String.format("[%s] %s", username, message), isValid(topic));
    }

    @OnClose (6)
    public Publisher<String> onClose(
            String topic,
            String username,
            WebSocketSession session) {

        log("onClose", session, username, topic);
        return broadcaster.broadcast(String.format("[%s] Leaving %s!", username, topic), isValid(topic));
    }

    private void log(String event, WebSocketSession session, String username, String topic) {
        LOG.info("* WebSocket: {} received for session {} from '{}' regarding '{}'",
                event, session.getId(), username, topic);
    }

    private Predicate<WebSocketSession> isValid(String topic) { (7)
        return s -> topic.equals("all") //broadcast to all users
                || "all".equals(s.getUriVariables().get("topic", String.class, null)) //"all" subscribes to every topic
                || topic.equalsIgnoreCase(s.getUriVariables().get("topic", String.class, null)); //intra-topic chat
    }
}
1 The @ServerWebSocket annotation defines the path the WebSocket is mapped under. The URI can be a URI template.
2 Use constructor injection to inject a bean of type ChatServerWebSocket.
3 The @OnOpen annotation declares the method to invoke when the WebSocket is opened.
4 Our chat server has a special topic called "all" that can make announcements and receive messages from all topics
5 The @OnMessage annotation declares the method to invoke when a message is received.
6 The @OnClose annotation declares the method to invoke when the WebSocket is closed.
7 A predicate to keep messages within topics yet also enable the special "all" topic

4.4. Test

To test asynchronous code, use Awaitility:

Awaitility is a DSL that allows you to express expectations of an asynchronous system in a concise and easy to read manner.

Micronaut Launch/CLI feature awaitility adds the following dependency:

build.gradle
testImplementation("org.awaitility:awaitility:4.2.2")

The Micronaut frameworks eases the creation of Websocket servers and clients.

Write a test that uses ClientWebSocket to test the application.

src/test/java/example/micronaut/ChatServerWebSocketTest.java
package example.micronaut;

import io.micronaut.context.BeanContext;
import io.micronaut.context.annotation.Property;
import io.micronaut.context.annotation.Requires;
import io.micronaut.core.annotation.NonNull;
import io.micronaut.core.util.CollectionUtils;
import io.micronaut.http.uri.UriBuilder;
import io.micronaut.runtime.server.EmbeddedServer;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import io.micronaut.websocket.WebSocketClient;
import io.micronaut.websocket.annotation.ClientWebSocket;
import io.micronaut.websocket.annotation.OnMessage;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;
import org.reactivestreams.Publisher;
import reactor.core.publisher.Flux;

import jakarta.validation.constraints.NotBlank;
import java.net.URI;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.Deque;
import java.util.List;
import java.util.concurrent.ConcurrentLinkedDeque;

import static org.awaitility.Awaitility.await;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotEquals;

@Property(name = "spec.name", value = "ChatWebSocketTest") (1)
@MicronautTest (2)
class ChatServerWebSocketTest {

    @Inject
    BeanContext beanContext;

    @Inject
    EmbeddedServer embeddedServer;

    @Requires(property = "spec.name", value = "ChatWebSocketTest") (1)
    @ClientWebSocket (3)
    static abstract class TestWebSocketClient implements AutoCloseable { (4)

        private final Deque<String> messageHistory = new ConcurrentLinkedDeque<>();

        public String getLatestMessage() {
            return messageHistory.peekLast();
        }

        public List<String> getMessagesChronologically() {
            return new ArrayList<>(messageHistory);
        }

        @OnMessage  (5)
        void onMessage(String message) {
            messageHistory.add(message);
        }

        abstract void send(@NonNull @NotBlank String message); (6)
    }

    private TestWebSocketClient createWebSocketClient(int port, String username, String topic) {
        WebSocketClient webSocketClient = beanContext.getBean(WebSocketClient.class);
        URI uri = UriBuilder.of("ws://localhost")
                .port(port)
                .path("ws")
                .path("chat")
                .path("{topic}")
                .path("{username}")
                .expand(CollectionUtils.mapOf("topic", topic, "username", username));
        Publisher<TestWebSocketClient> client = webSocketClient.connect(TestWebSocketClient.class,  uri); (7)
        return Flux.from(client).blockFirst();
    }

    @Test
    void testWebsockerServer() throws Exception {
        TestWebSocketClient adam = createWebSocketClient(embeddedServer.getPort(), "adam", "Cats & Recreation"); (8)
        await().until(() -> (9)
                Collections.singletonList("[adam] Joined Cats & Recreation!")
                        .equals(adam.getMessagesChronologically()));

        TestWebSocketClient anna = createWebSocketClient(embeddedServer.getPort(), "anna", "Cats & Recreation");
        await().until(() -> (9)
                Collections.singletonList("[anna] Joined Cats & Recreation!")
                        .equals(anna.getMessagesChronologically()));
        await().until(() -> (9)
                Arrays.asList("[adam] Joined Cats & Recreation!", "[anna] Joined Cats & Recreation!")
                        .equals(adam.getMessagesChronologically()));

        TestWebSocketClient ben = createWebSocketClient(embeddedServer.getPort(), "ben", "Fortran Tips & Tricks");
        await().until(() -> (9)
                Collections.singletonList("[ben] Joined Fortran Tips & Tricks!")
                        .equals(ben.getMessagesChronologically()));
        TestWebSocketClient zach = createWebSocketClient(embeddedServer.getPort(), "zach", "all");
        await().until(() -> (9)
                Collections.singletonList("[zach] Now making announcements!")
                        .equals(zach.getMessagesChronologically()));
        TestWebSocketClient cienna = createWebSocketClient(embeddedServer.getPort(), "cienna", "Fortran Tips & Tricks");
        await().until(() -> (9)
                Collections.singletonList("[cienna] Joined Fortran Tips & Tricks!")
                        .equals(cienna.getMessagesChronologically()));
        await().until(() -> (9)
                Arrays.asList("[ben] Joined Fortran Tips & Tricks!", "[zach] Now making announcements!", "[cienna] Joined Fortran Tips & Tricks!") (10)
                        .equals(ben.getMessagesChronologically()));

        // should broadcast message to all users inside the topic (11)
        final String adamsGreeting = "Hello, everyone. It's another purrrfect day :-)";
        final String expectedGreeting = "[adam] " + adamsGreeting;
        adam.send(adamsGreeting);

        //subscribed to "Cats & Recreation"
        await().until(() ->  (9)
                expectedGreeting.equals(adam.getLatestMessage()));

        //subscribed to "Cats & Recreation"
        await().until(() ->  (9)
                expectedGreeting.equals(anna.getLatestMessage()));

        //NOT subscribed to "Cats & Recreation"
        assertNotEquals(expectedGreeting, ben.getLatestMessage());

        //subscribed to the special "all" topic
        await().until(() ->  (9)
                expectedGreeting.equals(zach.getLatestMessage()));

        //NOT subscribed to "Cats & Recreation"
        assertNotEquals(expectedGreeting, cienna.getLatestMessage());

        // should broadcast message when user disconnects from the chat (12)

        anna.close();

        String annaLeaving = "[anna] Leaving Cats & Recreation!";
        await().until(() ->  (9)
                annaLeaving.equals(adam.getLatestMessage()));

        //subscribed to "Cats & Recreation"
        assertEquals(annaLeaving, adam.getLatestMessage());

        //Anna already left and therefore won't see the message about her leaving
        assertNotEquals(annaLeaving, anna.getLatestMessage());

        //NOT subscribed to "Cats & Recreation"
        assertNotEquals(annaLeaving, ben.getLatestMessage());

        //subscribed to the special "all" topic
        assertEquals(annaLeaving, zach.getLatestMessage());

        //NOT subscribed to "Cats & Recreation"
        assertNotEquals(annaLeaving, cienna.getLatestMessage());

        adam.close();
        ben.close();
        zach.close();
        cienna.close();
    }
}
1 Combine @Requires and properties (either via the @Property annotation or by passing properties when starting the context) to avoid bean pollution.
2 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. More info.
3 You can create Websocket clients by annotating interfaces or abstract classes with @ClientWebSocket.
4 The client must implement AutoCloseable, and you should ensure that the connection is closed at some point.
5 The @OnMessage annotation declares the method to invoke when a message is received.
6 Any method name that starts with (or equals) "broadcast" or "send" will be used to broadcast messages, as long as the parameter is a String or a bean
7 Once you have defined a client class, you can connect to the client socket and start sending messages.
8 Set up WebSocket clients for multiple users
9 Use Awaitility to test asynchronous code. By default, Awaitility waits for 10 seconds and if the condition is not fulfilled during this time, it throws a ConditionTimeoutException failing the test.
10 Test that the correct messages are automatically sent when users join topics
11 Test that chats are sent within a topic and not outside of it, with the exception of those sent using the special "all" topic
12 Test that the correct messages are automatically sent when users leave topics

5. Testing the Application

To run the tests:

./gradlew test

Then open build/reports/tests/test/index.html in a browser to see the results.

6. Running the Application

To run the application, use the ./gradlew run command, which starts the application on port 8080.

Open a browser and visit a URL such as http://localhost:8080/#/java/Joe. Then in another browser tab, open http://localhost:8080/\#/java/Moka. You can then try sending chats as Joe and Moka.

7. Generate a Micronaut Application Native Executable with GraalVM

We will use GraalVM, the polyglot embeddable virtual machine, to generate a native executable of our Micronaut application.

Compiling native executables ahead of time with GraalVM improves startup time and reduces the memory footprint of JVM-based applications.

Only Java and Kotlin projects support using GraalVM’s native-image tool. Groovy relies heavily on reflection, which is only partially supported by GraalVM.

7.1. GraalVM installation

The easiest way to install GraalVM on Linux or Mac is to use SDKMan.io.

Java 21
sdk install java 21.0.5-graal
Java 21
sdk use java 21.0.5-graal

For installation on Windows, or for manual installation on Linux or Mac, see the GraalVM Getting Started documentation.

The previous command installs Oracle GraalVM, which is free to use in production and free to redistribute, at no cost, under the GraalVM Free Terms and Conditions.

Alternatively, you can use the GraalVM Community Edition:

Java 21
sdk install java 21.0.2-graalce
Java 21
sdk use java 21.0.2-graalce

7.2. Native executable generation

To generate a native executable using Gradle, run:

./gradlew nativeCompile

The native executable is created in build/native/nativeCompile directory and can be run with build/native/nativeCompile/micronautguide.

It is possible to customize the name of the native executable or pass additional parameters to GraalVM:

build.gradle
graalvmNative {
    binaries {
        main {
            imageName.set('mn-graalvm-application') (1)
            buildArgs.add('--verbose') (2)
        }
    }
}
1 The native executable name will now be mn-graalvm-application
2 It is possible to pass extra arguments to build the native executable

open your browser and visit http://localhost:8080/\#/java/Joe

8. Next steps

Read more about:

9. License

All guides are released with an Apache license 2.0 license for the code and a Creative Commons Attribution 4.0 license for the writing and media (images…​).