Wednesday, June 2nd, 2010

Stomple: Stomping to the server via WebSockets

Category: JavaScript, Library

Karl Krukow has created Stomple, a library that “enables using the browser as a reliable messaging client, e.g. for JMS.” It is trivially simple to now have a browser (that supports this new WebSockets world) to join in with JMS backends, and start to consume.

To get going it is as simple as:


  1. var client = Stomple.create_client({
  2.     url : "ws://localhost:61614/stomp",
  3.     destination : "",
  4.     login : "guest",
  5.     passcode : "guest"
  6. });
  8. client.subscribe({
  9.     success: function(frame) {//called if subscribe succeeds within timeout-period
  10.         //subscribe succeeded... do something
  11.     },
  12.     failure: function(spec) {//called if subscribe fails or times out
  13.         console.log(spec.reason);
  14.     },
  15.     handler: function(msg) {//called when a message arrived ('this' is scope - see below)
  16.         this.received = msg.body;//"this" is "someObject"
  17.     },
  18.     scope: someObject
  19. });


  • Customizability and Callbacks. A key value of Stomple is that it shouldn’t cut off access to any low-level functionality. Hence everything is customizable and accessible to the user code. All core functions support success and failure callbacks. Further, there are low-level callbacks: socketOpen, socketMessage, socketClose, socketError corresponding to the low-level websocket events. These can be used to customize behaviour for special use-cases. At a higher-level, there are callbacks onConnect, connectFailed, onError, onReceipt correspoding to the Stomp events.
  • Automatic receipts. If client.autoReceipt is true (which it is by default), then all Stomp messages sent to the server include an automatically generated ‘receipt’ header. In the Stomp protocol, this causes the server to send a receipt for each message it receives, hence reassuring that the message has been received. If not enabled, the client can’t be sure the message is actually received.
  • Timeouts. By default all messages sent to the server are associated with a (configurable) 8 second timeout. So for example, suppose you subscribe to a destination, but do not receive a server receipt within 8 seconds: then your failure callback is called with reason ‘timeout’ and information about the message that failed. This way you are guaranteed that either your success or failure callback will always be called (but not both :) ). These time-outs are pervasive and configurable per API call.
  • Transaction management. In Stomp, transactions are started using the ‘BEGIN’ frame, corresponding to a begin function in Stomple. When you call begin, you don’t have to specify a transaction-id: if you don’t, one will be generated automatically for you. Further, any API calls made between a begin and a commit/abort automatically use this transaction identifier, hence grouping the calls in the same transaction (unless, of course, you explicitly provide a different or no transaction id). Further, this nests arbitrarily, and works in a stack-like manner (e.g., begin, begin, send, associates send with inner-most begin).
  • Feature complete. Stomple aims to be feature complete. For example, it supports the recommended Stomp ‘content-length’ header, where the current stomp-websocket version does not.
  • Correctness. Stomple is tested manually and has a growing automatic test-suite written in YUI3-test. Stomple passes JSLint.

Fork it and stomp instantly to JMS and beyond.

Posted by Dion Almaer at 2:38 am
Comment here

5 rating from 1 votes

Comments Here »

Comments feed TrackBack URI

Leave a comment

You must be logged in to post a comment.