StompJS使用文档总结

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

STOMP

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

ws://

Stomp.client(url)

var url = "ws://localhost:61614/stomp";

var client = Stomp.client(url);

　　Stomp.client(url, protocols)subprotocolssubprotocols

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

stomp.jsWebSocket class

Stomp.over(ws)

SockJS

Stomp.client(url)Stomp.over(ws)

node.js

stompjs npm packagenode.js

npm install stompjs

apprequirevar Stomp = require('stompjs');

Stomp.overTCP(host, port)

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

Stomp.overWS(url)

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

　　除了初始化不同，无论是浏览器还是node.js环境下，Stomp API都是相同的。

二、链接服务端

connect()CONNECT frame

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

var connect_callback = function() {

    // called back after the client is connected and authenticated to the STOMP server

};

　　但是如果连接失败会发生什么呢？

connect()error_callbackerror_callback

var error_callback = function(error) {

    // display the error's message header:

    alert(error.headers.message);

};

connect()

client.connect(login, passcode, connectCallback);

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

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

　　loginpasscodeconnectCallbackerrorCallbackhost

headersconnect

client.connect(headers, connectCallback);

client.connect(headers, connectCallback, errorCallback);

　　headermapconnectCallbackerrorCallback

headersloginpasscodehost

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!");

};

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

三、Heart-beating

heart-beating

heart-beatingincomingoutgoingincomingoutgoingheart-beating

client.heartbeat.outgoing = ;

// client will send heartbeats every 20000ms

client.heartbeat.incoming = ;

// client does not want to receive heartbeats

// from the server

　　heart-beatingwindow.setInterval()heart-beatsheart-beats

四、发送消息

send()headersobjectbody

client.send("/queue/test", {priority: }, "Hello, STOMP");

// client会发送一个STOMP发送帧给/queue/test，这个帧包含一个设置了priority为9的header和内容为“Hello, STOMP”的body。

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

bodyheadersheaders{}

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

destination

subscribe()destinationcallbackheadersdestinationfunction

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

　　subscribe()objectobjectid

unsubscribe()destination

headersIDheadersID

var mysubid = '...';

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

SUBSCRIBE frameFrame 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()objectunsubscribe()

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

...

subscription.unsubscribe();

六、支持JSON

bodyJSONJSON.stringify()JSON.parse()

七、Acknowledgment(确认)

acknowledged

ack headerclientclient-individual

message.ack()

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

    function(message) {

        // do something with the message

        ...

        // and acknowledge it

        message.ack();

    },

    {ack: 'client'}

);

　　ack()headersACK STOMP frame

var tx = client.begin();

message.ack({ transaction: tx.id, receipt: 'my-receipt' });

tx.commit();

　　nack()ack()

八、事务(Transactions)

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

begin()begin()transactionid

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()

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

九、调试

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

debug

client.debug = function(str) {

    // append the debug log to a #debug div somewhere in the page using JQuery:

    $("#debug").append(str + "\n");

};

十、使用情况

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

client.debug = null