JSR 356- WebSocket Java API

Sat, 23 Jul 2016 17:35:00 GMT

原文�Q?a style="cursor: pointer;">http://www.oracle.com/technetwork/articles/java/jsr356-1937161.html

学习如何在你的应用程序中集成WebSockets.

Published April 2013

对于许多��Z��客户端－服务器程序来��_��老的HTTP ��h��-响应模型已经有它的局限�? 信息必须通过多次��h��才能��其从服务端传送到客户�?

�q�去许多的黑客��用某些技术来�l�过�q�个问题�Q�例如：长轮�?long polling)�?span style="color: #333333;">��Z�� HTTP 长连接的服务器推技�?Comet).

然而，��Z��标准的、双向的、客��L��和服务器之间全双工的信道需求再不断增加�?/div>

�?011�q? IETF发布了标准WebSocket协议�Q�RFC 6455. 从那时�v�Q�大多数Web��览器都实现了支持WebSocket协议的客��L��APIs.同时�Q�许多Java 包也开始实��C��WebSocket协议.

WebSocket协议利用HTTP升��技术来��HTTP�q�接升��到WebSocket. 一旦升�U�后�Q�连接就有了在两个方向上�怺�独立(全双�?发送消�?数据�?的能�?

不需要headers 或cookies,�q�大大降低了所需的带�?/span>. 通常�Q�WebSockets来周期性地发送小消息 (例如�Q�几个字�?.

额外�?span style="font-family: 'Microsoft Yahei';">headers常常会��开销大于有效负蝲�Q?span style="font-family: 'Microsoft Yahei';">payload�Q��?/div>

JSR 356

JSR 356, WebSocket的Java API, 明确规定了API�Q�当Java开发者需要在应用�E�序中集成WebSocket�Ӟ��可以��用此API—服务端和客户端均�? 每个声明兼容JSR 356的WebSocket协议�Q�都必须实现�q�个API.

因此�Q�开发�h员可以自��q��写独立于底层WebSocket实现的WebSocket应用�?/span>�q�是一个巨大的好处�Q�因为它可以防止供应商锁定，�q�允许更多的选择、自��q��库、应用程序服务器�?/span>

JSR 356是即��到来的java EE 7标准的一部分�Q�因此，所有与Java EE 7兼容的应用服务器都有JSR 365标准WebSocket的实�?一旦徏立，WebSocket客户端和服务器节点已�l�是对称的了。客��L��API与服务器端API的区别是很小的，JSR 356定义的Java client API只是Java EE7完整API的子�?

客户�D�－服务器端�E�序使用WebSockets�Q�通常会包含一个服务器�l��g和多个客��L��l��g, 如图�Q�所�C?

�?

在这个例子中�Q�server application 是通过Java�~�写�?WebSocket 协议�l�节是由包含在Java EE 7容器中JSR 356 实现来处理的.

JavaFX 客户端可依赖��M��与JSR 356兼容的客��L��实现来处理WebSocket协议问题.

其它客户�?�?iOS 客户端和HTML5客户�?可��用其�?(非Java)与RFC6455兼容的实现来与server application通信.

�~�程模型

JSR 356定义的专家小�l?希望支持Java EE开发�h员常用的模式和技术�?/span>因此,JSR 356使用了注释和注入�?/span>

一般来��_��支持两种�~�程模型:

注解驱动(annotation-driven). 通过使用注解POJOs, 开发者可与WebSocket生命周期事�g交互.
接口驱动(interface-driven). 开发者可实现Endpoint接口和与生命周期交互的方�?

生命周期事�g

典型的WebSocket 交互生命周期如下:

一�?(客户�? 通过发送HTTP握手��h��来初始化�q�接.
其它�?服务�? 回复握手响应.
建立�q�接.从现在开始，�q�接是完全对�U�的.
两端都可发送和接收消息.
其中一端关闭连�?

大部分WebSocket生命周期事�g都与Java�Ҏ��对应�Q�不��是 annotation-driven �q�是interface-driven.

Annotation-Driven 方式

接受WebSocket��h��的端点可以是�?nbsp;@ServerEndpoint 注解的POJO.

此注解告知容器，此类应该被认为是WebSocket端点.

必须�?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">value 元素指定了WebSocket端点的�\�?

考虑下面的代码片�?

@ServerEndpoint("/hello")  public class MyEndpoint { }

此代码将会以相对路径hello来发布一个端�?在后�l�方法调用中�Q�此路径可携带�\径参敎ͼ�如： /hello/{userid}是一个有效�\径，在这�?/code>{userid} 的��|��可在生命周期�Ҏ��使用@PathParam 注解获取.

在GlassFish中，如果你的应用�E�序是用上下�?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">mycontextroot 部��v的，且在localhost�?span style="color: #000000; font-family: 'Microsoft Yahei';">8080端口上监�?/span>, WebSocket可通过使用ws://localhost:8080/mycontextroot/hello来访�?/code>.

初始化WebSocket�q�接的端点可以是�?nbsp;@ClientEndpoint 注解的POJO.@ClientEndpoint �?@ServerEndpoint的主要区别是ClientEndpoint 不接受�\径�\值元素，因�ؓ它监听进来的��h��?/p>

@ClientEndpoint  public class MyClientEndpoint {}

Java中��用注解驱动POJO方式来初始化WebSocket�q�接�Q�可通过如下代码来完�?

javax.websocket.WebSocketContainer container = javax.websocket.ContainerProvider.getWebSocketContainer();  container.conntectToServer(MyClientEndpoint.class, new URI("ws://localhost:8080/tictactoeserver/endpoint"));

此后�Q�以 @ServerEndpoint �?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">@ClientEndpoint 注解的类都称为注解端�?

一旦徏立了WebSocket�q�接 �Q�就会创�?nbsp;Session�Q��ƈ且会调用注解端点中以@OnOpen注解的方�?

此方法包含了几个参数:

javax.websocket.Session 参数, 代表创徏�?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">Session
EndpointConfig 实例包含了关于端炚w��|�的信息
�Q�个或多个以 @PathParam注解�?/code>字符串参�?指的是端点�\径的path参数

下面的方法实��C��当打开WebSocket�Ӟ��会打印session的标识符:

@OnOpen public void myOnOpen (Session session) {    System.out.println ("WebSocket opened: "+session.getId()); }

Session实例只要WebSocket未关闭就会一直有�?/code>. Session�c�M��包含了许多有意思的�Ҏ��Q�以允许开发者获取更多关于的信息�?/p>

同时,Session 也包含了应用�E�序�Ҏ��的数据钩�?即通过getUserProperties() �Ҏ��来返�?nbsp;Map.

�q�允许开发者可以��用session-和需要在多个�Ҏ��调用间共享的应用�E�序特定信息来填�?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">Session实例.

i当WebSocket端收到消息时�Q�将会调用以@OnMessage注解的方�?�?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">@OnMessage 注解的方法可包含下面的参�?

javax.websocket.Session 参数.
�Q�个或多个以 @PathParam注解�?/code>字符串参�?指的是端点�\径的path参数
消息本��n. 下面有可能消息类型描�q?

当其它端发送了文本消息�Ӟ��下面的代码片断会打印消息内容:

@OnMessage public void myOnMessage (String txt) {    System.out.println ("WebSocket received message: "+txt); }

如果�?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">@OnMessage i注解的方法返回��g��?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">void, WebSocket实现会将�q�回值发送给其它端点.下面的代码片断会��收到的文本消息以首字母大写的�Ş式发回给发送�?

@OnMessage public String myOnMessage (String txt) {    return txt.toUpperCase(); }

另一�U�通过WebSocket�q�接来发送消息的代码如下:

RemoteEndpoint.Basic other = session.getBasicRemote(); other.sendText ("Hello, world");

在这�U�方式中�Q�我们从Session 对象开始，它可以从生命周期回调�Ҏ��中获�?例如,�?nbsp;@OnOpen注解的方�?/code>).session实例�?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">getBasicRemote() �Ҏ��q�回的是WebSocket其它部分的代�?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">RemoteEndpoint. RemoteEndpoint 实例可用于发送文本或其它�c�d��的消息，后面有描�q?

当关闭WebSocket�q�接�?��会调用@OnClose 注解的方法。此�Ҏ��接受下面的参�?

javax.websocket.Session 参数. 注意�Q�一旦WebSocket真正关闭了，此参数就不能被��用了�Q�这通常发生�?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">@OnClose 注解�Ҏ��q�回之后.
A javax.websocket.CloseReason 参数�Q�用于描�q�关闭WebSocket的原�?如：正常关闭�Q�协议错�?服务�q�蝲�{�等.
�Q�个或多个以 @PathParam注解�?/code>字符串参�?指的是端点�\径的path参数

下面的代码片�D�|��C��WebSocket关闭的原�?

@OnClose public void myOnClose (CloseReason reason) {    System.out.prinlnt ("Closing a WebSocket due to "+reason.getReasonPhrase()); }

完整情况下，�q�里�q�有一个生命周期注�?如果收到了错误，��会调用 @OnError 注解的方法�?/p>

`Interface-Driven 方式`

annotation-driven 方式允许我们注解一个Java�c�，以及使用生命周期注解来注解方�?

使用interface-driven方式,开发者可�l�承javax.websocket.Endpoint �q�覆盖其中的onOpen, onClose, 以及onError �Ҏ��:

public class myOwnEndpoint extends javax.websocket.Endpoint {    public void onOpen(Session session, EndpointConfig config) {...}    public void onClose(Session session, CloseReason closeReason) {...}    public void onError (Session session, Throwable throwable) {...} }

��Z��拦截消息�Q�需要在onOpen实现中注册一�?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">javax.websocket.MessageHandler:

public void onOpen (Session session, EndpointConfig config) {    session.addMessageHandler (new MessageHandler() {...}); }

MessageHandler 接口有两个子接口: MessageHandler.Partial�?/code> MessageHandler.Whole.

MessageHandler.Partial 接口应该用于当开发者想要收到部分消息通知的时�?MessageHandler.Whole的实现应该用于整个消息到��N��知�?/p>

下面的代码片断会监听�q�来的文件消息，�q�将文本信息转换为大��版本后发回�l�其它端点：

public void onOpen (Session session, EndpointConfig config) {    final RemoteEndpoint.Basic remote = session.getBasicRemote();    session.addMessageHandler (new MessageHandler.Whole() {       public void onMessage(String text) {                  try {                      remote.sendString(text.toUpperCase());                  } catch (IOException ioe) {                      // handle send failure here                  }              }     }); }

`消息�c�d��Q�编码器�Q�解码器`

WebSocket的JavaAPI非常强大�Q�因为它允许发送�Q或接收�Q何对象作为WebSocket消息.

基本上，有三�U�不同类型的消息:

��Z��文本的消�?/li>
二进制消�?/li>
Pong 消息,它是WebSocket�q�接自��n

当��用interface-driven模式,每个session最多只能�ؓ�q�三个不同类型的消息注册一�?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">MessageHandler.

当��用annotation-driven模式,针对不同�c�d��的消息，只允许出��C��?code style="font-family: Monaco, Consolas, Courier, 'Lucida Console', monospace; color: #666666; background-color: inherit;">@onMessage 注解�Ҏ��. 在注解方法中�Q�消息内容中允许的参��C��赖于消息�c�d��?/p>

Javadoc for the @OnMessage annotation 明确指定了消息类型上允许出现的消息参�?

"如果�Ҏ��用于处理文本消息:
- String 用于接收整个消息
- Java 原型或等��L��cȝ��于接收整个消息�ƈ��其转换为此�c�d��
- String �?boolean 对用于部分接收消�?/li>
- Reader 用于以阻塞流的方式接收整个消�?/li>
- 端点的�Q何对象参数存在文本解码器 (Decoder.Text �?nbsp;Decoder.TextStream).
如果�Ҏ��用于处理二进制消�?
- byte[] �?nbsp;ByteBuffer 用于接收整个消息
- byte[] �?boolean �? 或�?nbsp;ByteBuffer 和boolean对用于部分接收消�?/li>
- InputStream 用于按阻塞流的方式接收整个消�?/span>
- 端点的�Q何对象参数存在二�q�制解码�?Decoder.Binary or Decoder.BinaryStream).
如果�Ҏ��是用于处理pong消息:
- PongMessage 用于处理pong消息"

��M��Java对象使用�~�码器都可以�~�码为基于文本或二进制的消息.�q�种��Z��文本或二�q�制的消息将转输到其它端点，在其它端点，它可以解码成Java对象�Q�或者被另外的WebSocket 包解�?

通常情况下，XML或JSON用于来传送WebSocket消息, �~�码/解码然后会将Java对象�~�组成XML或JSON�q�在另一端解码�ؓJava对象.

encoder是以javax.websocket.Encoder 接口的实现来定义,decoder是以javax.websocket.Decoder 接口的实现来定义�?

有时�Q�端点实例必��ȝ��道encoders和decoders是什�?使用annotation-driven方式, 可向@ClientEndpoint �?nbsp;@ServerEndpoint l注解中的encode和decoder元素传�?encoders和decoders的列表�?/p>

Listing 1 中的代码展示了如何注册一�?nbsp;MessageEncoder �c?它定义了MyJavaObject实例到文本消息的转换). MessageDecoder 是以相反的�{换来注册�?

@ServerEndpoint(value="/endpoint", encoders = MessageEncoder.class, decoders= MessageDecoder.class) public class MyEndpoint { ... }  class MessageEncoder implements Encoder.Text {    @override    public String encode(MyJavaObject obj) throws EncodingException {       ...    } }  class MessageDecoder implements Decoder.Text {    @override     public MyJavaObject decode (String src) throws DecodeException {       ...    }     @override     public boolean willDecode (String src) {       // return true if we want to decode this String into a MyJavaObject instance    } }

Listing 1

Encoder 接口有多个子接口:

Encoder.Text 用于��Java对象转成文本消息
Encoder.TextStream 用于��Java对象��d��到字�W�流�?/li>
Encoder.Binary 用于��Java对象转换成二�q�制消息
Encoder.BinaryStream 用于��Java对象��d��C��q�制��中

�c�M��?Decoder 接口有四个子接口:

Decoder.Text 用于��文本消息�{换成Java对象
Decoder.TextStream 用于从字�W�流中读取Java对象
Decoder.Binary 用于��二�q�制消息转换成Java对象
Decoder.BinaryStream 用于从二�q�制��中��d��Java对象

�l�论

WebSocket Java API为Java开发者提供了标准API来集成IETF WebSocket标准.通过�q�样做，Web 客户端或本地客户端可使用��M��WebSocket实现来轻易地与Java后端通信�?/p>

Java Api是高度可配置的，灉|��的，它允许java开发者��用他们喜�Ƣ的模式�?/div>

也可参�?/span>

JSR 356 on jcp.org
JSR 356 specification work on java.net
Tyrus (JSR 356 Reference Implementation) on java.net
JSR 342, the Java EE 7 umbrella specification on jcp.org
GlassFish, the Reference Implementation for Java EE

胡小�?/a> 2016-07-24 01:35 发表评论

亚洲色偷偷综合亚洲AV伊人蜜桃 ,国产偷国产偷亚洲清高APP,亚洲熟女少妇一区二区