WebSocket API - JAVA客户端/服务端API

规范包含在JavaEE7中，在包javax.websocket下，包含客户端API和服务端API，服务端API完全依赖于客户端API，只是再其基础上添加了一些功能，所以只需要导入服务端依赖即可。(WebSocket的Java API 只是规范，具体实现需要web容器、JavaEE服务器或者框架提供)

一、客户端API

1）客户端API基于如下抽象类或接口

1. ContainerProvider
   • 提供静态的getWebSocketContainer方法，获取底层WebSocket客户端实现
2. WebSocketContainer
   • 提供对所有WebSocket客户端特性的访问
   • 4个重载的 connectToServer; 都接收一个URL, 用于连接远程终端和初始化握手，返回一个Session，还可以接收如下类型中的一个(必须含有无参构造函数)
     • 标注了@ClientEndpoint的任意类型的POJO
     • 标注了@ClientEndpoint的任意类型的POJO的Class<?>
     • Endpoint类的实例和ClientEndpointConfig实例
     • Class<? extends Endpoint>和ClientEndpointConfig实例
3. RemoteEndpoint
4. Session
   • 关闭会话等重要功能

2）EndPoint与@ClientEndpoint

1. WebSocket的Endpoint抽象类有三个方法，onOpen、onClose、onError,他们将在这些事件触发时发生；这里重点介绍@ClientEndpoint的使用方式
2. @ClientEndpoint 类可以有(可选的)标注了@OnOpen @OnClose @OnError 的方法
3. @ClientEndpoint标注类和继承了Endpoint的类可以指定一个或者多个标注了@OnMessage的方法，用于接收远程终端发送的文本/二进制消息；通过使用注解类和方法，在选择具体的方法参数时具有很大的灵活性。

3）@ClientEndpoint标注类中注解标注方法的签名

1. @OnOpen标注的方法

   • Session 可选
   • EndpointConfig 可选

2. @OnClose标注的方法

   • Session 可选
   • CloseReason 可选

3. @OnError标注的方法

   • Session 可选
   • Throwable 必须

4. @OnMessage

   • Session 可选
   • 必选参数：如下参数组合的某一个
     • 字符串：用于接收完整文本消息。
     • 字符串、布尔值：用于以块的方式接收文本消息，并在最后一块中将布尔值设置为真。
     • Java原生类型或者原生类型的包装类型：用于接收完整的文本消息并转换成该类型。
     • Java.io.Reader对象：以阻塞流的方式接收文本消息。
     • byte[]或者java.nio.ByteBuffer：用于接收完整的二进制消息。
     • byte[]或者ByteBuffer、布尔值：以块的形式接收二进制消息。
     • java.io.InputStream：以阻塞流的方式接收二进制消息。
     • PongMessage对象：自定义心跳响应处理。
     • 任意的Java对象：终端得注册如下对应的某些驱动,它们会将结果转换为对应的声明类型，文本或二进制的消息类型必须与注册的解码器向匹配
       • Decoder.Text
       • Decoder.Binary
       • Decoder.TextStream
       • Decoder.BinaryStream

打开、关闭和错误时间，一个终端只能有一个对应的标注类方法；对于@OnMessage,最多有三个消息处理方法：一个处理文本、一个处理二进制、一个处理pong心跳消息。

二、服务端API

ServerContainer继承了WebSocketContainer, 它添加了通过编程方式注册了ServerEndpointConfig实例的方法和标注了@ServerEndpoint的类。在servlet环境中，调用ServletContext.getAttribute("javax.websocket.server.ServerContainer")可以获得ServerContainer实例，在独立运行的环境中，需要按照特定的WebSocket实现指令获得ServerContainer。

不过，在实际开发中，以上描述都可以不用关心，不需要获得ServerContainer,只需要使用@ServerEndpoint标注服务器终端类即可，WebSocket实现可以扫描类的注解，并自动选择和注册服务器终端。容器将在每次收到WebSocket连接时创建对应终端类的实例，在连接关闭之后销毁该实例。

1）@ServerEndpoint服务端标注类

1. 使用@ServerEndpoint，需要指定其中的value熟悉，表示响应程序对应的URL

@ServerEndpoint("/game/{var}")
public class GameServer { ... }

2. 可以在@OnOpen @OnClose @OnError @OnMessage 标注的方法中使用如 @PathParam("var") 获取路径参数

服务器终端中的事件处理方法将如同客户端终端中的事件处理方法一样工作。服务器和客户端的区别只在握手的时候。在握手完成建立连接后，服务器和客户端都将变成端点，并且是具有相同能力和责任的完全对等的终端。