How To Enable STOMP Messaging Protocol in JBoss AS7

May 3, 2012

Since I have started working on AS7, I have been pleasantly surprised by its ease of configuration. My favorite thing about AS7 (after its fast boot time) is that its configuration is located into a single file.

If you need messaging with AS7, you can use its standalone/configuration/standalone-full.xml configuration file which contains a messaging stack built on top of HornetQ. The whole messaging stack is configured in its messaging <subsystem>:

<subsystem xmlns="urn:jboss:domain:messaging:1.2">
    <hornetq-server>
        ...
    <hornetq-server>
</subsystem>

By default, AS7 only supports JMS as its messaging protocol. If your applications needs to send and receive messages from other platforms or languages than Java, JMS is not an option and you need to enable STOMP too.

Fortunately, adding STOMP support to AS7 is dead easy:

add an HornetQ acceptor to let AS7 accept STOMP frames on a dedicated socket
configure this socket to bind to default STOMP port

To add an HornetQ acceptor for STOMP, edit the standalone/configuration/standalone-full.xml file and add these lines in the <acceptors> section of <hornetq-server>:

<netty-acceptor name="stomp-acceptor" socket-binding="messaging-stomp">
    <param key="protocol" value="stomp"/>
</netty-acceptor>

The stomp-acceptor is expected to receive STOMP frames on the socket binding named messaging-stomp.

At the end of the same standalone/configuration/standalone-full.xml file, add a <socket-binding> to the <socket-binding-group name="standard-sockets"> section:

<socket-binding name="messaging-stomp" port="61613"/>

61613 is the default port for Stomp brokers.

With these 2 changes, we can now start JBoss AS7 with STOMP enabled:

$ ./bin/standalone.sh -c standalone-full.xml
...
14:14:38,027 INFO  [org.hornetq.core.remoting.impl.netty.NettyAcceptor] (MSC service thread 1-2) Started Netty Acceptor version 3.2.5.Final-a96d88c 127.0.0.1:61613 for STOMP protocol
...
14:14:38,263 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015874: JBoss AS 7.1.2.Final-SNAPSHOT "Brontes" started in 2749ms - Started 163 of 251 services (87 services are passive or on-demand)

Before sending and receiving messages from a STOM client, we also need to configure 2 things for the AS7:

add an user (AS7 is secured by default and we must explicitely add an application user to connect to it)
add a JMS queue to send and receive messages on it

To add an user, we use the add-user.sh tool:

$ ./bin/add-user.sh

What type of user do you wish to add?
 a) Management User (mgmt-users.properties)
 b) Application User (application-users.properties)
(a): b

Enter the details of the new user to add.
Realm (ApplicationRealm) : [type enter]
Username : myuser
Password : mypassword
Re-enter Password : mypassword
What roles do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[  ]: guest
About to add user 'myuser' for realm 'ApplicationRealm'
Is this correct yes/no? yes
Added user 'myuser' to file '[...]/standalone/configuration/application-users.properties'
Added user 'myuser' to file '[...]/domain/configuration/application-users.properties'
Added user 'myuser' with roles guest to file '[...]/standalone/configuration/application-roles.properties'
Added user 'myuser' with roles guest to file '[...]/domain/configuration/application-roles.properties'

Finally, to add a JMS queue, we will use JBoss CLI tool:

$ ./bin/jboss-cli.sh
You are disconnected at the moment. Type 'connect' to connect to the server or 'help' for the list of supported commands.
[disconnected /] connect
[standalone@localhost:9999 /] /subsystem=messaging/hornetq-server=default/jms-queue=test/:add(entries=["/java:jboss:exported/queue/test"])
{"outcome" => "success"}

We now have configured an user and a JMS queue. Let's send and receive STOMP messages using Ruby and its stomp gem (installed with sudo gem install stomp):

require 'rubygems'
require 'stomp'

client = Stomp::Client.new "myuser", "mypassword", "localhost", 61613

client.publish 'jms.queue.test', 'Hello, STOMP on AS7!'

client.subscribe "jms.queue.test" do |msg|
  p "received: #{msg.body}"
end

And it will output the expected message:

received: Hello, STOMP on AS7!

Conclusion

add a <netty-acceptor> with a stomp protocol param
add a <socket-binding> for default 61613 STOMP port
configure users and JMS queues by following AS7 messaging documentation

Using STOMP with AS7 is simple to setup (4 lines to add to its configuration file) and allow any languages and platforms to send and receive messages to your application hosted in AS7.