torquebox tutorial jbossIn this tutorial we will show how to develop a Ruby on Rails application on JBoss AS using TorqueBox project in just 10 steps!



Before diving into this tutorial we would need some basic definitions:

Surely some of you have hear about Ruby programming language which is an object oriented dynamic language very popular among Linux users.

Ruby on Rails is a MVC framework developed in Ruby for delivering quickly web applications.

JRuby is a fast, compliant implementation of the Ruby language upon the Java Virtual Machine. Pure Ruby applications run un-modified within the JRuby interpreter.

All these three components, combine into Torquebox which provides an all-in-one environment to run Ruby / RubyonRails applications on the top of JBoss AS

Step 1:  Installing Torquebox
Prerequisite: you need a JDK 1.6 in order to run Torquebox

Download Torquebox from here and extract in a folder.

Step 2:  Set up some system environment variables 
Supposing you installed Torquebox into C:\torquebox-1.0.0

export TORQUEBOX_HOME=C:\torquebox-1.0.0

Then add to your PATH environment variable jruby bin commands:

Step 3: Install rails libraries 

Ruby libraries are distributed as gem packages. A gem libraries contains the package information along with files to install.

So we will use the “gem” shell command to install the basic rails libraries:

C:\torquebox-1.0.0>gem install rails
Fetching: activesupport-3.0.7.gem (100%)
Fetching: builder-2.1.2.gem (100%)
Fetching: i18n-0.5.0.gem (100%)
Fetching: activemodel-3.0.7.gem (100%)
Fetching: rack-1.2.2.gem (100%)
Fetching: rack-test-0.5.7.gem (100%)
23 gems installed

Installation hack: If you are running behind a proxy you should use:
gem install -p http://<proxy-url> rails
Windows users should use the HTTP_PROXY environment variable
SET HTTP_PROXY=http://proxy:80

Step 4:  Install Rake support 

TorqueBox includes a support package which includes Rake tasks which assist in the deployment to and undeployment from an instance of the TorqueBox Server. Install it using gem utility:

C:\torquebox-1.0.0>gem install torquebox-rake-support
Fetching: torquebox-rake-support-1.0.0.gem (100%)
Successfully installed torquebox-rake-support-1.0.0
1 gem installed

Step 5:  Create a new Rails application 


Applications can be created using the rails utility which provides a skeleton for a basic MVC application. With the following code we will create a new web application named "example"

C:\torquebox-1.0.0\rails new example

Step 6: Install a JDBC adapter for your application 

There are several ways to connect a RubyOnRails application to a database. You can install native adapters for databases like MySQL, Postgres. However for Java users, the simplest approach is installing JDBC adapters which enables your Ruby on Rails application to access database servers that provide JDBC 3.0 compliant drivers.

For our purpose we will use a mysql JDBC adapter

C:\torquebox-1.0.0>gem install activerecord-jdbcmysql-adapter
Fetching: jdbc-mysql-5.1.13.gem (100%)
Fetching: activerecord-jdbcmysql-adapter-1.1.1.gem (100%)
Successfully installed jdbc-mysql-5.1.13
Successfully installed activerecord-jdbcmysql-adapter-1.1.1
2 gems installed

Step 7: Customize your application 

Move into the “example” folder and open the Rakefile file which contains the Rake configuration.
Add the following line:

require 'torquebox-rake-support'

In the same folder, open the Gemfile file and add the following:

gem 'activerecord-jdbcmysql-adapter'

Finally open the config/database.yml file which contains the database configuration.
Here we configure RubyonRails to connect to a MySQL instance running on the same host
-------------------database file
adapter: jdbcmysql
encoding: utf8
database: rubyonrails
pool: 5
username: root
password: admin

Now Let's move to MySQL shell and create an empty database named rubyonrails:

mysql> create database rubyonrails;
Query OK, 1 row affected (0.00 sec)

Step 8: Create your first application using scaffold 

Rails scaffolding is a quick way to generate some of the major pieces of an application. If you want to create the models, views, and controllers for a new resource in a single operation, scaffolding is the tool for the job.




Let's see what it can do for us.


We will create a sample "Music" application which store information about music tracks.

Issue the following command:

C:\torquebox-1.0.0\example>rails generate scaffold Music title:string description:text price:decimal
invoke  active_record
create    db/migrate/20110510184902_create_musics.rb
create    app/models/music.rb
invoke    test_unit
create      test/unit/music_test.rb
create      test/fixtures/musics.yml
route  resources :musics
invoke  scaffold_controller
create    app/controllers/musics_controller.rb
invoke    erb
create      app/views/musics
create      app/views/musics/index.html.erb
create      app/views/musics/edit.html.erb
create      app/views/musics/show.html.erb
create      app/views/musics/new.html.erb
create      app/views/musics/_form.html.erb
invoke    test_unit
create      test/functional/musics_controller_test.rb
invoke    helper
create      app/helpers/musics_helper.rb
invoke      test_unit
create        test/unit/helpers/musics_helper_test.rb
invoke  stylesheets
identical    public/stylesheets/scaffold.css

As you can see, the scaffold utility has created for you a set of directories which contain the basics of a MVC application which stores data in the music table. Following here is the explorer view of the example folder:

torquebox tutorial jboss jruby

The most interesting part is inside the app folder which contains:


  • a model where persistence information is stored (It's the equivalent of JPA)
  • a controller which redirects the views using its logic (It's the equivalent of the Servlet Controller)
  • a view which contains the pages which are displayed to the user (It's the equivalent of the JSPs)

Step 9: Reverse engineer to the database 

Now, the last step is synchronizing the model with the database. The following command will create the required table "musics" on mysql:

C:\torquebox-1.0.0\example>rake db:migrate
(in C:/torquebox-1.0.0/example)
==  CreateMusics: migrating ===================================================
-- create_table(:musics)
-> 0.0790s
-> 0 rows
==  CreateMusics: migrated (0.0790s) ==========================================

Step 10: Deploy your application 

C:\torquebox-1.0.0\example>rake torquebox:deploy['/example']
(in C:/torquebox-1.0.0/example)
TorqueBox Server OK: C:/torquebox-1.0.0/jboss/server/default
Deployed: example-knob.yml
into: C:/torquebox-1.0.0/apps

Good! your application is finally completed!
Now start the JBoss AS which ships in the C:/torquebox-1.0.0/jboss folder.

If you point the browser to the application's home page you will see RoR welcome page:
ruby on rails jruby torquebox tutorial

Now point the browser to the musics folder :




torquebox tutorial jboss ruby on rails


An empty list will appear. Let's add something to it, by clicking on the "New Music" link.

You will be redirected to the view that handles form data insert:

ruby on rails jruby tutorial

torquebox tutorial ruby on rails jboss

Once added the controller will redirect you to the list view which shows your record inserted:

ruby on rails jruby torquebox tutorial
Now you're done with it. You can experiment more about Ruby On Rails and Torquebox looking at the framework home page: