第三章、WebSocket配置

WebSocket应用程序配置有许多关键参数：在容器的URI空间中标识WebSocket端点的路径映射，端点支持的子协议，应用程序的扩展需求，此外，在打开握手期间，应用程序可以选择执行其他配置任务，例如检查发出请求的客户端的主机名或处理cookie，本节详细介绍了容器上支持这些配置任务的要求。

客户端和服务端点配置都包括应用程序提供的编码器和解码器的列表，在WebSocket消息和应用程序定义的消息对象之间转换的实现和使用这些类。[WSC-3-1]

遵循服务器特定配置和客户特定配置选项的定义。

3.1、服务端配置

• 为了将编程的端点部署到可用于客户端连接的URI空间中，容器需要一个ServerEndpointConfig实例。该对象保存配置数据和实现配置端点所需的默认实现提供的算法。通过提供带有ServerEndpointConfig的定义ServerEndpoingConfig.Configurator实现，WebSocketAPI允许开放人员覆盖其中的某些配置操作。[WSC-3.1-1]
• 这些操作在下面列出

3.1.1、URI 映射

• 本节介绍服务器端点的URI映射策略。websocket实现必须将传入的URI与所有端点路径的集合进行比较，并确定最佳匹配。如果在端点路径是相对URI的情况下是完全匹配。或者传入URI端点路径是端点路径的有效扩展，则打开握手请求中的传入URI与指定路径匹配 [WSC-3.1.1-1]
• 包含具有相同相对URI的多个端点路径的应用程序不是有效的应用程序，包含多个等效URI模板的端点路径的应用程序不是有效的应用程序。
• 但是从理论上将，打开握手请求中的传入URI可以匹配多个端点路径，举个例子，考虑如下场景：
  • 请求URI: “a/b"
  • 端点 A 映射到 “/a/b”
  • 端点 B映射到 “/a/{自定义名}”
• WebSocket实现将尝试以等同于以下方式的方式将输入的URI与应用程序中的端点路径（URI或1级URI模板）进行匹配：[WSC-3.1.1-3]
• 由于端点路径是相对URI或URI模板级别1，因此如果路径的片段不相同，则使用"/" 作为分割符，则路径不匹配，因此容器将从左到右遍历端点路径中与输入URI相同数量的段，并将每个段与输入URI的对应端进行比较，在检查下一个段之前，实现将在每个段保流哪些完全匹配的端点路径，或如果不存在，则保存可变段的端点路径，如果在此过程结束时存在端点路径，则存在匹配项。
• 由于要求不允许使用多个端点路径和等效的URI模板，并且每个段都要求完全匹配，因此最多只能有一个路径，这是最佳匹配。
• 例子
  • 假设有端点有路径为 /a/b, 只一个请求URI去匹配/a/b
  • 假设有端点映射到 /a/{变量}，请求URI如下都可以匹配到： /a/b(变量=b) , /a/apple（变量=apple)
    • 如下URI不能匹配： /a, /a/b/c (因为空字符串和带有保留字符"/"的字符串不是有效的URI模板级别1扩展)
  • 假设有三个端点和URI路径
    • 端点 A： /a/{变量}/c
    • 端点 B：/a/b/c
    • 端点 C：/a/{变量1}/{变量2}
      • 现在进入一个URI:/a/b/c, 它会匹配到端点B， 而不是 A或C，因为B是精确匹配
      • 现在进入一个URI：/a/d/c, 它会匹配到端点A，相对于C，A是更加精确一些（匹配到/c)
      • 现在进入一个URI： /a/x/y 它会匹配到端点C， 同时变量1=x，变量2=y
  • 假设现在有两个端点和URI路径
    • 端点 A： /{变量1}/d
    • 端点 B： /b/{变量2}
      • 现在进来一个URI: /b/d， 它会匹配到B ，变量2=的，而不会匹配到A 变量1=b，因为这个匹配处理过程是从左到右进行匹配的，所以端点B更加精确。
• 除非存在匹配项，否则实现不得建立连接。[WSC-3.1.1-4]

3.1.2、子协议协商

• 必须在创建时以默认顺序为默认服务器配置提供受支持协议的列表。在子协议协商期间，此配置将检查客户端提供的子协议列表，并从客户端提供的列表中选择它支持的列表中的第一个子协议，如果不匹配，则不选择。[WSC-3.1.2-1]

3.1.3、扩展修改

• 在打开握手中， 客户端提供了要使用的扩展列表。默认服务器配置从这些扩展中选择它支持的扩展，并且按照客户端要求的顺序放置它们.[WSC-3.1.3-1]

3.1.4、来源检查

• 默认服务器配置检查Origin请求头提供的主机名，如果无法验证主机名，则握手失败[WSC-3.1.4-1]

3.1.5、握手修改

• 默认服务器配置除了上述内容外，不对打开握手过程进行任何修改:[WSC-3.1.5-1]
• 开发人员可能希望自定义上面列出的配置和握手协议策略，为此，他们可以提供自己的ServerEndpointConfig.Configurator实现
• 例如，开发人员可能希望在握手过程中进行更多干预，他们可能希望使用Http cookie来跟踪客户端，或在握手响应中插入应用程序特定的响应头，为此，他们可以在ServerEndpointConfig.Configurator上实现ModifyHandshake() 方法，其中他们可以完全访问握手的HandshakeRequest和HandshakeResponse.

3.1.6、自定义状态或处理跨服务端点实例

• 开发人员还可以实现ServerEndpointConfig.Configurator,以保留自定义应用程序状态或其他类型的特定于应用程序的处理方法，这些方法可以通过EndpointConfig对象从同一逻辑端点的所有Endpoint实例访问。

3.1.7、自定义 端点创建

• 开发者可以通过提供覆盖getEndpointInstance()调用的ServerEndpointConfig.Configurator对象来控制中节点实例的创建。实现每次必须调用此方法新的康双人连接到逻辑端点。[WSC-3.1.7-1]该方法的平台默认实现是每次调用时都返回端点类的新实例。[WSC-3.1.7-2]
• 通过这种方式，开发人员可以以这样的方式部署端点：对于与逻辑端点的所有客户端连接，仅实例化端点类的一个实例。在这种情况下，请开发人员注意，例如，如果两个不同的客户端同时发送消息，则此类端点类的单例实例必须在编程时考虑并发调用线程。

3.2、客户端配置

• 为了将websocket客户端端点连接到其相应的websocket服务器端点，该实现需要配置信息，除了编码器和解码器的列表之外，Java websocket API 还需要以下属性：

3.2.1、子协议

• 默认的客户端配置使用开发人员提供的子协议列表，以优先顺序发送要在其指定的握手过程使用的子协议名称。[WSC-3.2.1-1]

3.2.2、扩展

• 默认的客户端配置必须使用开发人员提供的扩展列表，以便按照优先顺序发送要在其制定的握手过程中使用的扩展（包含参数）。[WSC-3.2.2-1]

3.2.3、客户端配置修改

• 一些客户端可以希望适用客户端和服务器之间进行开放式握手交互的方式，开发人员可以提供自己的ClientEndpointConfig.Configuartor实现，这些实现将覆盖基础实现的默认行为，以便对其进行自定义以适应特定的应用程序的需求。