Automation for the people: Build Java projects with Raven

Say "nevermore" to inexpressiveness and use Ruby to build your Java applications

 

I have an existing Java project, and over the past few years, I've meticulously maintained an Ant build script for it. I like the plethora of tasks available for Ant; however, I often find that the XML syntax of Ant scripts is somewhat onerous to write. Further, Ant's XML heritage is occasionally limiting when it comes to expressiveness . In fact, when I find myself needing a higher degree of flexibility (say with conditional logic), I'm often forced to write a custom task or embed logic within Ant's script task using Groovy, for instance.

Inexpressiveness nevermore

About this series

As developers, we work to automate processes for end-users; yet, many of us overlook opportunities to automate our own development processes. To that end, Automation for the people is a series of articles dedicated to exploring the practical uses of automating software development processes and teaching you when and how to apply automation successfully.

A few years ago, in my pursuit to find more expressive tools for building software, I learned of Rake. Rake is a Domain Specific Language (or DSL) for building software using the full-featured Ruby programming language. With Rake, I have the expressiveness I'm looking for without having to jump through hoops. I don't need to write custom tasks, for instance, because a Rake build script is Ruby (as opposed to XML); therefore, if I need some conditional logic, I can easily code it where I need it. What's more, Rake employs a dependency-based tasking system similar to what you find in Ant and its venerable progenitor, make. For instance, if I type rake deploy , Rake would call the dependent tasks I've set up, such as compilation, running tests, and so on. And Rake is smart enough to run dependent tasks only once (just like Ant, by the way).

By itself, Rake isn't all that helpful for most Java projects; however, a relatively new project, dubbed Raven, has married the power and expressiveness of Rake with tasks specific for building Java applications. With Raven, Java developers have a truly viable build platform that provides Java-specific features, such as compilation with javac and archiving binaries with jar and war , with the rich expressiveness of the Ruby programming language.

What is a DSL?

A Domain Specific Language (or DSL) is a programming language designed for a specific task. The Java language and Ruby are general-purpose programming languages, while Ant and Rake are DSLs dedicated to building software. Rake is considered an internal DSL because it's written in Ruby and can be extended using Ruby. Ant, on the other hand, is an external DSL because it is parsed and then executed in another language (that is, the XML is parsed and then acted upon via Java programming).

Raven is Rake and Rake is Ruby

Before jumping into using Raven for Java projects, it helps to understand the relationship between Raven and Rake. Figure 1 shows a logical diagram of Raven, and as you can see, Raven uses Rake, RubyGems, and Ruby. Accordingly, native Rake tasks are available to you when using Raven; plus, you can also use Ruby within Raven scripts. RubyGems is a package manager similar to CPAN, RPM, or APT that can be used to download necessary Ruby packages (and Java jars) and any transitive dependencies as well.

Figure 1. Logical diagram of Raven

While the jury is still out as to whether Raven is the best platform for building Java projects, I think you'll find that Raven provides a simple, yet powerful combination in moving toward a more natural programming language for building software. If you ask me, not having to rely on XML to build Java projects is reason enough to take a look at Raven.

---

Back to top

Raven's tapping at your chamber door

There are two approaches to getting Raven installed and configured, the first being the Ruby way and the second being more Java in style, which makes use of JRuby. I prefer the Java way because it's much simpler to configure. Getting Raven up and running entails a few steps:

• Download the Raven/JRuby distribution (see Resources ).
  
• Unzip the file to a location on your workstation.
  
• Create an environment variable called JRUBY_HOME .
  
• Add JRUBY_HOME/bin to your PATH environment variable.
  
• Verify your installation by opening a command prompt and entering jruby -version . If everything was installed correctly, you should see something like ruby 1.8.5 (0) [java] in the command window.

Hello, Raven

Of course, downloading and installing Raven isn't all that interesting. The real meat of this beast is its flexibility when creating build scripts. In Raven speak, build files are called Rakefiles and they have a simple format; in fact, if you've ever programmed in Ruby (or seen some Ruby code), they'll look quite familiar. That's the beauty, by the way, of Raven: it is Ruby — with some special words inserted here and there.

To get started using Raven quickly, I'll do arguably the most basic (and important) task first, compilation. The directory structure in Figure 2 represents my Java project's layout. Knowing where my third-party libraries and source code live will come in handy shortly.

Figure 2. Directory Structure of existing Java project

Note the lib directory in Figure 2. This is where third-party JARs live. Before I can compile, I must create a path, which couldn't be easier with Raven because it supports the ability to create a classpath via its dependency task (which is actually just a Ruby method, provided by Raven, called dependency ), which you can see in Listing 1:

Listing 1. Creating a classpath with Raven

require 'raven' require 'rake' dependency 'deps' do | task | task.libs = Dir.glob('lib/**/*.*') end

 

The deps dependency task, as defined in Listing 1, includes all of the libraries in my lib directory using the Dir class and glob() method. I can also use the dependency task to download JARs (using RubyGems) from a repository (which is similar to Maven's dependency management mechanism).

In Listing 1, I've specifically included anything found in the lib directory as part of my path. I've named this task deps and, as you'll see next in Listing 2, I can then make this task execute explicitly before I attempt to compile anything:

Listing 2. Compilation is a breeze

javac 'compile ' => 'deps' do |task| task.build_path << "src" end

 

As you can see, I'm performing compilation via Raven's javac task. The task is called compile and it has a dependency to the deps task from Listing 1. The symbol => means that Raven will run any task (or tasks) to the right of this operator prior to the current task (much like the depends attribute of the target element in Ant).

In between the do and the end of my javac task is where all the magic happens. By default, the javac task uses "src/main/java" as the default value of build_path . But, because my Java project does not follow this convention (remember Figure 2 ?), I need to modify the build_path property, which in my case is src because that's where my source code resides.

Is Raven just Ruby for Maven?

You might think that Raven is just a Ruby version of Maven, but that's not quite accurate. Although there are similarities in default naming conventions and dependency management, Raven's creator explains that it was just easier to do so.

To test this Raven script, I need to open a command prompt and type: rake compile . The .class files that are generated as a result of compilation will be placed into a directory called target/classes, which is automatically generated by the javac Raven task.

Less is more

One thing should be clear at this point. I didn't have to write a lot of code to get things compiled because Raven handled a few things behind the scenes, such as creating a target/classes directory and copying the resulting class files into this location. In fact, you may have already forgotten what the equivalent Ant script for Listing 1 and Listing 2 looks like. As a friendly reminder, Listing 3 shows a typical compilation using an Ant build script:

Listing 3. Compile Java source code with Ant

<?xml version="1.0" encoding="iso-8859-1"?> <project name="compile-code" default="all" basedir="."> ... <target name="compile-src"> <mkdir dir="${classes.dir}"/> <javac destdir="${classes.dir}" debug="true"> <src path="${src.dir}" /> <classpath refid="project.class.path"/> </javac> </target> <project>

 

Comparing Listing 3 with Listing 1 and Listing 2 offers some striking differences, don't you think? Not only does Raven do away with XML, but it assumes some basic attributes, thus allowing you to specify less when it comes to defining tasks. What's more, as Listing 2 shows, Raven allows you to override aspects that Raven assumes if you need to.

While Listings 1 and 2 are certainly interesting from a comparison standpoint, compilation is just the beginning of the fun that is build scripting. Let me show you a more interesting feature: packaging a Java Web application.

---

Back to top

Simple war file generation

A Web Archive (WAR) file is used to package Web applications and contains various assets such as servlets, third-party libraries, and images, for instance. These archives use a standard directory naming scheme and expect certain files, such as web.xml (which maps servlet names and other configuration aspects), to reside in the WEB-INF directory.

Raven makes the creation of a WAR file quite simple. In Listing 4, I'm using the war task with the name 'brewery.war' , which, by default, creates a WAR file with the same name. The default location of webapp_dir is src/main/webapp, but because my directory structure is different than what Raven assumes, I need to modify this with the line task.webapp_dir = 'src/web' .

Listing 4. Creating a WAR to deploy to a Web container

war 'brewery.war' => ['clean', 'compile', 'java-doc'] do |task| task.webapp_dir = 'src/web' end

 

Note how I've declared that before a WAR file can be created, Raven must first run the clean task, followed by the compile task, followed by a task to create some documentation. After those tasks successfully run, Raven can then create an archive, which as you can see requires very little typing. In fact, if my project followed the default directory layout that Raven assumes, I wouldn't have needed to write anything beyond those dependent tasks (that is, the code between the do and end wouldn't be required!).

Believe it or not, that's all there is to it — Raven's war task handles directory creation, file placement, and war file generation. Very efficient, don't you think?

Is it Raven, Rake, or Ruby?

All of the above! Rake is a DSL for building projects using Ruby. Raven uses Rake to provide Java-specific functionality for building Java projects. With Raven, just as with Rake, you've got access to the full Ruby programming language within your build scripts.

Generating documentation the easy way

Generating project documentation is often helpful in disseminating helpful information to team members. If you find yourself writing framework code or utilities that others plan to use, you'll eventually need to publish Javadocs, which are HTML files describing the classes, methods, and public instance variables found in related source code.

Generating documentation using the Javadoc mechanism is a snap using Raven, as you can see in Listing 5:

Listing 5. Generating JavaDoc documentation using Raven

javadoc 'java-doc' => 'deps' do |task| task.build_path << "src" end

 

Note that once again because my project doesn't follow Raven's assumed model, I have to modify the build_path property of the javadoc task. In addition, the task depends upon the deps task (from Listing 1 ) to include any class references.

At this point, you should probably realize that if your project follows Raven's desired layout, your build scripts will be even simpler than mine!

---

Back to top

Gimme more!

Although I've covered just a few of the features available in Raven, there's so much more you can do with this innovative build platform. In particular, there's extensive support in Raven for handling build dependencies (that is, third-party libraries) using RubyGems, a mechanism for auto-downloading of versioned binaries at build time rather than referring to shared drives. RubyGems handles third-party libraries in a similar manner to Maven or Ivy.

Besides RubyGems, Raven also can run JUnit tests, build normal JAR files, and clean directories. Table 1 lists a few of the more popular tasks available in Raven that facilitate building Java projects:

Table 1. Popular (and useful) Raven tasks

Raven task	Description
javac	Compiles Java source files and places the resulting class files in a target/classes directory by default.
jar	Generates a JAR file, which is often a collection of .class files.
war	Generates a Web application archive that is capable of deployment to a Java Web container.
javadoc	Generates Javadocs from source code.
junit	Executes JUnit tests
jar_source	Creates a JAR file from Java source files.
gem_wrap_inst	Transforms a JAR file into a RubyGem and then installs the file into a repository.

 

As Raven matures, the list in Table 1 will likely grow. Besides, if there's something missing in Raven that you need, there's nothing to stop you from writing it yourself!

---

Back to top

In conclusion

I hope I've demonstrated that the beauty of Raven is that it enables you to utilize the power and flexibility of the Ruby language within a build script. Whether or not Raven becomes popular for building Java projects is not for me to decide, but I believe Raven moves the industry in the right direction. In particular, Raven enables dependency-based tasking with a full-featured imperative programming language (rather than a declarative one like XML). Give it a try and see what I mean.

 

Resources

Learn

• Raven: Scripting Java Builds with Ruby (Matthieu Riou, Apress, 2007): This is the definitive guide for Raven, written by Raven's creator.
  
• "Using the Rake Build Language " (Martin Fowler, martinfowler.com, August 2005): Using Ruby to build software couldn't be more fun.
  
• "Ruby off the Rails " (Andrew Glover, developerWorks, October 2005): Get to know Ruby before you hop on (or off) the Rails bandwagon.
  
• "Introduction to Apache Maven 2 " (Sing Li, developerWorks, December 2006): This tutorial gets you started with Maven 2.
  
• "Practically Groovy: Ant scripting with Groovy " (Andrew Glover, developerWorks, December 2004): Andrew Glover introduces Groovy's builder utility, which makes it especially easy to combine Groovy with Ant and Maven for more expressive and controllable builds.
  
• "What's after Ant? " (Andrew Glover, thediscoblog.com, April 2007): Andrew Glover discusses what's on the horizon in the future of build languages.
  
• Automation for the people (Paul Duvall, developerWorks): Read the complete series.
  
• developerWorks : Hundreds of articles about every aspect of Java programming.
  

Get products and technologies

• Raven : Download Raven and JRuby.
  
• Ruby : Download the Ruby one-click installer.
  
• RubyGems : Download RubyGems package management system.
  
• Example Code : Raven script from the article.