This is a basic howto on deploying a JRuby on Rails application to Oracle Containers for Java EE (OC4J) Standalone.

Contents

• Prerequisites
• Installation
• Create a Rails 2.0 Application
• Packaging Rails app into WAR
• Deploy on OC4J Standalone
• Troubleshooting
• References

Prerequisites

• Windows 2000/XP / Linux
• Java 5
• JRuby 1.1RC3
• Rails 2.0/1.2
• activerecord-jdbc-adapter 0.8.0
• Oracle JDBC Driver
• Warbler
• Oracle Database 11gR1 / Oracle Database 10g XE
• Oracle Containers for J2EE (OC4J) 10gR3

Note: We used Rails 2.x in this guide, although there will be little changes in Rails 1.x

Installation

1. First download and install JDK 5, JRuby 1.1 and make sure you set $JAVA_HOME/bin and $JRUBY_HOME/bin in your $PATH variable.
   
   
2. Install Rails 2.0:
   
   

   sudo jruby -S gem install rails [-y]

   
   
3. Install activerecord-jdbc-adapter:
   
   

   sudo jruby -S gem install activerecord-jdbc-adapter

   
   
4. Download appropriate Oracle JDBC Driver jar file (ojdbc14.jar for DB 10g and ojdbc5.jar for DB 11g) and copy it into $JRUBY_HOME/lib.

Note: JRuby leverages JDBC to access various JDBC compliant database systems and Ruby-OCI8 can't work with JRuby because "Many Gems will work fine in JRuby however some Gems build native C libraries as part of their install process. These Gems will not work in JRuby unless the Gem has also provided a Java equivalent to the native library." as stated in the JRuby Wiki. The latest ActiveRecord JDBC Adapter (v0.8.0) only works with JRuby 1.1RC3 or future version.

Create a Rails 2.0 Application

Performing the following steps to create a simple Rails 2.0 application.

1. Create the app:
   
   

   jruby -S rails bookstore
   cd bookstore

   
   
2. Modify config/database.yml as any of the three forms below:
   
   

   development: adapter: jdbc driver: oracle.jdbc.driver.OracleDriver url:jdbc:oracle:thin:@<hostname>:<port>:<sid> username: railsuser password: railspasswd production: development

   development: adapter: oracle url:jdbc:oracle:thin:@<hostname>:<port>:<sid> username: railsuser password: railspasswd production: development

   development: adapter: oracle host: <hostname> port: 1521 (by default) database: <sid> username: railsuser password: railspasswd production: development

   We can use both the "jdbc" adapter or the "oracle" adapter as when using C Ruby, and set the production configuration the same as development configuration because when deployed Rails uses production configuration.
   
   In Rails 1.2, the jdbc adapter gem is not required by default by ActiveRecord. We need to add "jdbc" into %JRUBY_HOME%\lib\ruby\gems\1.8\gems\activerecord-x.y.z\lib\active_record.rb as below:
   
   

   unless defined?(RAILS_CONNECTION_ADAPTERS)
   

   RAILS_CONNECTION_ADAPTERS = %w( mysql postgresql sqlite firebird sqlserver db2 oracle sybase openbase frontbase jdbc)

   end

   
   Thus all Rails application can share this configuration and users don't need to config each newly created Rails application to use JDBC adapter.
   
   
3. Generate scaffold:
   
   

   ruby script/generate scaffold book name:string description:text price:float

   
   The scaffold API in Rails 2.0 is different from Rails 1.2. We need to specify field name and data type in the command line. This command will generate the model, view, controller and db migration files automatically.
   
   
4. Perform database migration:
   
   

   jruby -S rake db:migrate

   
   
5. Launch the default web server:
   
   

   jruby script/server

   
   
6. Navigate to http://localhost:3000/books to access the application.

Packaging Rails app into WAR

Warbler is a gem to make a single WAR file out of a Rails project and provides a minimal, flexible, Ruby-like way to bundle up all of your application files for deployment to a Java application server. It's developed by Nick Sieger, one of the core developer of JRuby. Warbler bundles JRuby and the Goldspike servlet for dispatching requests to your application inside the java application server, and assembles all jar files in $WARBLER_HOME/lib/*.jar into your application. No external dependencies are needed.

1. Install Warbler :
   
   

   jruby -S gem install warbler

   
   
2. Generate the Warbler configuration file:
   
   

   jruby -S warbler config

   
   and change the 13th line of config/warble.rb file to
   
   

   config.gems = ["activerecord-jdbc-adapter", "rails" ]

   
   because Warbler doesn't automatically package the activerecord JDBC driver.
   
   
3. Package the app:
   
   

   jruby -S warbler [war]

   
   A WAR file(bookstore.war) is generated under the top directory of the Rails app.

Deploy on OC4J Standalone

OC4J stands for "Oracle Containers for J2EE". OC4J standalone is the Oracle AS Containers for J2EE distribution which can be executed outside of the standard OracleAS environment. It is very easy to install(simply unzip it). Typically OC4J standalone would be used for development purposes and for small scale web solutions. OC4J 10g Standalone ships with Oracle JDBC driver for Java 1.4, so deploying JRuby on Rails application on it is made much easier:

1. Use the Application Server Control Console to deploy (access http://localhost:8888/em), or
   
   
2. Use the command line :
   
   

   java -jar $OC4J_ROOT/j2ee/home/admin_client.jar deployer:oc4j:localhost:23791 oc4jadmin -deploy -file /path/to/bookstore.war -deploymentName bookstore -bindAllWebApps
   
   

3. Navigate to http://localhost:8888/bookstore

Troubleshooting

1. While navigating to http://localhost:8888/bookstore/books after deploying the application on OC4J, the browser displays the following error message:
   
   

   No :secret given to the #protect_from_forgery call.
   Set that or use a session store capable of generating its own keys (Cookie Session Store)

   
   Solution: Uncomment the secret in line 9 in app/controllers/application.rb then re-deploy the app. See link.
   
   
2. While navigating to http://localhost:3000/bookstore/books, the browser displays the following error message:
   
   

   driver encountered an error: java.sql.SQLException: Io exception: SO Exception was generated.

   
   Solution: This is due to malformed database connection string in database.yml which should look like this:
   
   

   url: jdbc:oracle:thin:@hostname:1521:XE

   
   The port 1521 cannot be omitted with ojdbc14.jar but it works with ojdbc5.jar.

References

• OC4J FAQ
• JRuby on Rails on Tomcat
• Deploying a Rails Application on Tomcat
• Warbler, A Little Birdie To Introduce Your Rails App To Java
• JRuby .war packaging for Rails 2.0
• Warbler on JRuby Wiki
• Warbler RDoc
• Documentation of Activerecord-jdbc-adapter