JBoss.orgCommunity Documentation

Chapter 2. Adding TorqueBox Features

2.1. TorqueBox Rails Template
2.2. Running Tasks in the Background
2.3. Scheduled Jobs
2.4. Long-Running Services
2.5. Message Processors

This chapter builds upon the simple Rails application we created in Chapter 1, First Steps by modifying it to take advantage of TorqueBox features.

TorqueBox ships with a Rails template that we can use to automatically add torquebox to the Gemfile, convert the session store to the optional TorqueBox clustered session storage, setup all ActiveRecord objects to have TorqueBox::Backgroundable methods available, and add some TorqueBox-specific Rake tasks.

$ cd ~/torquebox_examples/rails_example
$ torquebox rails
       apply  .../torquebox-3.2.0/share/rails/template.rb
     gemfile    torquebox (3.2.0)
      remove    config/initializers/session_store.rb
 initializer    session_store.rb
 initializer    active_record_backgroundable.rb
    rakefile    torquebox.rake

To illustrate how TorqueBox makes it effortless to run long-running tasks in the background, let's first add a long-running task to our Post model. After each Post is created, lets publish a message to our favorite social network linking to that post. For simplicitly we'll just log a message and sleep for a few seconds to simulate the publish.


Start TorqueBox if it isn't already running via torquebox run (Windows users remember to use echo Y | jruby -S torquebox run), navigate to
http://localhost:8080/posts/, create a new post, and observe the output from the TorqueBox console.

09:11:19,746 INFO  [stdout] (http-localhost/127.0.0.1:8080-1) Publishing 'Chunky Bacon Fever' to our favorite social network
09:11:24,747 INFO  [stdout] (http-localhost/127.0.0.1:8080-1) Post published

As you can see, it took 5 seconds to publish the post and during that five seconds the browser was waiting on a response from the server. There's no reason the browser needs to wait until the post is published, so let's see how easy it is to convert the publish_to_social_network method to run in the background.


Create a new post and you'll see that the browser returns immediately and in the TorqueBox console the messaging runtime will spin up (since TorqueBox::Backgroundable uses messaging and the first message we send starts the messaging runtime pool) and publish the post to our favorite social network in the background.

TorqueBox also has built-in support for scheduled jobs (like Cron or Windows Scheduler) but in a cross-platform way. To see how scheduled jobs work, let's create a job that logs the number of posts in our database every 10 seconds. To do this create a PostCounter class in the app/jobs directory created for us by the TorqueBox Rails template earlier.


We also have to tell TorqueBox about this new job and when to run it. To do that, edit the config/torquebox.yml created for us by the TorqueBox Rails template to have the contents below.


Since we had to make a change to config/torquebox.yml, we need to restart TorqueBox for the job to start running. After restarting TorqueBox you should see output like below every 10 seconds.

09:45:30,029 INFO  [stdout] (JobScheduler$rails_example-knob.yml_Worker-2) 2 posts in the database

TorqueBox supports the notion of long-running services that get started when the application is deployed and stopped when the application is undeployed. This could be useful to connect a client to a streaming API service (like that provided by some social networks), monitor a resource for changes and take some action, or many other things. As an example, we'll create a service that pretends to connect to a social network and submit post ideas to a queue for later processing.


Just like with our scheduled job, we need to tell TorqueBox about this new service and the message queue it uses.


Restart TorqueBox and you should see the service starting in the logs.

10:43:56,316 INFO  [org.torquebox.core.runtime] (MSC service thread 1-7) Created ruby runtime (ruby_version: RUBY1_8, compile_mode: JIT, app: rails_example, context: services) in 17.73s
10:43:56,325 INFO  [stdout] (MSC service thread 1-5) ******** Starting PostIdeaGrabber ********

We have a long-running service placing messages on a queue but now we need something to consume those messages and do something with them. TorqueBox has a feature designed specifically for this purpose - message processors. We'll create a message processor to randomly choose some of the ideas and create new posts from them.


As usual we need to edit config/torquebox.yml so TorqueBox knows how to wire up this new message processor.


Restart TorqueBox and you should see new posts being created from the random ideas.

11:10:31,891 INFO  [stdout] (Thread-2 (HornetQ-client-global-threads-9512807)) Creating new post from idea Random idea 66

Congratulations! You now have an application that uses many of the features of TorqueBox. For detailed documentation on TorqueBox, look for the User Manual in the same location you found this Getting Started Guide.