JRuby-Rack

JRuby-Rack is a lightweight adapter for the Java servlet environment that allows any Rack-based application to run unmodified in a Java servlet container. JRuby-Rack supports Rails, Merb, and any Rack-compatible Ruby web framework.

For more information on Rack, visit http://rack.rubyforge.org/.

Download

JRuby-Rack 0.9.5 is the latest available and stable release.

Download

JRuby-Rack is also bundled with Warbler, which is available as a Ruby gem (jruby -S gem install warbler).

Getting Started

The easiest way to use JRuby-Rack is to get Warbler. Warbler bundles the latest version of JRuby-Rack and ensures that it gets placed in your WAR file when it gets built.

If you're assembling your own WAR using other means, you'll need to drop the latest JRuby-Rack jar into the WEB-INF/lib directory and configure the RackFilter in your application's web.xml.

Examples of web.xml snippets follow.

Rails web.xml Configuration

Here's sample web.xml configuration for Rails. Note the environment and min/max runtime parameters. For multi-threaded Rails with a single runtime, set min/max both to 1. Otherwise, define the size of the runtime pool as you wish.

 <context-param>
   <param-name>rails.env</param-name>
   <param-value>production</param-value>
 </context-param>
 
 <context-param>
   <param-name>jruby.min.runtimes</param-name>
   <param-value>1</param-value>
 </context-param>
 
 <context-param>
   <param-name>jruby.max.runtimes</param-name>
   <param-value>1</param-value>
 </context-param>
 
 <filter>
   <filter-name>RackFilter</filter-name>
   <filter-class>org.jruby.rack.RackFilter</filter-class>
 </filter>
 <filter-mapping>
   <filter-name>RackFilter</filter-name>
   <url-pattern>/*</url-pattern>
 </filter-mapping>
 
 <listener>
   <listener-class>org.jruby.rack.rails.RailsServletContextListener</listener-class>
 </listener>

web.xml Configurations for Other Rack Applications

Here's a sample web.xml configuration for a Sinatra application. The main difference is to place the rackup script for assembling the Rack-based application in the rackup parameter. Be sure to escape angle-brackets for XML.

 <context-param>
   <param-name>rackup</param-name>
   <param-value>
     require 'rubygems'
     gem 'sinatra', '~&gt; 0.9'
     require './lib/demo'
     set :run, false
     set :environment, :production
     run Sinatra::Application
   </param-value>
 </context-param>
 
 <filter>
   <filter-name>RackFilter</filter-name>
   <filter-class>org.jruby.rack.RackFilter</filter-class>
 </filter>
 <filter-mapping>
   <filter-name>RackFilter</filter-name>
   <url-pattern>/*</url-pattern>
 </filter-mapping>
 
 <listener>
   <listener-class>org.jruby.rack.RackServletContextListener</listener-class>
 </listener>

Features

Servlet Filter

JRuby-Rack's main mode of operation is as a servlet filter. This allows requests for static content to pass through and be served by the application server. Dynamic requests only happen for URLs that don't have a corresponding file, just as many Ruby applications expect. The application can also be configured to dispatch through a servlet instead of a filter if it suits your environment better.

Servlet Environment Integration

• Servlet context is accessible to any application both through the global variable $servlet_context and the Rack environment variable java.servlet_context.
• Servlet request object is available in the Rack environment via the key java.servlet_request.
• Servlet request attributes are passed through to the Rack environment.
• Rack environment variables and headers can be overridden by servlet request attributes.
• Java servlet sessions are used as the default session store for both Rails and Merb. Session attributes with String keys and String, numeric, boolean, or Java object values are automatically copied to the servlet session for you.

JRuby Runtime Management

JRuby runtime management and pooling is done automatically by the framework. In the case of Rails, runtimes are pooled. For Merb and other Rack applications, a single runtime is created and shared for every request.

Feedback

Please use the JRuby-Rack mailing lists on kenai.com and the JRuby-Rack JIRA issue tracker for feedback.

Source

The source is currently available from either of the following locations. To get the source, use git clone:

  git clone git://kenai.com/jruby-rack~main
  git clone git://github.com/nicksieger/jruby-rack.git

Building

You can build with either Maven or Rake. Either of the following two commands will suffice (but see the Note below).

 > mvn install 
 > jruby -S rake

The generated jar should be located here: target/jruby-rack-*.jar.

Note: There was a bug in JRuby's Java integration code in the 1.1.4 and 1.1.5 releases that prevented the specs from running cleanly. If you're building JRuby-Rack with one of those versions of JRuby, you'll need to skip running the specs as follows:

 > mvn install -Dmaven.test.skip
 > jruby -S rake SKIP_SPECS=true

If you build with JRuby <= 1.1.3 or JRuby >= 1.1.6, the specs should run clean.