STOMP 客户端 API 整理

STOMP(Simple Text-Orientated Messaging Protocol) 面向消息的简单文本协议
WebSocket是一个消息架构,不强制使用任何特定的消息协议,它依赖于应用层解释消息的含义;
与处在应用层的HTTP不同,WebSocket处在TCP上非常薄的一层,会将字节流转换为文本/二进制消息,因此,对于实际应用来说,WebSocket的通信形式层级过低,因此,可以在 WebSocket 之上使用 STOMP协议,来为浏览器 和 server间的 通信增加适当的消息语义。

如何理解 STOMP 与 WebSocket 的关系:
1) HTTP协议解决了 web 浏览器发起请求以及 web 服务器响应请求的细节,假设 HTTP 协议 并不存在,只能使用 TCP 套接字来 编写 web 应用,你可能认为这是一件疯狂的事情;
2) 直接使用 WebSocket(SockJS) 就很类似于 使用 TCP 套接字来编写 web 应用,因为没有高层协议,就需要我们定义应用间所发送消息的语义,还需要确保连接的两端都能遵循这些语义;
3) 同 HTTP 在 TCP 套接字上添加请求-响应模型层一样,STOMP 在 WebSocket 之上提供了一个基于帧的线路格式层,用来定义消息语义;
STOMP帧

STOMP帧由命令,一个或多个头信息、一个空行及负载(文本或字节)所组成;
其中可用的COMMAND 包括: CONNECT、SEND、SUBSCRIBE、UNSUBSCRIBE、BEGIN、COMMIT、ABORT、ACK、NACK、DISCONNECT;
例:发送消息

    SEND
    destination:/queue/trade
    content-type:application/json
    content-length:44
    {“action”:”BUY”,”ticker”:”MMM”,”shares”,44}^@

 订阅消息

 SUBSCRIBE
    id:sub-1
    destination:/topic/price.stock.*
    ^@

服务器进行广播消息

   MESSAGE
    message-id:nxahklf6-1
    subscription:sub-1
    destination:/topic/price.stock.MMM
    {“ticker”:”MMM”,”price”:129.45}^@

 客户端 API
引入stomp.js
<script type="application/javascript" src="http://cdn.bootcss.com/stomp.js/2.3.3/stomp.min.js"></script>
发起连接
客户端可以通过使用Stomp.js和sockjs-client连接

// 建立连接对象(还未发起连接)
var socket=new SockJS("/spring-websocket-portfolio/portfolio");
// 获取 STOMP 子协议的客户端对象
var stompClient = Stomp.over(socket);
// 向服务器发起websocket连接并发送CONNECT帧
stompClient.connect({},function connectCallback (frame) {
    // 连接成功时(服务器响应 CONNECTED 帧)的回调方法
        document.getElementById("state-info").innerHTML = "连接成功";
        console.log(‘已连接【‘ + frame + ‘】‘);
        stompClient.subscribe(‘/topic/getResponse‘, function (response) {
            showResponse(response.body);
        });
    },
function errorCallBack (error) {
    // 连接失败时(服务器响应 ERROR 帧)的回调方法
        document.getElementById("state-info").innerHTML = "连接失败";
        console.log(‘连接失败【‘ + error + ‘】‘);
    }
);
//1) socket连接对象也可通过WebSocket(不通过SockJS)连接
var socket=new WebSocket("/spring-websocket-portfolio/portfolio");
//2) stompClient.connect()方法签名:
client.connect(headers, connectCallback, errorCallback);
//其中headers表示客户端的认证信息,如:
var headers = {
  login: ‘mylogin‘,
  passcode: ‘mypasscode‘,
  // additional header
  ‘client-id‘: ‘my-client-id‘
};若无需认证,直接使用空对象 “{}” 即可;
connectCallback 表示连接成功时(服务器响应 CONNECTED 帧)的回调方法;
errorCallback 表示连接失败时(服务器响应 ERROR 帧)的回调方法,非必须;
//断开连接   若要从客户端主动断开连接,可调用 disconnect() 方法
client.disconnect(function () {
   alert("See you next time!");
}
//该方法为异步进行,因此包含了回调参数,操作完成时自动回调;

心跳机制
若使用STOMP 1.1 版本,默认开启了心跳检测机制,可通过client对象的heartbeat field进行配置(默认值都是10000 ms):
client.heartbeat.outgoing = 20000;  // client will send heartbeats every 20000ms
client.heartbeat.incoming = 0;      // client does not want to receive heartbeats from the server
发送信息

//连接成功后,客户端可使用 send() 方法向服务器发送信息:
client.send(destination url[, headers[, body]]);
/*其中destination url 为服务器 controller中 @MessageMapping 中匹配的URL,字符串,必须参数;
headers 为发送信息的header,JavaScript 对象,可选参数;
body 为发送信息的 body,字符串,可选参数;例:*/
client.send("/queue/test", {priority: 9}, "Hello, STOMP");
client.send("/queue/test", {}, "Hello, STOMP");

订阅、接收信息
STOMP 客户端要想接收来自服务器推送的消息,必须先订阅相应的URL,即发送一个 SUBSCRIBE 帧,然后才能不断接收来自服务器的推送消息;
订阅和接收消息通过 subscribe() 方法实现:

subscribe(destination url, callback[, headers])
/*其中destination url 为服务器 @SendTo 匹配的 URL,字符串;
callback 为每次收到服务器推送的消息时的回调方法,该方法包含参数 message;
headers 为附加的headers该方法返回一个包含了id属性的 JavaScript 对象,可作为 unsubscribe() 方法的参数;*/

取消订阅

var subscription = client.subscribe(...);
subscription.unsubscribe();

JSON 支持
STOMP 帧的 body 必须是 string 类型,若希望接收/发送 json 对象,可通过 JSON.stringify() and JSON.parse() 实现;

var quote = {symbol: ‘APPL‘, value: 195.46};
client.send("/topic/stocks", {}, JSON.stringify(quote));
client.subcribe("/topic/stocks", function(message) {
var quote = JSON.parse(message.body);
alert(quote.symbol + " is at " + quote.value);
});

事务支持
STOMP 客户端支持在发送消息时用事务进行处理:
可以将消息的发送和确认接收放在一个事务中。客户端调用自身的begin()方法就可以开始启动事务了,begin()有一个可选的参数transaction,一个唯一的可标识事务的字符串。如果没有传递这个参数,那么库会自动构建一个。这个方法会返回一个object。这个对象有一个id属性对应这个事务的ID,还有两个方法:commit()提交事务、abort()中止事务。在一个事务中,客户端可以在发送/接受消息时指定transaction id来设置transaction。

var tx = client.begin();
client.send("/queue/test", {transaction: tx.id}, "message in a transaction");
tx.commit();

如果你在调用send()方法发送消息的时候忘记添加transction header,那么这不会称为事务的一部分,这个消息会直接发送,不会等到事务完成后才发送。

调试

有一些测试代码能有助于你知道库发送或接收的是什么,从而来调试程序。客户端可以将其debug属性设置为一个函数,传递一个字符串参数去观察库所有的debug语句。默认情况,debug消息会被记录在在浏览器的控制台。

client.debug = function(str) {
   $("#debug").append(str + "\n");
};

 

STOMP 客户端 API 整理

上一篇:获取windows操作系统所有用户


下一篇:kendo ui grid 编辑行 修改popup window默认的按钮名称