摘要：為了知道連接的結(jié)果，你需要一個回調(diào)函數(shù)。每次服務(wù)端向客戶端發(fā)送消息時，客戶端都會輪流調(diào)用回調(diào)函數(shù)，參數(shù)為對應(yīng)消息的幀對象。

前兩天整理了websocket的資料，今天就把上次沒說完的Stomp.js好好說一說~
Stomp Over Webscoket參考文檔：http://jmesnil.net/stomp-webs...
本文為參考文檔的部分翻譯，技術(shù)不佳，如有失誤請指正。
本文轉(zhuǎn)載自個人博客：http://lsxj615.com/2016/08/17...

STOMP即Simple (or Streaming) Text Orientated Messaging Protocol，簡單(流)文本定向消息協(xié)議，它提供了一個可互操作的連接格式，允許STOMP客戶端與任意STOMP消息代理（Broker）進行交互。STOMP協(xié)議由于設(shè)計簡單，易于開發(fā)客戶端，因此在多種語言和多種平臺上得到廣泛地應(yīng)用。

該庫支持多種版本的STOMP協(xié)議：

STOMP 1.0

[STOMP 1.1]2

你可以下載 stomp.js 并在你自己的WEB應(yīng)用程序中使用。
提供了多種版本也可以直接用于生產(chǎn)。
這個js文件由CoffeeScript文件構(gòu)建，請查看Contribute部分下載源碼或瀏覽 annote source code

這個庫不是單純的Stomp 客戶端。它旨在WebSockets上運行而不是TCP。基本上，WebSocket協(xié)議需要在瀏覽器客戶端和服務(wù)端之間進行握手，確保瀏覽器的“same-origin”（同源）安全模型仍然有效。

這意味著該庫不能連接常規(guī)的STOMP代理，因為Websocket初始化的握手不是STOMP協(xié)議的一部分，他們不能理解從而會拒絕連接。

有一些正在進行的工作添加了WebSocket支持STOMP代理，從而他們可以在WebSocket協(xié)議上接受STOMP連接。

HornetQ是由Red Hat and JBoss創(chuàng)立的開源消息系統(tǒng).

要使HornetQ支持STOMP Over WebSocket，下載最新版本并按照下列步驟執(zhí)行：

$ cd hornetq-x.y.z/examples/jms/stomp-websockets
$ mvn clean install
...
INFO: HQ221020: Started Netty Acceptor version 3.6.2.Final-c0d783c         localhost:61614 for STOMP_WS protocol
Apr 15, 2013 1:15:33 PM org.hornetq.core.server.impl.HornetQServerImpl$SharedStoreLiveActivation run
INFO: HQ221007: Server is now live
Apr 15, 2013 1:15:33 PM org.hornetq.core.server.impl.HornetQServerImpl start
INFO: HQ221001: HornetQ Server version 2.3.0.CR2 (black"n"yellow2, 123) [c9e29e45-a5bd-11e2-976a-b3fef7ceb5df]

此時HornetQ已經(jīng)開啟了，并且61614在端口監(jiān)聽STOMP over WebSocket
它從URL為ws://localhost:61614/stomp 接受WebSocket的連接。

配置文檔

配置文檔

配置文檔

配置文檔

Stilts 是一個STOMP原生的消息框架。

TorqueBox 使用Stilts去提供它的Websockets and STOMP stack。

STOMP Over WebSocket 提供了一個直接從Stomp Frame映射到 Javascript 對象的方式。
Stomp Frame幀格式如下：

command和headers屬性始終會被定義，不過當這個frame沒有頭部時，headers可以為空。若這個frame沒有body，body的值可以為null。

STOMP javascript 客戶端會使用ws://的URL與STOMP 服務(wù)端進行交互。

為了創(chuàng)建一個STOMP客戶端js對象，你需要使用Stomp.client(url)，而這個URL連接著服務(wù)端的WebSocket的代理：

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

Stomp.client(url, protocols)也可以用來覆蓋默認的subprotocols。第二個參數(shù)可以是一個字符串或一個字符串數(shù)組去指定多個subprotocols。

瀏覽器提供了不同的WebSocket的協(xié)議，一些老的瀏覽器不支持WebSocket的腳本或者使用別的名字。默認下，stomp.js會使用瀏覽器原生的WebSocket class去創(chuàng)建WebSocket。

但是利用Stomp.over(ws)這個方法可以使用其他類型的WebSockets。這個方法得到一個滿足WebSocket定義的對象。

例如，可以使用由SockJS實現(xiàn)的Websocket：

如果使用原生的Websockets就使用Stomp.client(url)，如果需要使用其他類型的Websocket（例如由SockJS包裝的Websocket）就使用Stomp.over(ws)。

除了初始化有差別，Stomp API在這兩種方式下是相同的。

通過stompjs npm package同樣也可以在node.js程序中使用這個庫。

$ npm install stompjs

在node.jsapp中, 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環(huán)境下，Stomp API都是相同的。

一旦Stomp 客戶端建立了，必須調(diào)用它的connect()方法去連接，從而Stomp服務(wù)端進行驗證。這個方法需要兩個參數(shù)，用戶的登錄和密碼憑證。

這種情況下，客戶端會使用Websocket打開連接，并發(fā)送一個CONNECT frame。

這個連接是異步進行的：你不能保證當這個方法返回時是有效連接的。為了知道連接的結(jié)果，你需要一個回調(diào)函數(shù)。

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

但是如果連接失敗會發(fā)生什么呢？connect()方法接受一個可選的參數(shù)(error_callback)，當客戶端不能連接上服務(wù)端時，這個回調(diào)函數(shù)error_callback會被調(diào)用，該函數(shù)的參數(shù)為對應(yīng)的錯誤對象。

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

在大多數(shù)情況下，connect()方法可接受不同數(shù)量的參數(shù)來提供簡單的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類型）參數(shù)。）

如果你需要附加一個headers頭部，connect方法還接受其他兩種形式的參數(shù)：

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

斷開連接時，調(diào)用disconnect方法，這個方法也是異步的，當斷開成功后會接收一個額外的回調(diào)函數(shù)的參數(shù)。如下所示。

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

當客戶端與服務(wù)端斷開連接，就不會再發(fā)送或接收消息了。

如果STOMP broker(代理)接收STOMP 1.1版本的幀，heart-beating是默認啟用的。heart-beating也就是頻率，incoming是接收頻率，outgoing是發(fā)送頻率。

通過改變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()去規(guī)律地發(fā)送heart-beats或者檢查服務(wù)端的heart-beats。

當客戶端與服務(wù)端連接成功后，可以調(diào)用send()來發(fā)送STOMP消息。這個方法必須有一個參數(shù)，用來描述對應(yīng)的STOMP的目的地。另外可以有兩個可選的參數(shù)：headers，object類型包含額外的信息頭部；body，一個String類型的參數(shù)。

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

client會發(fā)送一個STOMP發(fā)送幀給/queue/test，這個幀包含一個設(shè)置了priority為9的header和內(nèi)容為“Hello, STOMP”的body。

如果你想發(fā)送一個有body的信息，也必須傳遞headers參數(shù)。如果沒有headers需要傳遞，那么就傳{}即可，如下所示：

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

為了在瀏覽器中接收消息，STOMP客戶端必須先訂閱一個目的地destination。

你可以使用subscribe()去訂閱。這個方法有2個必需的參數(shù)：目的地(destination)，回調(diào)函數(shù)(callback)；還有一個可選的參數(shù)headers。其中destination是String類型，對應(yīng)目的地，回調(diào)函數(shù)是伴隨著一個參數(shù)的function類型。

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

subscribe()方法返回一個object，這個object包含一個id屬性，對應(yīng)這個這個客戶端的訂閱ID。而unsubscribe()可以用來取消客戶端對這個目的地destination的訂閱。

默認情況下，如果沒有在headers額外添加，這個庫會默認構(gòu)建一個獨一無二的ID。在傳遞headers這個參數(shù)時，可以使用你自己的ID:

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

這個客戶端會向服務(wù)端發(fā)送一個STOMP訂閱幀（SUBSCRIBE frame）并注冊回調(diào)事件。每次服務(wù)端向客戶端發(fā)送消息時，客戶端都會輪流調(diào)用回調(diào)函數(shù)，參數(shù)為對應(yīng)消息的STOMP幀對象（Frame object）。如下所示：

callback = function(message) {
    // called when the client receives a STOMP message from the server
    if (message.body) {
        alert("got message with body " + message.body)
    } else {
        alert("got empty message");
    }
});

subscribe()方法，接受一個可選的headers參數(shù)用來標識附加的頭部。

var headers = {ack: "client", "selector": "location = "Europe""};

client.subscribe("/queue/test", message_callback, headers);

這個客戶端指定了它會確認接收的信息，只接收符合這個selector : location = "Europe"的消息。

如果想讓客戶端訂閱多個目的地，你可以在接收所有信息的時候調(diào)用相同的回調(diào)函數(shù)：

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對象調(diào)用unsubscribe()來結(jié)束接收。

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

...

subscription.unsubscribe();

STOMP消息的body必須為字符串。如果你需要發(fā)送/接收JSON對象，你可以使用JSON.stringify()和JSON.parse()去轉(zhuǎn)換JSON對象。

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);
};

默認情況，在消息發(fā)送給客戶端之前，服務(wù)端會自動確認（acknowledged）。

客戶端可以選擇通過訂閱一個目的地時設(shè)置一個ack header為client或client-individual來處理消息確認。

在下面這個例子，客戶端必須調(diào)用message.ack()來通知服務(wù)端它已經(jīng)接收了消息。

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

ack()接受headers參數(shù)用來附加確認消息。例如，將消息作為事務(wù)(transaction)的一部分，當要求接收消息時其實代理（broker）已經(jīng)將ACK STOMP frame處理了。

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

nack()也可以用來通知STOMP 1.1.brokers（代理）：客戶端不能消費這個消息。與ack()方法的參數(shù)相同。

可以在將消息的發(fā)送和確認接收放在一個事務(wù)中。

客戶端調(diào)用自身的begin()方法就可以開始啟動事務(wù)了，begin()有一個可選的參數(shù)transaction，一個唯一的可標識事務(wù)的字符串。如果沒有傳遞這個參數(shù)，那么庫會自動構(gòu)建一個。

這個方法會返回一個object。這個對象有一個id屬性對應(yīng)這個事務(wù)的ID，還有兩個方法：
commit()提交事務(wù)
abort()中止事務(wù)

在一個事務(wù)中，客戶端可以在發(fā)送/接受消息時指定transaction id來設(shè)置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();

如果你在調(diào)用send()方法發(fā)送消息的時候忘記添加transction header，那么這不會稱為事務(wù)的一部分，這個消息會直接發(fā)送，不會等到事務(wù)完成后才發(fā)送。

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

有一些測試代碼能有助于你知道庫發(fā)送或接收的是什么，從而來調(diào)試程序。

客戶端可以將其debug屬性設(shè)置為一個函數(shù)，傳遞一個字符串參數(shù)去觀察庫所有的debug語句。

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

默認情況，debug消息會被記錄在在瀏覽器的控制臺。