Simplified stomp.js API

@jmesnil jmesnil released this Sep 3, 2013

The Stomp API has been updated to make code simpler to write and understand.
The documentation has been updated to reflect the new API.

Simplified API:

Connection

The connect() method accepts different number of arguments to provide a simple API to use in most cases:

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

where login, passcode are strings and connectCallback and errorCallback are functions (some brokers also require to pass a host String).

The connect() method also accepts two other variants if you need to pass additional headers:

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

where header is a map and connectCallback and errorCallback are functions.

Please note that if you use these forms, you must add the login, passcode (and eventually host) headers yourself:

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

Acknowledgement

add ack() and nack() methods to the message
object passed to the subscribe callback.

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

Unsubscription

Instead of returning an id from client.subscribe(), return
an object with an unsubscribe() method that can be called directly.

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

Transaction

The begin() method returns a JavaScript object with commit() and
abort() methods to complete the transaction.

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

A transaction ID is automatically generated when calling 'begin() and is available in the returned object's idproperty.

Miscellanous changes and fixes

default onreceive method

When a subscription is automatically created on the broker-side, the received messages are discarded by the Stomp.client that find no matching callback for the subscription headers.
To workaround that, the client can set a default onreceive callback that will be called if no matching subscription is found.
This is required to support RabbitMQ temporary queue destinations.

debug log

By default, debug messages are now written in window.console.

WebWorker support

STOMP can now be used from a WebWorker (an example shows how to use it).

STOMP frame fragmentation

If the STOMP frames are big to send on a single WebSocket frame, some web server may have trouble process them. It is now possible to split a STOMP frame on multiple Web Socket frames by configuring the client.maxWebSocketFrameSize (in bytes). If the STOMP frame is bigger than this size, it will be send over multiple Web Socket frames (default is 16KiB).

use the 1st value for repeated headers

Stomp.js was keeping the last value of repeated headers. This has been fixed according to the specification to take the 1st value of repeated headers.

fix generation of timestamp on IE8

Make sure that timestamp generation works on IE8.

Downloads