Getting Started with Decorum

What decorum does in simple terms

The full benefits of Decorum can probably only be understood once you’ve used it for a while, or if you’ve tried other software such as Maven, Ivy or AntLion and found (as I did) that it doesn’t do quite what you want.

At its simplest, decorum builds a classpath of all your dependencies for you, which it can satisfy by automatically building them, or by finding a jar matching the dependency name and version.

Instead of depending on a jar, you depend on a project which provides two main benefits:

Upgrading a dependency can be as simple as dropping the new jar in the library directory.
The dependency can be automatically build from source

Decorum was largely created to solve two major annoyances with building a java project

If a jar file is missing, ant / javac have no way of telling you which one. You will get compile errors, and have to figure out from the missing class name which dependency is missing, and in particular which jar file. This can be very time consuming, especially since you may not be familiar with the classes.
You can only resolve one missing jar at a time. You have to repeat the compile to see if you’re missing anything else.

Since decorum allows you to explicitly define your dependencies, it can check for their existence before a build is even attempted. It can give you a list of exactly which jars are missing – all at once.

A quick comparison with Maven

Maven handles repositories of jar files so that projects can be distributed without them, yet they can be easily obtained.

Decorum doesn’t do any of this – you have to provide jars yourself.

Decorum will look through jars which match the project name, and pick the one with the highest allowed version number.

AFAIK Maven can’t do this.

So let’s see how this all works…

Making decorum available to your build file

First place the jar your library directory, and use a taskdef to install the extension:

<project ...>
...
  <!-- Import Decorum -->
  <taskdef name="dependencies" classname="org.trapdoor.decorum.Decorum">
    <classpath location="/path/to/decorum.jar" />
  </taskdef>
...
</project>

This makes a “dependencies” task available to your build file.

The Dependencies Task

The dependencies task defines a list of dependencies your project has. These may be sub-projects, sibling projects or third party projects. Decorum can either look for .jar files for these dependencies or perform sub-builds on them.

Let’s see how we define a simple list of dependencies:

<project ...>
...
  <dependencies id="deps">
    <dependency name="log4j" />
  </dependencies>
...
</project>

Notice the “id” attribute. This identifies the list of dependencies and we will use it later when we want to use the generated classpath. You can have multiple dependency lists by defining multiple dependencies elements with different ids.

But this won’t quite work as it stands – how does decorum know where to look for log4j? We need to add a libdir attribute to tell decorum where to look for the log4j jars:

<dependencies id="deps" libdir="/path/to/libs">

At this point, decorum will look in the libs directory for jars named log4j.jar, or log4j-.jar. Even before the build has started, if these dependencies fail, decorum will complain and stop the build – telling you to fix your dependencies first.

This will also create a path ref called “path.deps” for you, which you can pass in the classpathref attribute to the javac task.

Specifying Version Restrictions

You can specify minimum, maximum or exact versions that Decorum can match when it looks for jar files:

<dependency name="junit" version="3.9.8" />
<dependency name="junit" version="3.9-" />
<dependency name="junit" version="4.0+" />

which specify junit version 3.9.8 only, 3.9 or less, and 4.0 or greater respectively. Example jars that will match would include:

junit-3.9.8.jar
junit-3.9.jar, junit-3.9.8.jar, junit-3.5.2.jar
junit-4.0.jar, junit-4.0.1.jar, junit-5.jar

As you may have guessed, decorum understands version numbers separated by dots.