This article covers the following topics:

• Packaging our RoR project into a WAR file
• Deploying that WAR file on Tomcat

Please note that this article only covers deploying Jruby-On-Rails applications in a non-Production (i.e. non-public-facing) environment. This example is designed to allow a developer to deploy a Jruby-On-Rails application on her workstation. If you want to install Tomcat in a public-facing environment, then you need a different tutorial

Tomcat Installation

Tomcat was my choice for the following reasons:

1. It’s very easy to install. Just unpack it and go (if you already have the proper version of Java installed).
2. It’s very easy to administer on my netbook (which is where I’m learning about RoR and Jruby).
3. It’s relatively lightweight compared to JBoss or WebLogic.
4. It’s very easy to deploy war files. Just drop them in $TOMCAT_HOME/webapps, restart Tomcat, and you’re up-and-running.

So let’s install Tomcat:

$ cd /tmp
$ wget http://apache.opensourceresources.org/tomcat/tomcat-6/v6.0.24/bin/apache-tomcat-6.0.24.tar.gz
$ tar xvfz apache-tomcat-6.0.24.tar.gz
$ sudo cp -r apache-tomcat-6.0.24 /opt
# please replace tom:tom with your user and group
$ sudo chown -R tom:tom /opt/apache-tomcat-6.0.24

Assuming that you have the minimum version of Java (I’m using 1.6.0_15 from the sun-java6-jdk Ubuntu package), you can start Tomcat like this:

$ cd /opt/apache-tomcat-6.0.24/bin
$ ./startup.sh
Using CATALINA_BASE:   /opt/apache-tomcat-6.0.24
Using CATALINA_HOME:   /opt/apache-tomcat-6.0.24
Using CATALINA_TMPDIR: /opt/apache-tomcat-6.0.24/temp
Using JRE_HOME:        /usr/lib/jvm/java-6-sun
Using CLASSPATH:       /opt/apache-tomcat-6.0.24/bin/bootstrap.jar

Great, now you can test your installation by pointing your browser at the following url:

• http://localhost:8080

You can also shut the server down using the shutdown.sh script from the same directory.

Packaging Depot In A WAR File

Now that Tomcat is up-and-running, let’s build our WAR file. If you haven’t already installed warbler, then you can do so with the following command:

$ jruby -S gem install warbler

Warbler is a gem that makes it very easy to package RoR applications as WAR files. However, before we can use it, we need to tell it that we’re using the activerecord-jdbcsqlite3-adapter driver. Here’s how you do that:

1. Run the warble config command from the root directory of your project. This command will create the config/warble.rb file.
2. Add the following line to the newly-created config/warble.rb file:
   1. config.gems << "activerecord-jdbcsqlite3-adapter"

That’s it! Now you can build your war file:

$ warble

In a minute or so, you should see a file named depot-jruby.war in the root of your project directory. If you need to rebuild you war file, then simply execute the following command:

$ warble war:clean && warble

Deploying On Tomcat

Now we can finally deploy the WAR file to our Tomcat instance. Here’s how I do it on my machine:

$ cd /opt/apache-tomcat-6.0.24
$ cp /home/tom/Dev/ruby/depot-jruby/depot-jruby.war ./webapps
$ ./bin/shutdown.sh && ./bin/startup.sh

Then you can test your application by visiting the following URL:

• http://localhost:8080/depot-jruby/store

Conclusion

I know that I said this in my previous tutorial, but that was a lot easier than I thought it would be. It only took 3 simple steps, and the Tomcat installation step only needs to be done once.

I thought that it might be equally enlightening to “port” the Depot application to Jruby using the Jruby On Rails libraries. I had two basic milestones in mind:

1. Development & Testing – I wanted to be able to develop and test my application just like I did with CRuby, using tools such as mongrel and rake.
2. J2EE Deployment – The most popular process for deploying a Java-based application is to build a WAR file and then deploy it to a Java application server such as Tomcat (which was my choice). I wanted to be able to complete these steps with my RoR application.

The entire process was surprisingly easy. The first milestone, Development and Testing, is covered in this article. The J2EE Deployment milestone will be covered in a different blog article.

Development & Testing

Here are some simple steps that will have your application running with mongrel very quickly.

Please note that I am executing the steps below on a netbook running Ubuntu 9.10. These commands should work on most Linux distributions, however. Also, they should work with a few small adjustments on a Windows machine.

Prepping Your Project Directory

First, you’re not going to want to make these changes to your original version of the Depot code. You will probably want to create a copy of it that is designed to work with Jruby. Here’s how I did it on my machine:

$ cd /home/tom/Dev/ruby
$ cp -r depot depot-jruby

The location of your depot folder will probably be different on your machine, but I’m sure that you can make the necessary adjustments

Also, please note that it is a good idea to “freeze” your rails version now if you have not done so already. You can do this by executing the following command:

$ cd /home/tom/Dev/ruby/depot-jruby
$ jruby -S rake rails:freeze:edge RELEASE=2.2.2

Installing Jruby

Next, you’ll want to install Jruby. There’s a lot of ways of doing this, but this method worked pretty well on my development machine:

$ cd /tmp
$ wget http://jruby.kenai.com/downloads/1.4.0/jruby-bin-1.4.0.tar.gz
$ tar xvfz jruby-bin-1.4.0.tar.gz
$ sudo cp -r jruby-1.4.0 /opt
# please replace tom:tom with your user and group
$ sudo chown -R tom:tom /opt/jruby-1.4.0
$ sudo ln -s /opt/jruby-1.4.0 /opt/jruby

Then simply add /opt/jruby to your PATH, and see if you can execute jirb.

Installing Rails And Other Libraries

This process is just as easy using Jruby as it is using CRuby.

Install the gems using these commands:

$ jruby -S gem install rails --version 2.2.2
$ jruby -S gem install mongrel jruby-openssl jdbc-sqlite3

A few notes on those commands:

• Prepend the gem command with jruby -S to ensure that you are using the right version of the gem command. This also works with any other Jruby command, such as rake.
• Since the example uses the 2.2.2 version of Rails, we’re going to need it too.
• jdbc-sqlite3 is the Java version of the sqlite3 DB driver.
• The jruby-openssl package is nice to have regardless of what you’re installing with rubygems.

Making Depot Safe For JDBC

You can’t use the C-based database drivers with Jruby, but luckily, the Jruby developers have made it very easy to use the JDBC-based equivalents.

First, make sure that you are using version 0.9.2 of the activerecord-jdbc-adapter driver or higher. You can check this by executing the following command:

$ jruby -S gem list | grep activerecord-jdbc-adapter
activerecord-jdbc-adapter (0.9.2)

Next, execute the following command from the root directory of your project:

$ jruby script/generate jdbc
exists  config/initializers
create  config/initializers/jdbc.rb
create  lib/tasks
create  lib/tasks/jdbc.rake

That’s it! Your Depot application is now ready to use Jruby-on-Rails.

Please note that I did not modify my config/database.yml file or hack any part of the Rails libraries to make JDBC work. These steps used to be necessary, but the command listed above gives you a much easier and cleaner way of using JDBC. For more information, please check out this article:

• Fresh 0.9.2 activerecord-jdbc-adapter Release

Test

To test my work, I did the following:

• I ran the mongrel app server and executed some manual tests of the Depot web site. That worked well.
• I execute all of my tests using the rake test command. This also worked as well as it had with the CRuby version of my application.

Success! Now it would be nice to review all of the files that changed or were added. Since I checked my project into my git repository before making any changes, I can get the information that I need pretty easily:

$ git status
# branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       new file:   config/initializers/jdbc.rb
#       new file:   lib/tasks/jdbc.rake

That’s it! No code or config changes were necessary.

Conclusion

As you can see, it’s fairly easy to “port” the Depot application to use Java-based versions of mongrel, rails, and the other libraries from the Agile Development With Rails book. In my next article, I will take this application and deploy it on top of a Tomcat server.

I wanted to write my test script against a database manager that ran on my laptop, but I didn’t want to go through the hassle of installing and configuring Oracle or MySql. Also, I soon learned that a lot of Ruby database drivers don’t work with Jruby, so I needed a small, simple database that had a good JDBC driver. I ended up installing and configuring Apache Derby, and it worked out very well for me.

So anyways, here’s the script (jdbctest.rb):

require 'java'
require './derbyclient.jar'
require './derbytools.jar'

# This example assumes that you have the free DerbyDB software installed on
# your machine.  It also assumes that you are running it in "server" mode by
# executing the startNetworkServer.bat script.

# This is what I'm using instead of Class.forName("org.apache.derby.jdbc.ClientDriver").newInstance()
import 'org.apache.derby.jdbc.ClientDriver'

connString = "jdbc:derby://localhost:1527/MyDbTest"
conn = Java::JavaSql::DriverManager.getConnection(connString)

stmt = conn.createStatement

rs = stmt.executeQuery("select * from derbyDb")

while (rs.next) do
    puts "#{rs.getString("NUM")} -- #{rs.getString("ADDR")}"
end

rs.close
stmt.close
conn.close()

I then placed the jdbctest.rb script in a folder with the derbyclient.jar and derbytools.jar file, and then executed the script like this:

c:\Dev\jruby\somefolder>jruby .\jdbctest.rb
180 -- Grand Ave.
1910 -- Union St.

To make this script work, you need to do the following:

1. Install Derby using this tutorial: Step 1 – Install Software
   • This is a very simple task that took me all of 6 minutes after downloading the software.
2. Create the MyDbTest database and the derbyDB table using this tutorial: Step 2 – ij Basics
   • You should also populate this table using the SQL located under the Execute SQL Statements section.
3. Once you’ve created and queried your table using ij, start your Derby server using this tutorial: Step 4 – Derby Network Server
   • You should validate the server using ij. Please see the Test network server connection with ij section in the Step 4 tutorial for help.

Please note that this might seem like a lot of work, but it’s really very simple, especially when you compare it installing and configuring most relational database managers. It took me about 20 minutes from A to Z, and I had no prior experience with Derby.

That’s it! I hope that this tutorial helps a few other people who want to get started with Jruby and JDBC.

Background

I’m a middleware systems administrator for a living, and I often find that I need to write a script that has to interact with proprietary Java libraries. In the past, this meant writing a small Java program that would use the proprietary libraries, and then wrapping that program in a small shell script. This process was OK, but it did have its warts. For example, Java is a fairly verbose language. Going through all of the syntactic hoops just to write a simple program can be tedious.

A little over a year ago, I then discovered Groovy and Jruby. Both languages were very elegant, and I could see how they could both boost my scripting productivity dramatically. I therefore compared both languages for my scripting tasks, and, in the end, I determined that Groovy was just a better language. Here’s part of my rationale:

• A More Stable Interpreter – Jruby would often give extremely cryptic errors when you made a mistake, while Groovy did a much better job of pointing out any problems.
• A Compiler – At the time, Groovy had a compiler (groovyc) that use could use to compile your scripts into bytecode. This tool made it much easier for me to deploy Groovy code in my environment. Jruby has since introduced a similar tool, but it didn’t exist during my initial evaluation.

Now I’m on a new project, and we need to write a bunch of administrative scripts in a hurry. We have the same requirements as my old project, but just before I could dive into my Groovy interpreter, I found out that a lot of the Java developers on my team were ga-ga for Ruby. I therefore decided that it would be nice to evaluate both languages again, one year later. If Jruby is nearly as stable as Groovy for my needs, then it might be a good idea to start writing my scripts with it.

Evaluation

Before I could start my evaluation, I thought it might be a good idea to re-acquaint myself with Ruby. I read “Everyday Scripting With Ruby” a little over six months ago and thought that it was an excellent tutorial on both Ruby and agile scripting. I therefore decided to try running some of the examples in that book with Jruby to bring myself back up-to-speed.

In “Everyday Scripting With Ruby”, the first chapter encourages you to enter invalid code into irb, which is the Ruby interactive interpreter. This exercise shows you how to read the error messages returned by irb. Here’s the line of code:

 100 -= 43

And here’s what the latest-and-greatest (1.1.5) version of jirb (Jruby’s version of irb) returns when you enter that:

 irb(main):001:0> 100 -= 43
 SyntaxError: (irb):2: , unexpected tOP_ASGN

         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/workspace.rb:81:in `irb_binding'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/workspace.rb:53:in `eval'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/workspace.rb:81:in `evaluate'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/context.rb:219:in `evaluate'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:150:in `eval_input'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:259:in `signal_status'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:147:in `eval_input'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/ruby-lex.rb:244:in `each_top_level_statement'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/ruby-lex.rb:230:in `loop'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/ruby-lex.rb:230:in `each_top_level_statement'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/ruby-lex.rb:229:in `catch'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/ruby-lex.rb:229:in `each_top_level_statement'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:146:in `eval_input'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:70:in `start'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:69:in `catch'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:69:in `start'
         from E:\apps\jruby-1.1.5\bin\jirb:19Maybe IRB bug!!

Yikes. I’ve been reading Java stack traces for seven years, but I really have no idea what this error message is telling me. If I honestly thought that line of code should work, or was tired and trying to meet a deadline, this stack trace would be anything but helpful to me.

Just to compare things a bit, I tried to same line of code in the 1.5.6 version of groovysh, which is the interactive interpreter for Groovy:

 groovy:000> 100 -= 43
 ERROR org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed, groovysh_evaluate: 2:
 [100] is a constant expression, but it should be a variable expression at line:
 2 column: 5. File: groovysh_evaluate @ line 2, column 5.
 1 error

Ok, still a little confusing, but much easier to follow. Basically, it’s telling me that “100″ should be a variable of some type instead of a literal. That makes sense.

I thought this might be an anomaly, and I wanted to give Jruby another shot, so I tried executing the next “broken” line of code from the book in both jirb and groovysh:

 (1 + 3) * 2 + 1)

First, let’s try it in Jruby:

 irb(main):002:0> (1 + 3) * 2 + 1)
 SyntaxError: (irb):3: , unexpected tRPAREN

         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/workspace.rb:81:in `irb_binding'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/workspace.rb:53:in `eval'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/workspace.rb:81:in `evaluate'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/context.rb:219:in `evaluate'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:150:in `eval_input'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:259:in `signal_status'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:147:in `eval_input'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/ruby-lex.rb:244:in `each_top_level_statement'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/ruby-lex.rb:230:in `loop'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/ruby-lex.rb:230:in `each_top_level_statement'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/ruby-lex.rb:229:in `catch'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb/ruby-lex.rb:229:in `each_top_level_statement'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:146:in `eval_input'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:70:in `start'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:69:in `catch'
         from E:/apps/jruby-1.1.5/lib/ruby/1.8/irb.rb:69:in `start'
         from E:\apps\jruby-1.1.5\bin\jirb:19Maybe IRB bug!!

Ok, again, this is complete giberish. What the heck’s a tRPAREN? Ok, now let’s try it using groovysh:

 groovy:000> (1 + 3) * 2 + 1)
 ERROR org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed,
 groovysh_parse: 1: unexpected token: ) @ line 1, column 16.
     (1 + 3) * 2 + 1)
                    ^

Ok, this is exactly what I hoped to see. A nice, clear message telling me what I forgot and what it is associated with.

Shortest. Evaluation. Ever

You may not be saying that this is a weird way to evaluate a language. Well, it wasn’t my plan to evaluate Jruby by looking at its error messages, but it was all that I guess I needed. Here’s why error message quality is important to me:

1. Based on my experiences with numerous up-and-coming scripting languages, the quality of the error messages is proportional to the quality of the interpreter. If this assumption is true in this case, then the Groovy interpreter still appears to be more mature than the Jruby interpreter.
2. Other programmers won’t know what to do when they see one of the Jruby stack traces. Even if I was able to train myself to read the Jruby stack traces, I doubt that my co-workers would have the time or inclination to follow suit.

So, once again, when it comes to my unusual needs, Groovy wins the battle of stability and ease-of-use. Before I end this post, however, I would like to say a few good things about Jruby so that I don’t appear to be partisan:

• I’m really happy that Jruby finally has a tool that will compile your .rb files into .class files. This will make it much easier for me to deploy Jruby applications in my environment some day.
• Jruby seems to be improving at a rapid pace, and it has a lot of support from companies such as Sun. I think that it will be stable enough for my needs within a year or so.