WebSocket 支持

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

Tomcat 实现了由 Java WebSocket 项目的 Java WebSocket 1.1 API， 由 JSR-356 定义。

有几个示例应用程序演示了如何使用 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 应用程序更改此设置。

Java WebSocket 规范 1.0 不允许在第一个端点启动 WebSocket 握手之后进行编程部署。 默认情况下，Tomcat 仍允许额外的编程部署。此行为由 org.apache.tomcat.websocket.noAddAfterHandshake servlet 上下文初始化参数控制。 可以通过将 o`rg.apache.tomcat.websocket.STRICT_SPEC_COMPLIANCE` 系统属性设置为 true 来更改默认值，但在 servlet 上下文上的任何显式设置将始终优先。

当使用 WebSocket 客户端连接到服务器端点时，建立连接时 IO 操作的超时 由提供的 jakarta.websocket.ClientEndpointConfig 的 userProperties 控制。 该属性为 org.apache.tomcat.websocket.IO_TIMEOUT_MS，是 String 的超时时间（以毫秒为单位）。 默认值为 5000 （5 秒）。

使用 WebSocket 客户端连接到安全服务器端点时， 客户端的 SSL 配置由所提供的 javax.websocket.ClientEndpointConfig 的 userProperties 控制。支持以下用户属性：

默认的信任库密码是 changeit。

如果设置了 org.apache.tomcat.websocket.SSL_CONTEXT 属性， 则 org.apache.tomcat.websocket.SSL_TRUSTSTORE 和 org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD 属性将被忽略。

对于安全服务器端点，默认启用主机名验证。 若要绕过此验证（不推荐），必须通过 org.apache.tomcat.websocket.SSL_CONTEXT 用户属性提供自定义的 SSLContext。 自定义 SSLContext 必须使用继承自 javax.net.ssl.X509ExtendedTrustManager 的自定义 TrustManager 进行配置。所需的验证（或不进行验证）可以通过适当实现各个抽象方法来控制。

当使用 WebSocket 客户端连接到服务器端点时，客户端将遵循的 HTTP 重定向的数量由提供的 javax.websocket.ClientEndpointConfig 的 userProperties 控制。 该属性为 org.apache.tomcat.websocket.MAX_REDIRECTIONS。 默认值为 20。可以通过配置值 0 来禁用重定向支持。

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

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

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

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