Using Raven

The Quick Example

As a short example is always better than hundred lines of prose (at least in this context), Here is something that should satisfy your basic needs, it's the content of a rakefile that should sit at the root of your project module:


require 'raven'
require 'rake/clean'

CLEAN.include('target')

dependency 'compile_deps' do |t| 
    t.deps << [{'commons-logging' => '1.0.4'}, 'commons-pool']
    t.deps << ['commons-lang', 'wsdl4j', 'log4j']
end

javac 'compile' => 'compile_deps' do |t|
    t.build_path << "src/main/java"
end

jar 'ode-utils.jar' => 'compile'

jar_source 'ode-utils-source.jar' => 'compile'

lib_dir 'prepare_lib' => 'compile_deps' do |t|
    t.target = 'dist/lib'
end

war 'utils.war' => ['compile', 'compile_deps'] do |t|
    t.webapp_dir = 'src/test'
end

javadoc 'jdoc' => 'compile_deps'

junit 'test' => ['compile', 'compile_deps']

gem_wrap_inst 'gem' => 'ode-utils.jar' do |t|
    t.version = '1.0'
end
  

This demonstrates almost all Raven tasks available at the moment. But hopefully more will come to solve your problems (or at least the ones Raven is intended to solve). Don't hesitate to follow the links above, they lead to more detail.

To execute one of these tasks, it's just the usual rake thing:

rake ode-utils.jar

Just don't forget to require raven in your rakefile to load raven extensions.

All dependencies are automatically downloaded from http://gems.rubyraven.org/ if they're not available locally.

Installing Dependencies

If you're a smart guy (and you must be one if you chose Raven), you'll probably want to reuse things that have been written by others. Hence introducing dependencies in your project. But today is a lucky day for you! Raven let's you install these dependencies pretty simply. So using them in your Rake script becomes easy as well.

The easy way is to rely on Raven's Java Gem repository and let it download automatically your project dependencies. On your first build, and only if the necessary gems aren't already available locally, Raven will download and install them for you.

If no version is provided on the dependency declaration, the latest one will be fetched. However that's not really recommended outside of simple prototyping. If you want repeatable builds, specifying explicit version numbers is much better (see the above example script).

For those prefering explicit installations or if you want to try out some libraries without necessarily adding them in your rakefile, Raven also comes with an install command. All the following are valid Raven installation commands:


    # Installs the latest version of commons-httpclient
    raven install httpclient
    # Installs explicitly xstream 1.2 from the xstream module
    raven install -g xstream xstream:1.2
    # Installs all Axis2 modules (from the axis2 group)
    raven install --all -g axis2
  

The command tries to be as permissive as possible with what you pass (doing some regexp based search) and will tell you when there is an ambiguity. Providing a more complete name, the group or the version can remove the ambiguity. It also tries to guess the latest version when none is provided (sometimes that can be a challenge so be tolerant).

Running Your Own

The Theory

Yes, that's the sad truth, all these dependencies that you declare must be found somewhere. And that's where RubyGems come into the picture. A Gem is basically a package (a zip) containing everything necessary to install a given software or library. Ruby Gems has a remote repository where it downloads all its Gems from. So when you type 'gem install rails' it will look up the Rails Gem in the remote repository, download the Gem and install it locally. And it's not installed in a random directory but in Gem's local repository.

So where does Raven comes into the picture? It just wraps jar files in a Gem. Basically a Gem becomes a small box containing a jar. What's the benefit? Gem is good, so if you can use Gem, you'll be good too.

So Raven does four things:

  • It provides a central Java Gem repository where it finds all required gems at http://gems.rubyraven.org/.
  • If you don't want to rely on implicit installation, it provides you the install command (see above).
  • If you're using Maven (and plan to change to Raven, of course), it imports your Maven local repository into the Gem local repository. Just a simple command and you're set! Yes, sometimes life can be beautiful.
  • It allows you to create your own central repository that you can use to get your Gems from. It will download everything from other Maven repositories and sets up your own Gem central repository with all these jars.

The Things To Do

If you're using Maven (but not for long hopefully), just use the following command and answer to the questions. That's probably the easiest way to build your local repository for now.

%> raven import

To setup your own remote repository (which soon or later is going to be needed anyway if you need more dependencies), run this from an appropriate directory:

%> raven repository

This is going to take a while as the whole repository will be downloaded. Alternatively, if you're only interested in a few modules use:

%> raven repository axis2 xerces springframework hibernate

This can be run several times if you want to add up more libraries later.

Then, to start the central server, run from the same directory:

%> raven server

To configure Raven to use your new central repository in a rakefile, just configure the sources as shown below:

set_sources(["http://localhost:2000"])