Version:

Getting started with WebSockets Next

このガイドでは、Quarkus アプリケーションで Web ソケットを利用してインタラクティブな Web アプリケーションを作成する方法について説明します。このガイドでは、Web ソケットを使用して、接続している他のユーザーとメッセージを送受信する非常にシンプルなチャットアプリケーションを開発します。

前提条件

このガイドを完成させるには、以下が必要です:

約15分
IDE
JDK 17+がインストールされ、 JAVA_HOME が適切に設定されていること
Apache Maven 3.9.16
使用したい場合は、 Quarkus CLI
ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM（あるいはネイティブなコンテナビルドを使用する場合はDocker）をインストールし、適切に設定していること

Quarkus WebSockets と Quarkus WebSockets Next

このガイドでは、quarkus-websockets-next エクステンションを使用します。このエクステンションは、WebSocket API の新しい実装であり、元の quarkus-websockets エクステンションよりも効率的で使いやすいものとなっています。元の quarkus-websockets エクステンションは今後も利用可能で、引き続きサポートされます。

quarkus-websockets とは異なり、quarkus-web-socket-next は、https://jakarta.ee/specifications/websocket/[Jakarta WebSocket] を実装しません。代わりに、より使いやすく簡素化された最新の API を提供します。また、Quarkus のリアクティブプログラミングモデルおよび Quarkus のネットワーク層と効率的に連携するように設計されています。

What you’ll learn

quarkus-websockets-next エクステンションの使い方
Web ソケットエンドポイントを宣言する方法
Web ソケットを使用してメッセージを送受信する方法
接続しているすべてのユーザーにメッセージをブロードキャストする方法
新しい接続と切断の通知を受け取る方法
Web ソケット URL で パスパラメーター を使用する方法

アーキテクチャ

このガイドでは、WebSocketを使用して、接続されている他のユーザーとメッセージを送受信するための簡単なチャットアプリケーションを作成します。

Architecture

ソリューション

次の章で紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、すぐに完成した例に飛んでも構いません。

git clone https://github.com/quarkusio/quarkus-quickstarts.git で Git リポジトリーをクローンします。または、https://github.com/quarkusio/quarkus-quickstarts/archive/main.zip[アーカイブ] をダウンロードします。

ソリューションは websockets-next-quickstart ディレクトリにあります。

Mavenプロジェクトの作成

まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します。

コマンドラインインタフェース

quarkus create app org.acme:websockets-next-quickstart \
    --extension='websockets-next' \
    --no-code
cd websockets-next-quickstart

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストールと使用方法の詳細については、 Quarkus CLI ガイドを参照してください。

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:3.39.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=websockets-next-quickstart \
    -Dextensions='websockets-next' \
    -DnoCode
cd websockets-next-quickstart

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

Windowsユーザーの場合:

cmdを使用する場合、（バックスラッシュ \ を使用せず、すべてを同じ行に書かないでください）。
Powershellを使用する場合は、 -D パラメータを二重引用符で囲んでください。例: "-DprojectArtifactId=websockets-next-quickstart"

このコマンドは、プロジェクト (クラスなし) を生成し、websockets-next エクステンションをインポートします。

すでに Quarkus プロジェクトが設定されている場合は、プロジェクトのベースディレクトリーで以下のコマンドを実行することで、プロジェクトに websockets-next エクステンションを追加できます。

CLI

quarkus extension add websockets-next

Maven

./mvnw quarkus:add-extension -Dextensions='websockets-next'

Gradle

./gradlew addExtension --extensions='websockets-next'

これにより、ビルドファイルに以下が追加されます:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-websockets-next</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-websockets-next")

WebSocket エンドポイントの宣言

アプリケーションには、Web ソケットを処理する単一のクラスが含まれています。 src/main/java ディレクトリーに org.acme.websockets.ChatWebSocket クラスを作成します。作成したファイルに次の内容をコピーします。

package org.acme.websockets;

import io.quarkus.websockets.next.OnClose;
import io.quarkus.websockets.next.OnOpen;
import io.quarkus.websockets.next.OnTextMessage;
import io.quarkus.websockets.next.WebSocket;
import io.quarkus.websockets.next.WebSocketConnection;
import jakarta.inject.Inject;

@WebSocket(path = "/chat/{username}")  (1)
public class ChatWebSocket {

    // Declare the type of messages that can be sent and received
    public enum MessageType {USER_JOINED, USER_LEFT, CHAT_MESSAGE}
    public record ChatMessage(MessageType type, String from, String message) {
    }

    @Inject
    WebSocketConnection connection;  (2)

    @OnOpen(broadcast = true)       (3)
    public ChatMessage onOpen() {
        return new ChatMessage(MessageType.USER_JOINED, connection.pathParam("username"), null);
    }

    @OnClose                    (4)
    public void onClose() {
        ChatMessage departure = new ChatMessage(MessageType.USER_LEFT, connection.pathParam("username"), null);
        connection.broadcast().sendTextAndAwait(departure);
    }

    @OnTextMessage(broadcast = true)  (5)
    public ChatMessage onMessage(ChatMessage message) {
        return message;
    }

}

1	Declares the web socket endpoint and configures the path. Note that the path can contain a path parameter: `username`.
2	A session scoped bean that represents the connection to the client. It allows sending messages programmatically and retrieving the path parameters.
3	このメソッドは、新しいクライアントが接続したときに呼び出されます。`broadcast = true` 属性は、返されたメッセージが接続されているすべてのクライアントに送信される必要があることを示します。
4	このメソッドは、クライアントが切断されたときに呼び出されます。このメソッドは、`WebSocketConnection` を使用して、接続されている残りのすべてのクライアントにメッセージをブロードキャストします。
5	This method is called when a client sends a message. The `broadcast = true` attribute indicates that the returned message should be sent to all connected clients. Here, we just return the received (text) message.

ご覧のとおり、Quarkus はアノテーションを使用して Web ソケットのライフサイクルとメッセージ処理に対応しています。また、JSON を使用してメッセージを自動的にシリアライズおよびデシリアライズします。

洗練されたWebフロントエンド

すべてのチャットアプリケーションには 洗練された UIが必要です。これは、それほど洗練されていないかもしれませんが、十分に機能します。 Quarkusは、META-INF/resources ディレクトリーに含まれる静的リソースを自動的に提供します。 src/main/resources/META-INF/resources ディレクトリーを作成し、この index.html ファイルをそこへコピーします。

アプリケーションの実行

では、実際にアプリケーションを見てみましょう。以下のように実行してみてください:

CLI

quarkus dev

Maven

./mvnw quarkus:dev

Gradle

./gradlew --console=plain quarkusDev

そして、ブラウザウィンドウを2つ開いて、 http://localhost:8080/ に移動します:

上部のテキストエリアに名前を入力します(2種類の名前を使用します)。
connectをクリック
メッセージの送受信

Application

いつものように、アプリケーションは以下の方法でパッケージ化されます。

CLI

quarkus build

Maven

./mvnw install

Gradle

./gradlew build

そして、 java -jar target/quarkus-app/quarkus-run.jar を使って実行します。

ネイティブ実行可能ファイルを次のようにビルドすることもできます。

CLI

quarkus build --native

Maven

./mvnw install -Dnative

Gradle

./gradlew build -Dquarkus.native.enabled=true

まとめ

この短いスタートガイドでは、quarkus-websockets-next エクステンションを使用して、簡単なチャットアプリケーションを作成する方法について説明しました。このエクステンションの詳細は、専用のリファレンスガイドを参照してください。