Stomp Client
===========


A node.js STOMP client. Props goes to Russell
Haering for doing the
initial legwork.

The following enhancements have been added:

* Unit tests
* Ability to support different protocol versions (1.0 or 1.1) - more work needed
* Inbound frame validation (required / regex'able header values)
* Support for UNSUBSCRIBE frames in client
* Ability to add custom headers to SUBSCRIBE/UNSUBSCRIBE frames
* ACK and NACK support

Installation

npm install stomp-client

Super basic example

var Stomp = require('stomp-client');
var destination = '/queue/someQueueName';
var client = new Stomp('127.0.0.1', 61613, 'user', 'pass');

client.connect(function(sessionId) {
client.subscribe(destination, function(body, headers) {
console.log('This is the body of a message on the subscribed queue:', body);
});

client.publish(destination, 'Oh herrow');
});

The client comes in two forms, a standard or secure client. The example below is
using the standard client. To use the secure client simply change
StompClient to SecureStompClient

API

Queue Names

The meaning of queue names is not defined by the STOMP spec, but by the Broker.
However, with ActiveMQ, they should begin with "/queue/" or with "/topic/", see
STOMP1.0 for
more detail.

Stomp = require('stomp-client')

Require returns a constructor for STOMP client instances.

For backwards compatibility, require('stomp-client').StompClient is also
supported.

Stomp(address, [port], [user], [pass], [protocolVersion], [vhost], [reconnectOpts], [tls])

- address: address to connect to, default is "127.0.0.1"
- port: port to connect to, default is 61613
- user: user to authenticate as, default is ""
- pass: password to authenticate with, default is ""
- protocolVersion: see below, defaults to "1.0"
- vhost: see below, defaults to null
- reconnectOpts: see below, defaults to {}
- tls: Establish a tls/ssl connection. If an object is passed for this argument it will passed as options to the tls module.

Protocol version negotiation is not currently supported and version "1.0" is
the only supported version.

ReconnectOpts should contain an integer retries specifying the maximum number
of reconnection attempts, and a delay which specifies the reconnection delay.
(reconnection timings are calculated using exponential backoff. The first reconnection
happens immediately, the second reconnection happens at +delay ms, the third at + 2*delay ms, etc).

Stomp(options)

- options: Properties are named the same as the positional parameters above. The property 'host' is accepted as an alias for 'address'.

stomp.connect([callback, [errorCallback]])

Connect to the STOMP server. If the callbacks are provided, they will be
attached on the 'connect' and 'error' event, respectively.

virtualhosts

If using virtualhosts to namespace your queues, you must pass a version header of '1.1' otherwise it is ignored.

stomp.disconnect(callback)

Disconnect from the STOMP server. The callback will be executed when disconnection is complete.
No reconnections should be attempted, nor errors thrown as a result of this call.

stomp.subscribe(queue, [headers,] callback)

- queue: queue to subscribe to
- headers: headers to add to the SUBSCRIBE message
- callback: will be called with message body as first argument,
and header object as the second argument

stomp.unsubscribe(queue, [headers])

- queue: queue to unsubscribe from
- headers: headers to add to the UNSUBSCRIBE message

stomp.publish(queue, message, [headers])

- queue: queue to publish to
- message: message to publish, a string or buffer
- headers: headers to add to the PUBLISH message

stomp.ack(messageId, subscription, [transaction]),

stomp.nack(messageId, subscription, [transaction])

- messageId: the id of the message to ack/nack
- subscription: the id of the subscription
- transaction: optional transaction name

Property: stomp.publishable (boolean)

Returns whether or not the connection is currently writable. During normal operation
this should be true, however if the client is in the process of reconnecting,
this will be false.

Event: 'connect'

Emitted on successful connect to the STOMP server.

Event: 'error'

Emitted on an error at either the TCP or STOMP protocol layer. An Error object
will be passed. All error objects have a .message property, STOMP protocol
errors may also have a .details property.

If the error was caused by a failure to reconnect after exceeding the number of
reconnection attempts, the error object will have a reconnectionFailed property.

Event: 'reconnect'

Emitted when the client has successfully reconnected. The event arguments are
the new sessionId and the reconnection attempt number.

Event: 'reconnecting'

Emitted when the client has been disconnected for whatever reason, but is going
to attempt to reconnect.

Event: 'message' (body, headers)

Emitted for each message received. This can be used as a simple way to receive
messages for wildcard destination subscriptions that would otherwise not trigger
the subscription callback.

LICENSE

MIT