JBoss.orgCommunity Documentation

Chapter 4. Web Applications

4.1. Performance
4.2. Deployment
4.3. Clustering
4.4. Sessions
4.5. Caching
4.5.1. Clustering Modes
4.5.2. ActiveSupport::Cache::TorqueBoxStore options
4.6. Ruby Web Frameworks
4.6.1. Rack
4.6.2. Ruby on Rails
4.6.3. Sinatra

TorqueBox supports any and all Rack-based web application frameworks, including Ruby On Rails and Sinatra, among others. TorqueBox aims to be unobtrusive, requiring no unusual packaging of your app (e.g. no war files), and unless it depends on obscure native gems, no modifications whatsoever.

So why deploy your Ruby web app on TorqueBox? Because you get cool enterprisey features that every non-trivial app will need eventually if it's successful at all. Let's go over a few.

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 5, Application Deployment.

Clustering TorqueBox nodes is trivially easy:

 $ $JBOSS_HOME/bin/run.sh -c all 

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.

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.

TorqueBox provides an implementation of the Rails 3.x ActiveSupport::Cache::Store that exposes your application to the sexy Infinispan data grid.

Backed by Infinispan, ActiveSupport::Cache::TorqueBoxStore supports all the options of the existing Rails implementations, including the advanced features of MemCacheStore, along with a few more to control how data replication occurs amongst the nodes in a cluster.

Although it does depend on the ActiveSupport Rails 3 gem, it may be used in any Rack-based application or any TorqueBox service, task or job that requires sophisticated caching.

TorqueBox aims to provide complete Ruby Rack compatibility. Please refer to the Rack specification at http://rack.rubyforge.org/doc/SPEC.html for more information.

Applications implemented by the user must simply provide an object implementing a single-argument method in the form of call(env).


Ruby-on-Rails (also referred to as "RoR" or "Rails") is one of the most popular Model-View-Controller (MVC) frameworks for the Ruby language. It was originally created by David Heinemeier Hansson at 37signals during the course of building many actual Ruby applications for their consulting business.

Rails has straight-forward components representing models, views, and controllers. The framework as a whole values convention over configuration. It has been described as "opinionated software" in that many decisions have been taken away from the end-user.

It is exactly the opinionated nature of Rails that allows it to be considered a simple and agile framework for quickly building web-based applications. Additionally, since Ruby is an interpreted language instead of compiled, the assets of an application can be edited quickly, with the results being immediately available. In most cases, the application does not need to be restarted to see changes in models, views or controllers reflected.

While TorqueBox is 100% compatible with Ruby-on-Rails, there are a few steps that must be taken to ensure success. The biggest issues to contend with involve database access and native gems. The distribution includes a Rails application template to make the creation or adaptation of a codebase to TorqueBox easier.

ActiveRecord applications deployed on TorqueBox benefit from using the Java-based JDBC database drivers. These drivers are provided as a handful of gems which you may include into your application through config/environment.rb or a Gemfile. For more information on database connectivity wihtin the TorqueBox environment, please see Chapter 12, Database Connectivity.

Rails 2.x

You simply must reference the activerecord-jdbc-adapter from your environment.rb within the Rails::Initializer.run block.

Rails::Initializer.run do |config|

  config.gem "activerecord-jdbc-adapter",
             :require=>'jdbc_adapter'

end
          

All databases will require inclusion of the activerecord-jdbc-adapter. No other gems need to be required or loaded, since ActiveRecord will perform further discovery on its own.

Rails 3.x

Rails 3 uses bundler to manage the dependencies of your application. To specify the requirement of the activerecord-jdbc-adapter with Rails 3, simple add it to your Gemfile. Additionally, any specific JDBC driver your application will require should be indicated.

gem 'activerecord-jdbc-adapter'
gem 'jdbc-sqlite3'

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.