Part 1: Hibernate in a Hurry

Our first goal is to get up to speed with Hibernate as quickly as
possible. Most of the chapters in this part are updated versions of
content from Hibernate: A Developer's Notebook
(O'Reilly), reflecting the major changes that came about with Hibernate 3.
The sample code now works with the latest versions of the tools we rely on
to provide an easy yet realistic environment for working with Hibernate.
There is also a new chapter covering the ability to use Java 5
annotations, rather than XML mapping files, to
configure Hibernate mappings.

NOTE

Of course, with any printed book about active open source
projects, things will get out of date quickly! See Appendix E for the
specific versions we discuss, and for ideas on how to cope with
changes.

Getting started and following along with the examples is even easier
in this new version of the book because we've adopted Maven to help
download many of the tools and libraries. As we hope you will see, there's
no excuse to avoid diving in and trying this stuff yourself!

Once you're comfortable with the fundamentals of Hibernate, Part 2 will demonstrate
how to tie Hibernate into some other environments to make each more
powerful than they are on their own.

All right, time to dive in….

Chapter 1. Installation and Setup

It continues to amaze me how many great, free, open source Java™ tools
are out there. When I needed a lightweight object/relational mapping service
for a JSP e-commerce project at the turn of the
millennium, I had to build my own. It evolved over the years, developed some
cool and unique features, and we've used it in a wide variety of different
contexts. But, once I discovered Hibernate, we used that for new development
instead of my own familiar system (toward which I'll cheerfully admit bias).
That should tell you how compelling it is!

If you're looking at this book, you're likely interested in a powerful
and convenient way to bridge the worlds of Java objects and relational
databases. Hibernate fills that role very nicely, without being so
complicated that learning it becomes a daunting challenge in itself. To
demonstrate that, this chapter guides you to the point where you can play
with Hibernate and see for yourself why it's so exciting.

Later chapters will look at using Hibernate as part of more complex
environments such as Spring and Stripes, as well as using it with other
databases. The goal of this first chapter is to show you how easy it is to
put together a basic, self-contained environment in which you can explore
Hibernate and do real things with it.

1.1. Getting an Ant Distribution

Although it might be surprising, the first few things you need
to get Hibernate running have nothing to do with Hibernate
itself. First, you must set up an environment in which the remaining
examples work. This will have the pleasant side effect of building a solid
foundation for any actual project you might be undertaking.

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 run them 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?

The examples use Apache Ant for several reasons. It's convenient
and powerful; it's one of the standard build tools for Java-based
development; it's free; and it's cross-platform. If you use Ant, the
examples will work equally well anywhere there's a Java environment,
which means readers of this book won't be frustrated or annoyed.
Fortunately, it also means we can do many more cool things with less
effort—especially since several Hibernate tools have explicit Ant
support, which I'll show you how to leverage. (I should note that these
days more complex Java projects often use Maven, which adds many other
project management capabilities. Since I had to pick one, in the spirit
of keeping things simple and true to what I find useful, I went with Ant
for these examples.)

If you are currently using Maven as a build tool, you will notice that we are using Maven's Ant Tasks to
manage dependencies from our Ant builds. Although Maven is gaining
momentum, Ant continues to be the most widely used build tool in Java
development. Every chapter's example code folder also has a Maven
pom.xml file and can be compiled
with Maven. In many cases, the Maven build file provides the same
functionality as the Ant build.xml
file by using the Maven Hibernate3 plug-in. In Chapter 12 you will find some
guidance for building and deploying Hibernate applications using
full-blown Maven, but the majority of the examples in this book focus on
Ant as a build tool, using the Maven Ant Tasks to relieve the tedium of
finding and downloading the various libraries we need, and the libraries
on which they, in turn, rely.

To take advantage of all these capabilities, 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 Ant manages Java builds, I feel
lost without it.

1.1.2. How do I do that?

You can download a binary release of Ant from http://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.7.0; 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.7.0 ant

Once Ant is situated, you need to do a couple of things to make it
work correctly. You need to add its bin directory in the distribution (in this
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 (http://ant.apache.org/manual/) if you need
them.