stomp.js 2.1.0 is Released

I have released a new version of Stomp over WebSockets.

During my summer holidays, I have simplified its API to make it more object-oriented instead of a simple translation of the protocol frames. The new API is backwards compatible except for the susbcription change.

The documentation has been updated to reflect the new API.

I also created a 2.1.0 release on GitHub to provide a well-known location to download stomp.js (and its minified version).

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

The message objects passed to the subscribe callback now have ack() and nack() methods to directly acknowledge (or not) the message.

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(), subscribe() returns an object with an id property corresponding to the subscription ID and an unsubscribe() method.

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 id property.

Miscellaneous 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.

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

• 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