WebSocket API - JAVA客戶(hù)端/服務(wù)端API

規(guī)范包含在JavaEE7中，在包javax.websocket下，包含客戶(hù)端API和服務(wù)端API，服務(wù)端API完全依賴(lài)于客戶(hù)端API，只是再其基礎(chǔ)上添加了一些功能，所以只需要導(dǎo)入服務(wù)端依賴(lài)即可。(WebSocket的Java API 只是規(guī)范，具體實(shí)現(xiàn)需要web容器、JavaEE服務(wù)器或者框架提供)

一、客戶(hù)端API

1）客戶(hù)端API基于如下抽象類(lèi)或接口

1. ContainerProvider
   • 提供靜態(tài)的getWebSocketContainer方法，獲取底層WebSocket客戶(hù)端實(shí)現(xiàn)
2. WebSocketContainer
   • 提供對(duì)所有WebSocket客戶(hù)端特性的訪(fǎng)問(wèn)
   • 4個(gè)重載的 connectToServer; 都接收一個(gè)URL, 用于連接遠(yuǎn)程終端和初始化握手，返回一個(gè)Session，還可以接收如下類(lèi)型中的一個(gè)(必須含有無(wú)參構(gòu)造函數(shù))
     • 標(biāo)注了@ClientEndpoint的任意類(lèi)型的POJO
     • 標(biāo)注了@ClientEndpoint的任意類(lèi)型的POJO的Class<?>
     • Endpoint類(lèi)的實(shí)例和ClientEndpointConfig實(shí)例
     • Class<? extends Endpoint>和ClientEndpointConfig實(shí)例
3. RemoteEndpoint
4. Session
   • 關(guān)閉會(huì)話(huà)等重要功能

2）EndPoint與@ClientEndpoint

1. WebSocket的Endpoint抽象類(lèi)有三個(gè)方法，onOpen、onClose、onError,他們將在這些事件觸發(fā)時(shí)發(fā)生；這里重點(diǎn)介紹@ClientEndpoint的使用方式
2. @ClientEndpoint 類(lèi)可以有(可選的)標(biāo)注了@OnOpen @OnClose @OnError 的方法
3. @ClientEndpoint標(biāo)注類(lèi)和繼承了Endpoint的類(lèi)可以指定一個(gè)或者多個(gè)標(biāo)注了@OnMessage的方法，用于接收遠(yuǎn)程終端發(fā)送的文本/二進(jìn)制消息；通過(guò)使用注解類(lèi)和方法，在選擇具體的方法參數(shù)時(shí)具有很大的靈活性。

3）@ClientEndpoint標(biāo)注類(lèi)中注解標(biāo)注方法的簽名

1. @OnOpen標(biāo)注的方法

   • Session 可選
   • EndpointConfig 可選

2. @OnClose標(biāo)注的方法

   • Session 可選
   • CloseReason 可選

3. @OnError標(biāo)注的方法

   • Session 可選
   • Throwable 必須

4. @OnMessage

   • Session 可選
   • 必選參數(shù)：如下參數(shù)組合的某一個(gè)
     • 字符串：用于接收完整文本消息。
     • 字符串、布爾值：用于以塊的方式接收文本消息，并在最后一塊中將布爾值設(shè)置為真。
     • Java原生類(lèi)型或者原生類(lèi)型的包裝類(lèi)型：用于接收完整的文本消息并轉(zhuǎn)換成該類(lèi)型。
     • Java.io.Reader對(duì)象：以阻塞流的方式接收文本消息。
     • byte[]或者java.nio.ByteBuffer：用于接收完整的二進(jìn)制消息。
     • byte[]或者ByteBuffer、布爾值：以塊的形式接收二進(jìn)制消息。
     • java.io.InputStream：以阻塞流的方式接收二進(jìn)制消息。
     • PongMessage對(duì)象：自定義心跳響應(yīng)處理。
     • 任意的Java對(duì)象：終端得注冊(cè)如下對(duì)應(yīng)的某些驅(qū)動(dòng),它們會(huì)將結(jié)果轉(zhuǎn)換為對(duì)應(yīng)的聲明類(lèi)型，文本或二進(jìn)制的消息類(lèi)型必須與注冊(cè)的解碼器向匹配
       • Decoder.Text
       • Decoder.Binary
       • Decoder.TextStream
       • Decoder.BinaryStream

打開(kāi)、關(guān)閉和錯(cuò)誤時(shí)間，一個(gè)終端只能有一個(gè)對(duì)應(yīng)的標(biāo)注類(lèi)方法；對(duì)于@OnMessage,最多有三個(gè)消息處理方法：一個(gè)處理文本、一個(gè)處理二進(jìn)制、一個(gè)處理pong心跳消息。

二、服務(wù)端API

ServerContainer繼承了WebSocketContainer, 它添加了通過(guò)編程方式注冊(cè)了ServerEndpointConfig實(shí)例的方法和標(biāo)注了@ServerEndpoint的類(lèi)。在servlet環(huán)境中，調(diào)用ServletContext.getAttribute("javax.websocket.server.ServerContainer")可以獲得ServerContainer實(shí)例，在獨(dú)立運(yùn)行的環(huán)境中，需要按照特定的WebSocket實(shí)現(xiàn)指令獲得ServerContainer。

不過(guò)，在實(shí)際開(kāi)發(fā)中，以上描述都可以不用關(guān)心，不需要獲得ServerContainer,只需要使用@ServerEndpoint標(biāo)注服務(wù)器終端類(lèi)即可，WebSocket實(shí)現(xiàn)可以?huà)呙桀?lèi)的注解，并自動(dòng)選擇和注冊(cè)服務(wù)器終端。容器將在每次收到WebSocket連接時(shí)創(chuàng)建對(duì)應(yīng)終端類(lèi)的實(shí)例，在連接關(guān)閉之后銷(xiāo)毀該實(shí)例。

1）@ServerEndpoint服務(wù)端標(biāo)注類(lèi)

1. 使用@ServerEndpoint，需要指定其中的value熟悉，表示響應(yīng)程序?qū)?yīng)的URL

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

2. 可以在@OnOpen @OnClose @OnError @OnMessage 標(biāo)注的方法中使用如 @PathParam("var") 獲取路徑參數(shù)

服務(wù)器終端中的事件處理方法將如同客戶(hù)端終端中的事件處理方法一樣工作。服務(wù)器和客戶(hù)端的區(qū)別只在握手的時(shí)候。在握手完成建立連接后，服務(wù)器和客戶(hù)端都將變成端點(diǎn)，并且是具有相同能力和責(zé)任的完全對(duì)等的終端。