These notes record all that was involved in migrating 3 apps from TorqueBox 1.1.1 to 2.0.3. Two of those apps were Rails 2 apps, and one was a Java EE and JSF app. It’s worth noting from the start that most of the complexity involved had to do with the Java EE app, and using long-lived messaging destinations. If your setup is all Rails/Rack apps with “embedded” destinations then you will be able to skip most of the steps below.

All instructions below assume use of the “standalone” configuration.

Running TorqueBox

Instructions as per the manual, with the following notes:

Bind to specific/all IP addresses: If you’re used to passing the “-b” parameter to bind to a specific IP address, you can either:

• pass the bind address as a system property on startup like so: ./standalone.sh -Djboss.bind.address=0.0.0.0
• or set the option as an environment variable like: export JAVA_OPTS=”-Djboss.bind.address=0.0.0.0″
• or make a permanent change to an XML config file like this.

Deployment

In TorqueBox 2, $TORQUEBOX_HOME/apps is so last season. Everything gets deployed to $JBOSS_HOME/standalone/deployments

Wars seem to deploy just by copying them into $JBOSS_HOME/standalone/deployments directory.

For other deployment descriptors, do this:

• cp the torquebox.yml or myapp-knob.yml file into $JBOSS_HOME/standalone/deployments
• touch $JBOSS_HOME/standalone/deployments/myapp-knob.yml.dodeploy

^ Note: I also got a strange error whereby when I used torquebox deploy myapp-knob.yml, the app server tried (and obviously failed) to unzip the yaml file). However the above manual deployment worked for me.

Project Configuration

Rails

Had to upgrade from Rails 2.3.11 to 2.3.14 to avoid this bug due to a later version of rubygems being used.

Data Sources

In TorqueBox 1 I used a *-ds.xml datasource descriptor for my database so I could access it from a pure Java EE app (so you can skip this step if you only deploy Ruby/Rack apps). These are no longer compatible with TorqueBox 2. Instead I had to do the following steps:

• Install a MySQL driver as a module and register it as a driver as per the instructions here, but don’t follow the “Add the Datasource” section because we’ll do that differently in the next step.
• Instead of copying a *-ds.xml file, run a JBoss CLI command such as this: $JBOSS_HOME/bin/jboss-cli.sh -c “data-source add –name=myapp-ds –connection-url=jdbc:mysql://db.myapp.net:3306/myapp –user-name=myapuser –password=secret –jndi-name=java:/myapp-ds –driver-name=com.mysql”
• In the above step, the “com.mysql” at the end has to match the name you gave your driver.
• Then follow up with this to enable the datasource: $JBOSS_HOME/bin/jboss-cli.sh -c “data-source enable –name=myapp-ds”

Messaging

Configuration

Filters / Selectors

If you’ve used filters for your message consumers, you’ll need to update your relevant yaml file (torquebox.yml or *-knob.yml) to change filter: to selector: like this.

Destination Names

For whatever reason~, I had named my queues and topics like “com.myapp.component.function”, which seemingly resulted in my consumers being unable to find them in TorqueBox 2. I switched to using “/com/myapp/component/function” as per the examples in the TorqueBox docs and things worked again.

~ Looks like it was to make _HQ_ORIG_ADDRESS based message selectors prettier, because they started with “jms.queue.” More on this later.

Durable Topic Subscriptions

Durable topic subscribers in torquebox.yml or *-knob.yml seem to require an explicit client_id in TorqueBox 2 (I think they were defaulted in TorqueBox 1). Related doc.

Long Lived Destinations

If you deploy long-lived queues and topics you might need to:

• change the name of eg: myapp-topics.yml to myapp-topics-knob.yml.
• update the file format slightly so your destinations are listed under a “topics:” or “queues:” parent (this was optional in TorqueBox 1).

Dead Letter Queue / Expiry Queue

If you use the Dead Letter Queue (DLQ) or Expiry Queue, these are apparently not created by default any more. To create them, run the following commands from a terminal or script:

• $JBOSS_HOME/bin/jboss-cli.sh -c “jms-queue add –queue-address=DLQ –entries=DLQ –durable=true”
• $JBOSS_HOME/bin/jboss-cli.sh -c “jms-queue add –queue-address=ExpiryQueue –entries=ExpiryQueue –durable=true”

If you’ve renamed your queues and topics from eg: com.myap.func to /com/myapp/func and your DLQ consumers are filtered based on the original address, the corresponding selector would change from

selector: "_HQ_ORIG_ADDRESS = 'jms.topic.com.myap.func'"

to

selector: "_HQ_ORIG_ADDRESS = 'jms.topic./com/myapp/func'"

(the key point being that you keep both the dot at the end of jms.queue. and the leading slash of your destination name, which looks kind of weird but works).

Also, instead of subscribing to /queue/DLQ, you simply subscribe to DLQ. Here’s a full example:

messaging:
    DLQ:
        FileReadyDlqHandler:
            selector: "_HQ_ORIG_ADDRESS = 'jms.topic./com/myapp/file_ready'"

Messaging Destination Deployment Gotchyas

Hornet-Q XML Fragments

Because I have a Java EE app as well, I used to deploy myapp-jms.xml files containing the long-lived destinations for that app. In TorqueBox 2/JBoss AS 7.1 using these files is apparently only recommended for development. The file format has changed and needs updating. According to this other helpful page the changes look like this. Then you can deploy by copying into the $JBOSS_HOME/standalone/deployments directory as per usual (no need for a .dodeploy).

The myapp-hornetq-configuration.xml file seemed to deploy without errors, but it’s difficult to find any evidence in the logs or console that the “address-settings” and “security-settings” in that file were actually applied. Remains to be seen at this stage.

JBoss Console

If you deploy your destinations in torquebox.yml or *-knob.yml, or as an XML fragment, they won’t appear in the JBoss Console’s JMS Metrics view (though they will appear in Backstage). This is a known issue. If your destinations are long-lived, you could use the JBoss CLI as a workaround, as described in the following section.

JBoss AS CLI/Script Based Deployment of Long-Lived Destinations

You can use CLI commands similar to those used above for the DLQ to deploy your long-lived destinations. Be aware that the defaults for durability are not necessarily the same so it may pay to be more explicit. Also this changed my installation/deployment strategy from “put all files in place, then start server” to the opposite where I have to start the server first.

Useful Resources:

• JBoss AS 7 Admin Guide
• JBoss AS 5/6 to 7 Migration Guide