JBoss.orgCommunity Documentation

Chapter 9. STOMP & WebSockets on TorqueBox

9.1. Overview
9.1.1. What are 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. Rack middleware to provide the Javascript client
9.5.3. Injecting the endpoint URL
9.6. Other Clients (without WebSockets)
9.7. 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.

STOMP supports the notion of virtuals, 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 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 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.

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.