1.1 Getting an Ant Distribution

If you're not already using Ant to manage the building, testing, running, and packaging of your Java projects, now is the time to start. The examples in this book are Ant driven, so you'll need a working Ant installation to follow along and experiment with variations on your own system, which is the best way to learn.

First of all, get an Ant binary and install it.

1.1.1 Why do I care?

We chose to structure our examples around Ant for several reasons. It's convenient and powerful, it's increasingly (almost universally ) the standard build tool for Java-based development, it's free and it's crossplatform. Many of the example and helper scripts in the current Hibernate distribution are Windows batch files, which don't do any good for people like me who live in a Unix world. Using Ant means our examples can work equally well anywhere there's a Java environment, which means we don't have to frustrate or annoy any readers of this book. Happily, it also means we can do many more cool things with less effort ” especially since several Hibernate tools have explicit Ant support, which we'll show how to leverage.

To take advantage of all this, you need to have Ant installed and working on your system.

NOTE

I used to wonder why people bothered with Ant when they could use Make. Now that I've seen how well it manages Java builds, I feel lost without it.

1.1.2 How do I do that?

Download a binary release of Ant from ant.apache.org/bindownload.cgi . Scroll down to find the current release of Ant, and download the archive in a format that's convenient for you to work with. Pick an appropriate place for it to live, and expand the archive there. The directory into which you've expanded the archive is referred to as ANT_HOME . Let's say you've expanded the archive into the directory /usr/ local/apache-ant-1.5.1 ; you may want to create a symbolic link to make it easier to work with, and to avoid the need to change any environment configuration when you upgrade to a newer version:

/usr/local $ ln -s apache-ant-1.5.1 ant

Once Ant is situated, you need to do a couple of things to make it work right. You need to add its bin directory in the distribution (in our example, /usr/local/ant/bin ) to your command path . You also need to set the environment variable ANT_HOME to the top-level directory you installed (in this example, /usr/local/ant ). Details about how to perform these steps under different operating systems can be found in the Ant manual, ant.apache.org/manual/ , if you need them.

Of course, we're also assuming you've got a Java SDK. Because some of Hibernate's features are available only in Java 1.4, you'd be best off upgrading to the latest 1.4 SDK. It's also possible to use most of Hibernate with Java 1.3, but you may have to rebuild the Hibernate JAR file using your 1.3 compiler. Our examples are written assuming you've got Java 1.4, and they will need tweaking if you don't.

Once you've got this set up, you should be able to fire up Ant for a test run and verify that everything's right:

~ $ ant -version
Apache Ant version 1.5.1 compiled on February 7 2003

1.1.3 What just happened ?

Well, not much just yet, but you're now in a position where you'll be able to try out the examples we provide later on, and use them as a starting point for your actual Hibernate projects.

If you're new to Ant, it wouldn't be a bad idea to read the manual a little bit to get a sense of how it works and what it can do for you; this will help make sense of the build.xml files we start working with in our examples. If you decide (or already know) you like Ant, and want to dig deeper, you can pick up O'Reilly's Ant: The Definitive Guide (after you finish this book, of course)!

1.1.4 What about...

...Eclipse, JBuilder, Sun ONE Studio (Forte for Java), or some other Java IDE? Well, you can certainly use these, but you're on your own as far as what you need to do to get Ant integrated into the build process. (Several already use Ant, so you might be starting out ahead; for the others you might have to jump through some hoops.) If all else fails, you can use the IDE to develop your own code, but invoke Ant from the command line when you need to use one of our build scripts.