JBoss.orgCommunity Documentation

Chapter 9. STOMP & WebSockets on TorqueBox

9.1. Overview
9.1.1. What is WebSockets?
9.1.2. What is STOMP?
9.1.3. What are Stomplets?
9.2. Ruby Stomplets
9.2.1. Stomplet API
9.2.2. Example
9.3. JMS Integration
9.3.1. Destination and Message compatibility
9.4. Deployment descriptors
9.5. Javascript Client
9.5.1. Using the Javascript client
9.5.2. Injecting the endpoint URL
9.6. Other Clients (without WebSockets)
9.7. Secure connections (TLS and wss://)
9.8. Further information

TorqueBox provides real-time bidirectional communication between applications and web-browsers using a combination of WebSockets and STOMP. Raw access to WebSockets is not provided. Instead, multiplexed communication is supported through the layering of messaging semantics on top. Additionally, optional integration into other messaging systems (such as JMS/HornetQ) are provided to enable advanced application architectures.

TorqueBox provides support for Stomplets to allow explicit control and design of messaging end-points, instead of simple direct bridging to some other underlying messaging technology, such as a JMS broker.

Ruby Stomplets have a handful of methods which may be implemented to support all messaging actions.

TorqueBox provides useful classes upon which you can build your own application's Stomplets. The most useful of these is TorqueBox::Stomp::JmsStomplet, which handles a large portion of bridging between STOMP and JMS, while allowing the flexibility to adapt the integration to match your particular needs.

The primary assistance it provides is through two methods:

Your own Stomplet may use these methods to handle the heavy-lifting after translating between STOMP destinations and JMS destinations.

When using send_to(...), the stomp_message parameter may be a complete StompMessage, or simply a string, which will be converted into a message. Any headers specified will override any headers provided through the StompMessage.

To deploy Stomplets with your application, a stomp section is added to your application's torquebox.yml or torquebox.rb descriptor. The section should contain named sections for each Stomplet your application needs to deploy. Each Stomplet is bound to a route, which works similar to Rails request routing, but matches against STOMP destinations instead of web URLs. Additionally, it specifies the class of the implementation, along with optional configuration in the form of name/value pairs of strings.

Parameters from flexible routes may be accessed within the on_subscribe() and on_unsubscribe() methods using a hash-like syntax: subscriber[paramName].

STOMP supports the notion of virtual hosts, just as with web container. By default, if your application specifies a virtual host for the web portion of the configuration, the same value will be used for the STOMP container. The host may be overridden, though, by specifying a host: parameter within the stomp: block.

To configure stomplets using the YAML syntax:

To configure stomplets via the DSL:

TorqueBox makes use of the Stilts framework and to implement the WebSockets and STOMP stack. TorqueBox includes the Javascript client provided by the Stilts distribution in the share/javascripts/ directory. The client is derived from work by Jeff Mesnil. The client has several methods of connecting back to the server, transparent to your application:

The Javascript STOMP client isolates your application from the underlying WebSocket protocol. The Javascript client works purely in terms of STOMP semantics. The client is based around callbacks.

The client is created using the Client(...) constructor of the Javascript Stomp class. This method takes up to three parameters, being the host, port and secure flag of the server to connect to. Creating the client does not connect it. The client is contained in a file named stomp.js, which can be served directly from the Stomplet server port, by requesting /stomp.js. When the STOMP client is loaded in this fashion into your HTML page, the Client() constructor is pre-configured with the host, port and secure flag for the same server. See Section 9.5.2, “Injecting the endpoint URL” for details on retrieving the endpoint variable used in the example below.

// Load the client from the STOMP server
<script src="http://<%= endpoint.host %>:<%= endpoint.port %>/stomp.js"></script>

<script type="text/javascript">
  // To use the preconfigured client provided by the server.
  client = new Stomp.Client(); 

  // To specify the host, port and secure flag explicitly
  client = new Stomp.Client( "somehost.com", 8676, true );

The Stilts distribution also includes JRuby-based clients and Java clients appropriate for communicating with the TorqueBox STOMP service. While STOMP is offered over WebSockets, the same service, on the same port (8675) provides bare STOMP also, for clients not requiring a WebSockets transport. The JRuby and Java clients can seamlessly communicate with the TorqueBox STOMP server using either TCP/IP, or WebSockets as the underlying transport.

If the web container is configured to provide an HTTPS/SSL connector (see SSL Configuration How-To), then a matching secure connector for WebSockets will be provisioned. By default, the secure connector runs on port 8676. WebSocket implementations in browsers do not typically provide a method for accepting untrusted SSL certificates, so it is necessary to first ensure that any self-signed certificate is designated as trusted by the browser before attempting to initiate a secure WebSocket connection. To make a secure connection, clients should use the wss:// scheme instead of simply ws:// in their connection URLs.

Additionally, the secure connector can accept pure-STOMP client connections (not using WebSockets), if TLS is enabled on the client.

TorqueBox uses the Stilts project to provide the WebSockets and STOMP stack. The Stilts project also defines the Stomplet API. Additional clients are available directly from the Stilts project. Rest assured, Stilts is written by the same people who write TorqueBox.