第四章、WebSocket注解

本部分包含Java WebSocket API 中注解语义的完整规范

4.1、@ServerEndpoint

• 该类级别的注解，它装饰的java类必须由实现部署为WebSocket服务端点，并在websocket实现的URI空间中可用。[WSC-4.1.1-1]该类必须是public,具体的，并且有public的无参数构造方法，该类可能是也可能不是final修饰的，并且可能有也可能没有final修饰的方法。

4.1.1、value（value 属性）

• value属性必须是java字符串，该字符串是部分URI或URI模板（级别1），并且以"/"开头，有关URI模板的定义，请参见附录[6]，该实现使用value属性将端点部署到webSocket实现的URI空间，在确定与传入的打开握手请求的请求URI的匹配时，实现必须将值视为相对于websocket实现的URI的值。[WSC-4.1.1-2]注解端点匹配的语义与上一章中定义的语义相同。value属性是强制性的，实现必须在部署时拒绝缺少或格式不正确的路径[WSC-4.1.1-3]

• 举个例子

  • @ServerEndpoint("/bookings/{guest-id}")
    public class BookingServer{
      @OnMessage
      public void processBookingRequest(@PathParam("guest-id") String guestID, String message, Session session){
        // 处理客户的预定操作
        
      }
    }
    

  • 在上述例子中，下面任意的URIs都是可以连接到该端点

    • /bookings/JohnSmith
    • /bookings/SallyBrown
    • /bookings/MadisonWatons

• 但是，如果端点注解为@ServerEndpoint("/bookings/SallyBrown"),则只有对/bookings/SallyBrown的客户端请求才能连接到此Websocket端点。

• 如果在value属性中使用URI模板，则开发人员可以使用@PathParam注解取到URI路径上的值，如下所述

• 包含多个带注解的端点的应用程序可能会无意中使用相同的相对URI。WebSocket实现必须在部署时拒绝此类应用程序，并提供一条提示性错误信息，即存在无法解析的重复路径。[WSC-4.1.1-4]

• 应用程序可能包含映射到路径的端点，该路径是URI模板的扩展形式，该路径由同一应用程序中的另一个端点使用。在这种情况下，该应用程序是有效的。请求参考上一章中有关如何解决这种情况下最佳匹配的定义。

• 未来版本可能允许更高级别的URI模板。

4.1.2、encoders(编码器属性）

• encoders属性包含一个java类的列表（可能为空），这些这些java类将充当此端点的编码器组件，这些必须实现某种形式的Encoder接口。并且具有public的无参的构造方法，并且在此websocket端点所属的应用程序的类路径中可见。该实现必须为每个端点的每个连接的每个编码器创建一个新的实例。以确保编码器中不会同时存在两个线程。当尝试使用RemoteEndpoint API [WSC-4.1.2-1]发送应用程序对象时，实现必须尝试将匹配参数化类型的应用程序对象编码为编码器。

4.1.3、decoders(解码器属性)

• decoders属性包含一个Java类列表（可能为空），这些Java类将充当此端点的解码器组件。这些类必须实现某种形式的Decoder接口，并且具有public的无参数构造方法，并且在此websocket端点所属的应用程序的类路径中可见，该实现必须为每个端点的每个连接创建每个编码器的新实例。该实现必须尝试使用适合Websocket消息类型的列表中的解码器对websocket消息进行解码，并将已解码对象形式的消息传递给Websocket端点[WSC-4.1.3-1]。在具有解码器的实现上，实现必须在解码器上使用willDecode()方法来确定解码器是否与传入消息匹配[WSC-4.1.3-2]

4.1.4、subprotocols（子协议属性）

• subprotocols 参数包含此端点支持的子协议的字符串名称的列表（可能为空）。实现必须在开始握手中使用此列表，以协商所需的子协议以用于其建立的连接[WSC-4.1.4-1]

4.1.5、configurator( 配置器属性)

• 可选的configurator属性允许开发人员指示他希望websocket实现使用开发人员提供的ServerEndpointConfig.Configurator实现，如果提供了一个，则websocket实现必须在配置端点时使用它。[WSC-4.1.5-1]除了自定义打开握手，开发人员还可以使用此技术在端点的所有实例之间共享状态。

4.2、@ClientEndpoint

4.2.1、encoders( 编码器属性)

• encoders参数包含一个java类列表（可能为空），这些java类将充当此端点的编码器组件。这些类必须实现某种形式的Encoders接口，并具有public的无参构造方法，并且在此websocket端点所在的应用程序的类路径中可见。该实现必须为每个端点的每个连接的每个编码器创建一个新的实例，以确保编码器中不会同时存在两个线程，当尝试使用RemoteEndpoint API [WSC-4.2.1-1]发送应用程序对象时，实现必须尝试将匹配参数化类型的应用程序对象编码为编码器

4.2.2、decoders(解码器属性)

• decoders参数包含一个java类列表（可能为空），这些java类将充当此端点的解码器组件。这些类必须实现某种形式的Decoder接口，并且具有public的无参的构造方法，并且在此websocket端点所属的应用程序的类路径中可见。该实现必须为每个端点的每个连接创建每个编码器的新的实例，该实现必须尝试使用列表中的第一个适当的解码器来解码Websocket的消息。并将消息以已解码对象的形式传递给Websocket端点[WSC-4.2.2-1]。如果Decoder实现具体有该方法，则该实现必须在解码器上使用willDecode()方法来确定Decoder是否将匹配传入消息[WSC-4.2.2-2]

4.2.3、configurator(配置器属性)

• 可选的configurator属性允许开放人员指示他希望WebSocket实现使用开放人员提供的ClientEndpointConfig.Configurator实现。如果提供了一个，则websocket实现必须在配置端点时使用它。[4.2.3-1]开放人员除了自定义打开握手之外，还可以使用此技术在端点的所有实例之间共享状态。

4.2.4、subprotocols(子协议属性)

• subprotocols 参加包含此端点将会支持的子协议字符串名称的列表（可能为空），实现必须在开始握手中使用此列表，以协商所需的子协议以用于其建立的连接[WSC-4.2.4-1]

4.3、@PathParam

• 此注解用于在带有注解@OnMessage, @OnError, @OnOpen,@OnClose修饰的带注解的端点的类上对方法的一个或多个参数进行注解。这些参数允许类型为Sring，任何Java基本类型或其包装类，除此之外其他类型注解时候必须在部署时报错。[WSC-4.3-1] 必须存在此注解的value属性，否则实现必须抛出错误，[WSC-4.3-2]如果此注解的value属性与在@ServerEndpoint注解中使用的URI模板元素的变量名称相匹配，则该注解的端点将被标注，那么实现必须将其注解的参数值关联起来带有调用方法时调用websocket框架所连接的请求URI的路径片段的值。[WSC-4.3-3]否则，由该注解的String参数的值必须在实现中设置为null。必须遵循以下规则：

  • 如果参数是String， 则容器必须使用路径段的值[WSC-4.3-4]

  • 如果参数是Java基本类型或其包装类型， 则容器必须使用路径端字符串来构造类型，其结果与使用公共的一个实参String构造函数获取包装类型的结果相同，并简化为基本类型（如果需要）。[WSC-4.3-5]

  • 如果容器无法将路径段正确解码为带注解的path参数，则容器必须向包含的路径段的websocket的错误处理方法引发DecodeException.[WSC-4.3-6]

  • 例子1

    • @ServerEndpoint("/bookings/{guest-id}")
      public class BookingServer{
        
        @OnMessage
        public void processBookingRequest(@PathParam("guest-id") String guestID,String message, Session session){
          // 处理客户的预定操作
         
        }
      }
      

    • 在上述例子中，如果客户连接这个端点使用URI /bookings/JohnSmith, 那么这个guestID参数的值为"JohnSmith"

  • 例子2 (整数)

    • @ServerEndpoint("/rewards/{vip-level}")
      public class RewardServer{
        
        @OnMessage
        public void processReward(@PathParam("vip-level") Integer vipLevel, String message, Session session){
          //处理奖牌逻辑
        }
      }
      

4.4、@OnOpen

• 该注解可用于以@ServerEndpoint或@ClientEndpoint注解的Java类的某些方法，注解定义了只要有新客户端连接到此端点，就调用装饰方法，建立连接后，容器会通知该方法[WSC-4.4-1].装饰的方法只能有一个可选的Session参数，一个可选的Endpoint-Config参数和零个或多个@PathParam注解作为参数的注解的String参数，如果存在Session参数，则实现必须传入与新连接[WSC-4.4-2]相对应的新创建的Session，任何在不遵守这些规则的方法上使用此注解或多个方法上使用此注解的Java类都可能无法通过实现进行部署，并行错误会报告给部署者[WSC-4.4-3]

4.5、@OnClose

• 该注解可用于以@ServerEndpoint或@ClientEndpoint注解的Java类某些方法，注解定义了无论何时远程对等方从此端点断开连接，无论该过程是由远程对等方，通过本地容器还是通过对session.close()的调来发起，都将调用修饰的方法，在断开连接之前，容器会通知该方法[WSC-4.5-1]。装饰的方法只能具有可选的Session的参数，可选的CloseReason参加和零个或n个以上@PathParam注解为参数的字符串参数，如果存在Session参数，则实现必须传入与连接[WSC-4.5-2]相应的即将结束的Session，如果方法本身抛出错误，则实现必须将此错误与会话[WSC-4.5-3]一起传递给端点的onError()方法。
• 在不遵守这些规则的方法上使用此注解的任何Java类，或在一个以上方法上使用此注解的任何java类都可能不会实现部署，并且错误会报告给部署者。[WSC-4.5-4]

4.6、@OnError

• 该注解可用于以@ServerEndpoint或@ClientEndpoint注解的Java类的某些方法，注解定义了只要与此端点的任何连接上产生错误，就调用@OnError装饰的方法。装饰的方法只能具有可选的Session参数，必须的Throwable参数以及从0 到n的String参数，并且使用@PathParam注解作为参数，如果存在Session参数，则实现必须将发生错误的Session传递给连接[WSC-4.6-1],容器必须将错误作为Throwable参数传递给此方法[WSC-4.6-2]。
• 在不遵守这些规则的方法上使用此注解的任何Java类，或在一个以上方法上使用此注解的任何java类都可能不会实现部署，并且错误会报告给部署者。[WSC-4.6-3]

4.7、@OnMessage

• 该注解可用于以@ServerEndpoint或@ClientEndpoint注解的Java类的某些方法，注解定义了每当收到消息时就调用这个标有@OnMessage注解的方法，它装饰的方法可能具有多种形式，用于处理文本，二进制或Pong消息以及立即发送回消息，这些形式在@OnMessage的api文档中进行详细定义。
• 用@OnMessage注解的任何不符合其中定义的形式的方法均无效，如果尝试部署这样的带有注解的端点，则websocket实现不能部署这样的端点，并且必须在部署时抛出异常。[WSC-4.7-1]
• 如果该方法使用与Java基本类型作为方法参数来处理整个文本消息，则实现必须使用单个String参数构造函数来尝试构造该对象，如果该方法使用的Java基本数据类型作为方法参数来处理整个文本消息，则实现必须尝试如上所述构造器类等效项，然后将其转换为其基本数据类型值。[WSC-4.7-2]
• 如果该方法使用Java基本数据类型作为返回值，则实现必须使用java基本数据类型的标准Java字符串表示形式构造要发送的文本消息。如果该方法使用与Java基本数据类型等效的类作为返回值，则实现必须如上所述从Java基本数据类型等效项构造文本消息。[WSC-4.7-3]
• 对于每个websocket消息格式，每个websocket端点只能具有一个消息处理方法：文本，二进制和pong。如果端点不满足这些要求，这个就在部署的时候抛出异常[WSC-4.7-4]

4.7.1、maxMessageSize(最大消息的大小)

• maxMessageSize属性允许开放人员以字节为单位指定其注解的方法将能够处理的最大消息大小，或者-1表示没有最大消息大小，默认值为-1.
• 如果传入消息超过最大消息的大小，则实现必须使用关闭代码1009（消息太大）正式关闭连接[WSC-4.7.1-1]

4.8、Websocket和继承

• 该规范定义的websocket注解行为不会沿用java 类继承层次结构传递，它们仅仅适用于标记了它们的Java类。例如，从带有类级别WebSocket注解的Java类继承的Java本身不会成为注解的端点，除非它本身已由类级别WebSocket注解进行标注，类似地，带注解的端点的子类可能不使用方法机械臂的websocket注解，除非他们本身使用类级别的websocket注解。覆盖使用websocket方法注解的方法的紫烈不会获得websocket回调，除非这些子类方法本身使用方法级别的websocket注解进行标记。
• 不应该部署以此类方式将Java继承与Websocket注解错误地混合在一起的Java类[WSC-4.8.1]
• 使用存档（jar包）扫描技术在启动是部署端点的实现，除了其他错误定义（例如在构建要部署带注解的端点的列表是非公开的带注解的类）之外，还必须过滤掉带注解的端点的子类[WSC-4.8.2]

4.9、附录

1. [1] I. Fette and A. Melnikov. RFC 6455: The WebSocket Protocol. RFC, IETF, December 2011. See http://www.ietf.org/rfc/rfc6455.txt.
2. [2] Ian Hickson. The WebSocket API. Note, W3C, December 2012. See http://dev.w3.org/html5/websockets/.
3. [3] S. Bradner. RFC 2119: Keywords for use in RFCs to Indicate Requirement Levels. RFC, IETF, March 1997. See http://www.ietf.org/rfc/rfc2119.txt.
4. [4] Danny Coward. Java API for WebSocket. JSR, JCP, 2013. See http://jcp.org/en/jsr/detail?id=356.
5. [5] Expert group mailing list archive. Web site. See http://java.net/projects/websocket-spec/lists/jsr356-experts/archive.
6. [6] J. Gregorio, R. Fielding, M. Hadley, M. Nottingham, and D. Orchard. RFC 6570: URI Template. RFC, IETF, March 2012. See http://www.ietf.org/rfc/rfc6570.txt.
7. [7] Pete Muir. Contexts and Dependency Injection for Java EE. JSR, JCP, 2013. See http://jcp.org/en/jsr/detail?id=347.
8. [8] Linda DeMichiel and Bill Shannon. Java Platform, Enterprise Edition 7 (Java EE 7) Specification. JSR, JCP, 2013. See http://jcp.org/en/jsr/detail?id=342.