WebSocketハウツー
目次
概要
Tomcatは、RFC 6455で定義されているWebSocketのサポートを提供します。
アプリケーション開発
Tomcatは、Jakarta WebSocketプロジェクトで定義されているJakarta WebSocket 2.1 APIを実装しています。
WebSocket APIの使用方法を示すいくつかのサンプルアプリケーションがあります。クライアント側のHTMLとサーバー側のコードの両方を確認する必要があります。
Tomcat WebSocket固有の設定
Tomcatは、WebSocketに対してTomcat固有の構成オプションを多数提供しています。これらのオプションは、時間の経過とともにWebSocket仕様に組み込まれることが予想されます。
ブロッキングモードでWebSocketメッセージを送信するときに使用される書き込みタイムアウトは、デフォルトで20000ミリ秒（20秒）です。これは、WebSocketセッションに添付されたユーザープロパティコレクションでorg.apache.tomcat.websocket.BLOCKING_SEND_TIMEOUTプロパティを設定することで変更できます。このプロパティに割り当てられる値はLongである必要があり、使用するタイムアウトをミリ秒単位で表します。無限のタイムアウトには、-1を使用します。
Tomcatがピアにクローズメッセージを送信した後、ピアがWebSocketセッションのクローズメッセージを送信するのをTomcatが待機する時間は、デフォルトで30000ミリ秒（30秒）です。これは、WebSocketセッションに添付されたユーザープロパティコレクションでorg.apache.tomcat.websocket.SESSION_CLOSE_TIMEOUTプロパティを設定することで変更できます。このプロパティに割り当てられる値はLongである必要があり、使用するタイムアウトをミリ秒単位で表します。ゼロ以下の値は無視されます。
クローズが異常な場合にセッションクローズメッセージを書き込むときにTomcatが使用する書き込みタイムアウトは、デフォルトで50ミリ秒です。これは、WebSocketセッションに添付されたユーザープロパティコレクションでorg.apache.tomcat.websocket.ABNORMAL_SESSION_CLOSE_SEND_TIMEOUTプロパティを設定することで変更できます。このプロパティに割り当てられる値はLongである必要があり、使用するタイムアウトをミリ秒単位で表します。ゼロ以下の値は無視されます。
Jakarta WebSocket APIの一部であるSession.setMaxIdleTimeout(long)メソッドに加えて、Tomcatはアクティビティがないためにセッションがタイムアウトするタイミングをより詳細に制御できます。WebSocketセッションに添付されたユーザープロパティコレクションでorg.apache.tomcat.websocket.READ_IDLE_TIMEOUT_MSプロパティを設定すると、指定されたミリ秒数WebSocketメッセージが受信されない場合にセッションタイムアウトがトリガーされます。org.apache.tomcat.websocket.WRITE_IDLE_TIMEOUT_MSプロパティを設定すると、指定されたミリ秒数WebSocketメッセージが送信されない場合にセッションタイムアウトがトリガーされます。これらは、Session.setMaxIdleTimeout(long)の有無にかかわらず、個別に使用することも、組み合わせて使用することもできます。関連するプロパティが指定されていない場合、読み取りおよび/または書き込みのアイドルタイムアウトが適用されます。
アプリケーションが受信バイナリメッセージのMessageHandler.Partialを定義していない場合、受信バイナリメッセージはすべてバッファリングして、登録されたバイナリメッセージのMessageHandler.Wholeへの1回の呼び出しでメッセージ全体を配信できるようにする必要があります。バイナリメッセージのデフォルトのバッファサイズは8192バイトです。これは、サーブレットコンテキストの初期化パラメータorg.apache.tomcat.websocket.binaryBufferSizeを目的の値（バイト単位）に設定することで、Webアプリケーションに対して変更できます。
アプリケーションが受信テキストメッセージのMessageHandler.Partialを定義していない場合、受信テキストメッセージはすべてバッファリングして、登録されたテキストメッセージのMessageHandler.Wholeへの1回の呼び出しでメッセージ全体を配信できるようにする必要があります。テキストメッセージのデフォルトのバッファサイズは8192バイトです。これは、サーブレットコンテキストの初期化パラメータorg.apache.tomcat.websocket.textBufferSizeを目的の値（バイト単位）に設定することで、Webアプリケーションに対して変更できます。
WebSocketクライアントを使用してサーバーエンドポイントに接続する場合、接続を確立している間のIO操作のタイムアウトは、提供されたjakarta.websocket.ClientEndpointConfigのuserPropertiesによって制御されます。プロパティはorg.apache.tomcat.websocket.IO_TIMEOUT_MSであり、タイムアウトはミリ秒単位のStringです。デフォルトは5000（5秒）です。
WebSocketクライアントを使用してサーバーエンドポイントに接続する場合、クライアントが追跡するHTTPリダイレクトの数は、提供されたjakarta.websocket.ClientEndpointConfigのuserPropertiesによって制御されます。プロパティは
WebSocketクライアントを使用して、BASICまたはDIGEST認証を必要とするサーバーエンドポイントに接続する場合、次のユーザープロパティを設定する必要があります
org.apache.tomcat.websocket.WS_AUTHENTICATION_USER_NAMEorg.apache.tomcat.websocket.WS_AUTHENTICATION_PASSWORD
オプションで、WebSocketクライアントは、サーバー認証チャレンジに特定のレルムが含まれている場合にのみ、オプションのユーザープロパティでそのレルムを定義することにより、資格情報を送信するように構成できます
org.apache.tomcat.websocket.WS_AUTHENTICATION_REALM
WebSocketクライアントを使用して、BASICまたはDIGEST認証を必要とするフォワードプロキシ（ゲートウェイとも呼ばれます）経由でサーバーエンドポイントに接続する場合、次のユーザープロパティを設定する必要があります
org.apache.tomcat.websocket.WS_PROXY_AUTHENTICATION_USER_NAMEorg.apache.tomcat.websocket.WS_PROXY_AUTHENTICATION_PASSWORD
オプションで、WebSocketクライアントは、サーバー認証チャレンジに特定のレルムが含まれている場合にのみ、オプションのユーザープロパティでそのレルムを定義することにより、資格情報を送信するように構成できます
org.apache.tomcat.websocket.WS_PROXY_AUTHENTICATION_REALM