Channel¶
服务概述¶
channel是新浪云提供的实时消息推送服务。通过在浏览器和新浪云服务端之间建立长连接,使得应用可以方便的向javascript客户端实时的推送消息。
下图为channel服务的大致使用流程:
channel服务的使用主要包含两个部分:JS客户端,服务端处理程序。
对于JS客户端,其需要完成:
- 使用应用服务端创建的channel url连接上channel的服务器。
- 设置下行消息的处理函数。
- 需要发送消息时,调用send发送消息给channel服务器(或者直接使用XMLHttpRequest直接发送给应用服务端也可)。
对于应用的服务端:
- 调用create_channel为每个客户端创建一个channel,并将channel的url返回给客户端。
- 处理channel server发过来的客户端上行消息(如果有的话)。
- 有消息要发送时,调用send_message来向客户端推送消息。
当JS客户端和channel服务端连接上/断开或者当JS客户端有发送消息给channel服务器时,channel服务器会使用http回调的方式通知应用。
回调地址 | 事件说明 |
---|---|
/_sae/channel/connected | 客户端连接上channel服务器 |
/_sae/channel/disconnected | 客户端和channel服务器断开 |
/_sae/channel/message | 客户端有上行消息,POST内容的message字段为JS客户端发送的内容 |
所有的http回调都使用POST方法。所有http回调的POST内容中的from字段为客户端对应channel的名称。其余字段(如果有)见具体回调说明。
注解
每个html页面最多可以建立1个channel连接。
API使用手册¶
Server端API:
Javascript客户端API:
在html页面中使用以下代码引用Channel服务的js库。
<script type="text/javascript" src="http://channel.sinaapp.com/api.js"></script>
-
class
sae.
Channel
(url) 参数: - url (string) – 服务端create_channel()返回的url地址
-
sae.Channel.
onopen
设置客户端连接上服务端时的回调函数。
-
sae.Channel.
onmessage
设置客户端收到消息时的回调函数。该函数接受一个参数:一个messagae对象,其中的data字段为服务端send_message接口发送的消息内容。
-
sae.Channel.
onerror
设置客户端和服务端连接出现错误时的回调函数。
-
sae.Channel.
onclose
设置客户端关闭和服务端的连接时的回调函数。
使用示例¶
下面我们使用 TicTacToe(井字棋) 游戏来示范Channel服务的使用方法:
完整代码:https://github.com/sinacloud/sae-channel-examples/tree/master/java
演示地址:http://javachannel.sinaapp.com/
实现简要介绍
玩家1首次打开游戏页面为用户创建一个channel,同时实例化一个Game对象存储至缓存(Memcache)中,等待其他玩家加入;
代码简要实现(详见:https://github.com/sinacloud/sae-channel-examples/blob/master/java/WebContent/index.jsp)
SaeChannel channel = new SaeChannel();
String url1 = channel.createChannel(user1);//创建的channel作为WebSocket url
Game game = new Game(gamekey,user1,url1);
game.put();//game保存至缓存
有玩家2加入游戏时为玩家2创建另一个channel,同时更新缓存中的Game对象,同时向玩家1,2发送消息告知游戏开始;
代码简要实现(详见:https://github.com/sinacloud/sae-channel-examples/blob/master/java/src/game/Opened.java)
String url2 = channel.createChannel(user2);//创建的channel作为WebSocket url
//向玩家发送消息告知游戏开始
channel.sendMessage(user1, game);
channel.sendMessage(user2, game);
游戏进行实时向玩家channel发送消息,更新游戏信息,使用JavaScript的sae.Channel对象的onmessage方法实时更新游戏状态。
代码简要实现(服务端代码详见:https://github.com/sinacloud/sae-channel-examples/blob/master/java/src/game/Opened.java)
game.xMove(1);
game.oMove(2);
channel.sendMessage(user1, game);
channel.sendMessage(user2, game);
//JavaScript
var channel = sae.Channel(url);
channel.onmessage = function(message){
updateGame(message);
}