TorqueBox runs on JRuby, one of the fastest Ruby interpreters available. Because JRuby runs on the Java Virtual Machine, your app runs on real OS threads, so if your app supports multi-threaded invocations, you will make the most of your hardware resources.

Of course, running on the JVM has a drawback: "native" gems that rely upon machine-specific compiled code do not function with JRuby and TorqueBox. You must replace these gems with pure-Ruby or pure-Java implementations. Some native gems using FFI are usable within TorqueBox. Fortunately, gems that won't run on JRuby are becoming more and more rare.

Most successful web apps evolve to the point that passively responding to HTTP requests is not enough. Before you know it, you may need background processes, scheduled jobs, messaging, and active daemons all in support of your web app.

With TorqueBox these things are an integral part of your app and as such, they share its life cycle. When your application is deployed under TorqueBox, so are your scheduled jobs, background tasks, services, etc. It's simply a matter of editing a single torquebox.yml configuration file within your app. This will make your operations staff very happy!

For more details, please see Chapter 4, TorqueBox Application Deployment.

Clustering nodes is trivially easy (replace 1.2.3.4 with a real IP address):

 $ $JBOSS_HOME/bin/standalone.sh --server-config=standalone-ha.xml -b 1.2.3.4 

Or, if using the torquebox-server gem:

 $ torquebox run --clustered -b 1.2.3.4 

And when those nodes are behind the JBoss mod_cluster Apache module, you get automatic, dynamic configuration of workers, server-side load factor calculation, and fine-grained application lifecycle control.

But even without mod_cluster, TorqueBox clustering provides automatic web session replication and distributed caching, not to mention automatic load-balancing of message delivery, enabling smart distribution of any background processes spawned by your web app.

For more details, please see Chapter 21, TorqueBox Production Setup.

Ruby web apps are often deployed individually, without respect to hostnames or context-path. Running under TorqueBox, however, you may host several apps under a single host, or multiple apps under different hostnames.

In a YAML configuration, the web settings grouped under the web key. For the DSL, they are grouped within the web block.

web:
  rackup: alternative/path/to/my_config.ru
  context: /app-one
  static: public
  host: www.host-one.com

TorqueBox.configure do
  web do
    rackup "alternative/path/to/my_config.ru"
    context "/app-one"
    static "public"
    host "www.host-one.com"
  end
end

By using the TorqueBox application-server-based session store, your application gets the benefits of clusterable sessions without having to setup and maintain a database. When clustered, session state is automatically replicated throughout an Infinispan data grid.

Additionally, by using the TorqueBox session store, your application can communicate between both the Java and Ruby sides through the HTTP session. Where possible, elemental scalar attributes of the Ruby session are synchronized to similar attributes in the Java session, and vice-versa.

For complex objects, they are retained in a Ruby hash, and serialized as a blob into a single attribute of the Java session.

When copying between the Ruby and Java sessions, attributes will be retained under symbol keys in the ruby session, and string keys in the Java session. The supported scalar types are numerics, strings, booleans and nil.

How you enable the TorqueBox session store varies based on the web framework used. For Rack applications, just add use TorqueBox::Session::ServletStore to your config.ru. For specific examples in Rails and Sinatra applications, see Section 6.8.4, “Rails Sessions Configuration” and Section 6.9.1, “Sinatra Sessions Configuration”.

The session timeout can be configured in your TorqueBox deployment descriptor(s). The general format for the session timeout value is numeric with an optional unit of measure, where ms = milliseconds, s = seconds, m = minutes and h = hours. If no unit of measure is provided, minutes will be assumed. Ex: session-timeout: 10 h will set the session timeout to 10 hours.

...
  
web:
  host: foobar.com
  context: /tacos
  session-timeout: 10

TorqueBox provides an implementation of the Rails 3.x ActiveSupport::Cache::Store that exposes your application to the sexy Infinispan data grid. Additionally, TorqueBox provides similar functionality for Sinatra sessions. See specific configuration options in the Ruby Web Frameworks sections below. To learn more about ActiveSupport::Cache::Store, the Infinispan cache, and the many other ways it is used by TorqueBox and can be used by you, please see Chapter 7, TorqueBox Caching.

Sinatra is a very simple DSL for creating web applications. And all the TorqueBox features available to Rails apps, e.g. clustering, session replication, and caching, will work for Sinatra app just as well.

require 'sinatra''
require 'torquebox'

class SinatraSessions < Sinatra::Base

  use TorqueBox::Session::ServletStore

  get '/foo' do
    session[:message] = 'Hello World!'
    redirect '/bar'
  end

  get '/bar' do
    session[:message]   # => 'Hello World!'
  end

end

require 'active_support/cache/torque_box_store'
class SinatraCache < Sinatra::Base
  set :cache, ActiveSupport::Cache::TorqueBoxStore.new
end

set :cache, ActiveSupport::Cache::TorqueBoxStore.new(:mode => :distributed, :sync => true)

COUNTERS = ActiveSupport::Cache::TorqueBoxStore.new(:name => 'counters', 
                                                    :mode => :replicated, 
                                                    :sync => true)