摘要：為了知道連接的結果，你需要一個回調函數。每次服務端向客戶端發送消息時，客戶端都會輪流調用回調函數，參數為對應消息的幀對象。

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

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

該庫支持多種版本的STOMP協議：

STOMP 1.0

[STOMP 1.1]2

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

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

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

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

HornetQ是由Red Hat and JBoss創立的開源消息系統.

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

$ 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已經開啟了，并且61614在端口監聽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 服務端進行交互。

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

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

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

瀏覽器提供了不同的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在這兩種方式下是相同的。

通過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環境下，Stomp API都是相同的。

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

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

如果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。

當客戶端與服務端連接成功后，可以調用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。

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

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

為了在瀏覽器中接收消息，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）。如下所示：

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參數用來標識附加的頭部。

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

STOMP消息的body必須為字符串。如果你需要發送/接收JSON對象，你可以使用JSON.stringify()和JSON.parse()去轉換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);
};

默認情況，在消息發送給客戶端之前，服務端會自動確認（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()方法的參數相同。

可以在將消息的發送和確認接收放在一個事務中。

客戶端調用自身的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

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

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

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

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