Warbler

Warbler is a gem that makes a .war file out of a Rails, Merb, or Rack-based application. The intent is to provide a minimal, flexible, ruby-like way to bundle all your application files for deployment to a Java application server.

Warbler provides a sane set of out-of-the box defaults that should allow most Rails applications without external gem dependencies (aside from Rails itself) to assemble and just work.

Warbler bundles JRuby and the JRuby-Rack servlet adapter 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 downloaded.

Getting Started

1. Install the gem: gem install warbler.
2. Run Warbler in the top directory of your Rails application: warble.
3. Deploy your railsapp.war file to your favorite Java application server.

Usage

Warbler's warble command is just a small wrapper around Rake with internally defined tasks.

Note: Although rake prints out in the messages below, you must substitute warble for rake on the command line.

 $ warble -T
 rake config         # Generate a configuration file to customize your war assembly
 rake pluginize      # Unpack warbler as a plugin in your Rails application
 rake war            # Create trunk.war
 rake war:app        # Copy all application files into the .war
 rake war:clean      # Clean up the .war file and the staging area
 rake war:gems       # Unpack all gems into WEB-INF/gems
 rake war:jar        # Run the jar command to create the .war
 rake war:java_libs  # Copy all java libraries into the .war
 rake war:public     # Copy all public HTML files to the root of the .war
 rake war:webxml     # Generate a web.xml file for the webapp

Warbler makes heavy use of Rake's file and directory tasks, so only recently updated files will be copied, making repeated assemblies much faster.

Configuration

Rails applications

Rails applications are detected automatically and configured appropriately. The following items are set up for you:

• The Rails gem is packaged if you haven't vendored Rails.
• Other gems configured in Rails.configuration.gems are packaged (Rails 2.1 or later).
• Multi-thread-safe execution (as introduced in Rails 2.2) is detected, and runtime pooling is disabled.

Merb Applications

Merb applications are detected automatically, and the merb-core gem and its dependencies are packaged.

Other Rack-based Applications

If you have a config.ru file in the top directory of your application, its contents will be used as the rackup script for your Rack-based application. You will probably need to specify framework and application gems in config/warble.rb.

See the examples in the JRuby-Rack project to find out how to configure Warbler to package Camping and Sinatra applications.

Configuration Auto-detect Notes

• If you don't have database access in the environment where you package your application, you might want to set Warbler.framework_detection to false at the top of config.rb. In this case you might need to specify additional details such as booter, gems, and other settings.
• A more accurate way of detecting a Merb application's gems is needed. Until then, you have to specify them in config/warble.rb. See Custom Configuration below.
• Is it possible to more generally detect what gems an application uses? Gem.loaded_specs is available, but the application needs to be loaded first before its contents are reliable.

Custom Configuration

The default configuration puts application files (app, config, lib, log, vendor, tmp) under the .war file's WEB-INF directory, and files in public in the root of the .war file. Any Java .jar files stored in lib will automatically be placed in WEB-INF/lib for placement on the web app's classpath.

• If the default settings are not appropriate for your application, you can customize Warbler's behavior.
  1. To customize files, libraries, and gems included in the.war file, you'll need a config/warble.rb file. There are two ways of generating one:
     • With the gem, simply run:
         warble config
     • If you have Warbler installed as a plugin, use the generator:
         script/generate warble
  2. Next, edit the config/warble.rb to your taste. The generated config/warble.rb file is fully documented with the available options and default values.
• If you install the gem but later decide you'd like to have it as a plugin, use the pluginize command:
    warble pluginize
  Once Warbler is installed as a plugin, you can use rake to build the war (with the same set of tasks as above).
  
  
• If you want to upgrade or switch one or more Java libraries from what's bundled in the Warbler gem, simply change the jars in WARBLER_HOME/lib, or modify the java_libs attribute of Warbler::Config to include the files you need.

web.xml

Java web applications are configured mainly through the web.xml file. Warbler creates a suitable default file for you for use. However, if you need to customize it in any way, you have two options.

• If you just want a static web.xml file whose contents you manually control, you can copy the one generated for you in tmp/war/WEB-INF/web.xml to config/web.xml and modify as needed. It will be copied into the webapp for you.
• If you want to inject some dynamic information into the file, copy the WARBLER_HOME/web.xml.erb to config/web.xml.erb. Its contents will be evaluated for you and put in the webapp. Note that you can also pass arbitrary properties to the ERB template by setting config.webxml.customkey values in your config/warble.rb file.

For more information on configuration, see Warbler::Config.

Troubleshooting

If Warbler isn't packaging the files you were expecting, there are several debug tasks available to give you more insight into what's going on.

• war:debug prints a YAML dump of the current configuration.
• war:debug:X prints a list of files that Warbler will include during that stage of assembly. Valid values of X are app, java_libs, gems, public, includes, excludes.

Source

You can get the Warbler source using Git, in any of the following ways:

 git clone git://kenai.com/warbler~main
 git clone git://git.caldersphere.net/warbler.git
 git clone git://github.com/nicksieger/warbler.git

You can also download a tarball of Warbler source at http://github.com/nicksieger/warbler/tree/master.

License

Warbler is provided under the terms of the MIT license.

 Warbler (c) 2007-08 Sun Microsystems, Inc.

Warbler also bundles several other pieces of software for convenience. Please read the file LICENSES.txt to ensure that you agree with the terms of all the components.