WebSocket 支持

Tomcat 提供对 RFC 6455 定义的 WebSocket 的支持。

Tomcat 实现了由 Jakarta WebSocket 项目定义的 Jakarta WebSocket 2.1 API。

有几个示例应用程序演示了如何使用 WebSocket API。 需要查看客户端 HTML 和服务器端代码。

Tomcat 为 WebSocket 提供了许多特定于 Tomcat 的配置选项。 预计随着时间的推移，这些将被吸收到 WebSocket 规范中。

在阻塞模式下发送 WebSocket 消息时使用的写入超时默认为 20000 毫秒（20 秒）。 这可以通过在附加到 WebSocket 会话的用户属性集合中设置 org.apache.tomcat.websocket.BLOCKING_SEND_TIMEOUT 属性来更改。 分配给此属性的值应为 Long，表示要使用的超时（以毫秒为单位）。对于无限超时，请使用 -1。

在 Tomcat 向对等体发送关闭消息后，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，表示要使用的超时（以毫秒为单位）。小于或等于零的值将被忽略。

除了 Session.setMaxIdleTimeout(long) 方法（作为 Jakarta WebSocket API 的一部分）之外， Tomcat 还提供了对由于缺少活动而导致的会话超时的更大控制。 如果在指定的毫秒数内未收到 WebSocket 消息，则在附加到 WebSocket 会话的用户属性集合中 设置属性 org.apache.tomcat.websocket.READ_IDLE_TIMEOUT_MS 将触发会话超时。 如果指定毫秒数内未发送 WebSocket 消息，则将属性设置为 org.apache.tomcat.websocket.WRITE_IDLE_TIMEOUT_MS 将触发会话超时。 这些可以单独使用，也可以一起使用，有或没有 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 控制。 该属性为 org.apache.tomcat.websocket.MAX_REDIRECTIONS。 默认值为 20。可以通过配置值 0 来禁用重定向支持。

使用 WebSocket 客户端连接到需要 BASIC 或 DIGEST 身份验证的服务器终端节点时，必须设置以下用户属性：

（可选）如果服务器身份验证质询包含特定领域，则可以将 WebSocket 客户端配置为 仅在服务器身份验证质询包含特定领域时发送凭证，方法是在可选的 user 属性中定义该领域：

当使用 WebSocket 客户端通过需要 BASIC 或 DIGEST 身份验证的 转发代理（也称为网关）连接到服务器端点时，必须设置以下用户属性：

（可选）如果服务器身份验证质询包含特定领域，则可以将 WebSocket 客户端配置为 仅在服务器身份验证质询包含特定领域时发送凭证，方法是在可选的 user 属性中定义该领域：