StompJS使用文档总结

　　STOMP即Simple (or Streaming) Text Orientated Messaging Protocol，简单(流)文本定向消息协议，它提供了一个可互操做的链接格式，容许STOMP客户端与任意STOMP消息代理（Broker）进行交互。STOMP协议因为设计简单，易于开发客户端，所以在多种语言和多种平台上获得普遍地应用。

1、建立STOMP客户端

一、在web浏览器中使用普通的Web Socket

　　STOMP javascript 客户端会使用ws://的URL与STOMP 服务端进行交互。

　　为了建立一个STOMP客户端js对象，你须要使用Stomp.client(url)，而这个URL链接着服务端的WebSocket的代理

var url = "ws://localhost:61614/stomp"; var client = Stomp.client(url);

　　Stomp.client(url, protocols)也能够用来覆盖默认的subprotocols。第二个参数能够是一个字符串或一个字符串数组去指定多个subprotocols。

二、在web浏览器中使用定制的WebSocket

　　浏览器提供了不一样的WebSocket的协议，一些老的浏览器不支持WebSocket的脚本或者使用别的名字。默认下，stomp.js会使用浏览器原生的WebSocket class去建立WebSocket。

　　可是利用Stomp.over(ws)这个方法可使用其余类型的WebSockets。这个方法获得一个知足WebSocket定义的对象。

　　例如，可使用由SockJS实现的Websocket。

　　若是使用原生的Websockets就使用Stomp.client(url)，若是须要使用其余类型的Websocket（例如由SockJS包装的Websocket）就使用Stomp.over(ws)。除了初始化有差异，Stomp API在这两种方式下是相同的。

三、在node.js程序中

　　经过stompjs npm package一样也能够在node.js程序中使用这个库。

　　npm install stompjs

　　在node.js app中，require这个模块：var Stomp = require('stompjs');

　　为了与创建在TCP socket的STOMP-broker链接，使用Stomp.overTCP(host, port)方法。

var client = Stomp.overTCP('localhost', 61613);

　　为了与创建在Web Socket的STOMP broker链接，使用Stomp.overWS(url)方法。

var client = Stomp.overWS('ws://localhost:61614/stomp');

　　除了初始化不一样，不管是浏览器仍是node.js环境下，Stomp API都是相同的。

2、连接服务端

　　一旦Stomp 客户端创建了，必须调用它的connect()方法去链接Stomp服务端进行验证。这个方法须要两个参数，用户的登陆和密码凭证。这种状况下，客户端会使用Websocket打开链接，并发送一个CONNECT frame。

　　这个链接是异步进行的：你不能保证当这个方法返回时是有效链接的。为了知道链接的结果，你须要一个回调函数。

var connect_callback = function() { // called back after the client is connected and authenticated to the STOMP server
};

　　可是若是链接失败会发生什么呢？

　　connect()方法接受一个可选的参数(error_callback)，当客户端不能链接上服务端时，这个回调函数error_callback会被调用，该函数的参数为对应的错误对象。

var error_callback = function(error) { // display the error's message header:
 alert(error.headers.message); };

　　在大多数状况下，connect()方法可接受不一样数量的参数来提供简单的API：

client.connect(login, passcode, connectCallback);
client.connect(login, passcode, connectCallback, errorCallback);
client.connect(login, passcode, connectCallback, errorCallback, host);

　　login和passcode是strings，connectCallback和errorCallback则是functions。（有些brokers（代理）还须要传递一个host（String类型）参数。）

　　若是你须要附加一个headers头部，connect方法还接受其余两种形式的参数：

client.connect(headers, connectCallback);
client.connect(headers, connectCallback, errorCallback);

　　header是map形式，connectCallback和errorCallback为functions。

　　须要注意：若是你使用上述这种方式，你须要自行在headers添加login、passcode（甚至host）：

var headers = { login: 'mylogin', passcode: 'mypasscode', // additional header
    'client-id': 'my-client-id' }; client.connect(headers, connectCallback);

　　断开链接时，调用disconnect方法，这个方法也是异步的，当断开成功后会接收一个额外的回调函数的参数。以下所示。

client.disconnect(function() { alert("See you next time!"); };

　　当客户端与服务端断开链接，就不会再发送或接收消息了。

3、Heart-beating

　　若是STOMP broker(代理)接收STOMP 1.1版本的帧，heart-beating是默认启用的。

　　heart-beating也就是频率，incoming是接收频率，outgoing是发送频率。经过改变incoming和outgoing能够更改客户端的heart-beating(默认为10000ms)：

client.heartbeat.outgoing = 20000; // client will send heartbeats every 20000ms
client.heartbeat.incoming = 0; // client does not want to receive heartbeats // from the server

　　heart-beating是利用window.setInterval()去规律地发送heart-beats或者检查服务端的heart-beats。

4、发送消息

　　当客户端与服务端链接成功后，能够调用send()来发送STOMP消息。这个方法必须有一个参数，用来描述对应的STOMP的目的地。另外能够有两个可选的参数：headers，object类型包含额外的信息头部；body，一个String类型的参数。

client.send("/queue/test", {priority: 9}, "Hello, STOMP"); // client会发送一个STOMP发送帧给/queue/test，这个帧包含一个设置了priority为9的header和内容为“Hello, STOMP”的body。

　　client.send(destination, {}, body);

　　若是你想发送一个有body的信息，也必须传递headers参数。若是没有headers须要传递，那么就传{}便可。

5、订阅（Subscribe）和接收（receive）消息

　　为了在浏览器中接收消息，STOMP客户端必须先订阅一个目的地destination。

　　你可使用subscribe()去订阅。这个方法有2个必需的参数：目的地(destination)，回调函数(callback)；还有一个可选的参数headers。其中destination是String类型，对应目的地，回调函数是伴随着一个参数的function类型。

var subscription = client.subscribe("/queue/test", callback);

　　subscribe()方法返回一个object，这个object包含一个id属性，对应这个这个客户端的订阅ID。

　　而unsubscribe()能够用来取消客户端对这个目的地destination的订阅。

　　默认状况下，若是没有在headers额外添加，这个库会默认构建一个独一无二的ID。在传递headers这个参数时，可使用你本身的ID。

var mysubid = '...'; var subscription = client.subscribe(destination, callback, { id: mysubid });

　　这个客户端会向服务端发送一个STOMP订阅帧（SUBSCRIBE frame）并注册回调事件。每次服务端向客户端发送消息时，客户端都会轮流调用回调函数，参数为对应消息的STOMP帧对象（Frame object）。

　　subscribe()方法，接受一个可选的headers参数用来标识附加的头部。

var headers = {ack: 'client', 'selector': "location = 'Europe'"}; client.subscribe("/queue/test", message_callback, headers);

　　这个客户端指定了它会确认接收的信息，只接收符合这个selector : location = 'Europe'的消息。

　　若是想让客户端订阅多个目的地，你能够在接收全部信息的时候调用相同的回调函数：

onmessage = function(message) { // called every time the client receives a message
} var sub1 = client.subscribe("queue/test", onmessage); var sub2 = client.subscribe("queue/another", onmessage)

　　若是要停止接收消息，客户端能够在subscribe()返回的object对象调用unsubscribe()来结束接收。

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

6、支持JSON

　　STOMP消息的body必须为字符串。若是你须要发送/接收JSON对象，你可使用JSON.stringify()和JSON.parse()去转换JSON对象。

7、Acknowledgment(确认)

　　默认状况，在消息发送给客户端以前，服务端会自动确认（acknowledged）。

　　客户端能够选择经过订阅一个目的地时设置一个ack header为client或client-individual来处理消息确认。

　　在下面这个例子，客户端必须调用message.ack()来通知服务端它已经接收了消息。

var subscription = client.subscribe("/queue/test", function(message) { // do something with the message
 ... // and acknowledge it
 message.ack(); }, {ack: 'client'} );

　　ack()接受headers参数用来附加确认消息。例如，将消息做为事务(transaction)的一部分，当要求接收消息时其实代理（broker）已经将ACK STOMP frame处理了。

var tx = client.begin(); message.ack({ transaction: tx.id, receipt: 'my-receipt' }); tx.commit();

　　nack()也能够用来通知STOMP 1.1.brokers（代理）：客户端不能消费这个消息。与ack()方法的参数相同。

8、事务(Transactions)

　　能够在将消息的发送和确认接收放在一个事务中。

　　客户端调用自身的begin()方法就能够开始启动事务了，begin()有一个可选的参数transaction，一个惟一的可标识事务的字符串。若是没有传递这个参数，那么库会自动构建一个。这个方法会返回一个object。这个对象有一个id属性对应这个事务的ID，还有两个方法：

　　commit()提交事务

　　abort()停止事务

　　在一个事务中，客户端能够在发送/接受消息时指定transaction id来设置transaction。

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

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

var txid = "unique_transaction_identifier"; // start the transaction
var tx = client.begin(); // oops! send the message outside the transaction
client.send("/queue/test", {}, "I thought I was in a transaction!"); tx.abort(); // Too late! the message has been sent

9、调试

　　有一些测试代码能有助于你知道库发送或接收的是什么，从而来调试程序。

　　客户端能够将其debug属性设置为一个函数，传递一个字符串参数去观察库全部的debug语句。默认状况，debug消息会被记录在在浏览器的控制台。

client.debug = function(str) { // append the debug log to a #debug div somewhere in the page using JQuery:
    $("#debug").append(str + "\n"); };

10、使用状况

一、var error_callback = function(error) {
　　第一次链接失败和链接后断开链接都会调用这个函数
};

二、关闭控制台调试数据：设置client.debug = null 就能够，stompjs会去检测debug是不是函数，不是函数就不会调用输出