WebSocket 操作指南
目录
概述
Tomcat 提供对 RFC 6455 中定义的 WebSocket 的支持。
应用程序开发
Tomcat 实现了由 Jakarta WebSocket 项目定义的 Jakarta WebSocket 2.1 API。
Tomcat WebSocket 特定配置
Tomcat 为 WebSocket 提供了许多 Tomcat 特定的配置选项。预计这些选项将随着时间的推移被吸纳到 WebSocket 规范中。
在阻塞模式下发送 WebSocket 消息时使用的写入超时默认为 20000 毫秒（20 秒）。可以通过在 WebSocket 会话的用户属性集合中设置属性 org.apache.tomcat.websocket.BLOCKING_SEND_TIMEOUT 来更改此值。分配给此属性的值应为 Long 类型，表示要使用的超时（以毫秒为单位）。对于无限超时，请使用 -1。
Tomcat 在向对等方发送关闭消息后，等待对等方发送 WebSocket 会话关闭消息的时间默认为 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。二进制消息的默认缓冲区大小为 8192 字节。可以通过将 servlet 上下文初始化参数 org.apache.tomcat.websocket.binaryBufferSize 设置为所需值（以字节为单位）来为 Web 应用程序更改此值。
如果应用程序未为传入的文本消息定义 MessageHandler.Partial，则任何传入的文本消息都必须进行缓冲，以便可以在一次调用中将整个消息传递给为文本消息注册的 MessageHandler.Whole。文本消息的默认缓冲区大小为 8192 字节。可以通过将 servlet 上下文初始化参数 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