Hibernate - Part 2- Getting Started

As mentioned in a previous post, I've been preparing for using Hibernate in my latest project by reading Harnessing Hibernate, the Getting Started Guide, and watching some tutorials on YouTube.  At this point, I was ready to do some coding.

I opted to download and play with some of the tutorials from the Harnessing Hibernate book.  However, I wouldn't be using the code as-is.  I'd be making some initial modifications to the sample code:

1. I'd use the current version of Hibernate (v3.6.2.Final), Hibernate Tools (v3.2.4.GA) and Ant (v1.8.2) instead of the older versions discussed in the book.
2. I decided, at least for now, not to use the Maven ant tasks for downloading and maintaining library dependencies.  Instead, I would manually download the Hibernate release bundles from SourceForge.
3. I would run the examples through Eclipse rather than solely through the file system as described in the book.
4. Instead of using the example "test" code as-is (Java classes with main() method), I would incorporate the test code into JUnit tests.

So far so good, right?  Well I quickly ran into some challenges getting the sample code running on my dev system.

Downloading and unpacking the Hibernate resource bundles is a no-brainer, but do I need to do anything special to Eclipse?  Of course, my project will need the Hibernate jars in its classpath (more on the later) but if I want the Eclipse IDE to include the Hibernate perspective and tooling I'll also need to install the Hibernate Tools directly into Eclipse.  Although I won't really leverage the Hibernate / Eclipse integration right now, I'd like to at least get it configured.  Rather than go step-by-step through the process, I recommend following the directions as described in the JBoss Tools 3.2 Installation From Update Site.

At this point, I created a new Eclipse Java Project and imported the Harnessing Hibernate sample code for Chapter 3.  The sample code includes an Ant build file, the Hibernate configuration and mapping files as well as test classes for inserting records and querying records.

I had compile errors in the Java classes that reference Hibernate.  It's worth noting that even though we installed the Hibernate Tools into Eclipse (and indeed Eclipse now recognizes and assigns special icons and editors to the Hibernate config and mapping files) we still need to add the Hibernate and dependent jars to the project build path.

Several of the online tutorials I read suggested using Eclipse User Libraries as a convenient way to organize the Hibernate jars in the project's build path.  The User Libraries initially seemed like a good solution and my Java classes now compiled without errors.  However, I soon realized my Ant build wasn't aware of the User Libraries I created.  I describe in detail in an earlier blog post my attempts to overcome this issue.  In the end I decided to utilize User Libraries in Eclipse and add separate classpath references for the jars in the Ant build file.  It seems like a duplication of effort but it's workable for now.

An inspection of the Ant build.xml included in the Harnessing Hibernate sample code shows Ant tasks for using the HibernateTool task to create both Java classes and Database tables.  The Hibernate Tool uses the hibernate.cfg.xml and a couple of Hibernate mapping files (.hbm) to determine what to create and where.  For these samples, we are using an HSQLDB database.

Before we run the Ant tasks and actually use Hibernate for the first time, let's take a moment to review what we've done so far:

1. Download and unpack the release bundles for Hibernate, Hibernate Took and Ant.
2. Install the Hibernate Tools into Eclipse using Help > Install Software
3. Create a new Eclipse Java Project and import the sample code from Harnessing Hibernate (Chapter 3)
4. Create Eclipse User Libraries for Hibernate
5. Update the Ant build.xml classpath with references to the Hibernate and Hibernate tool jars.

At this point, I ran the HibernateTool tasks in the Ant build file for creating the Java entity classes and database tables.  Ant executed without any stack traces and ended with BUILD SUCCESSFUL.  Awesome!  I confirmed the new Java classes were created but when I fired up the HSQL Database Manager I couldn't see the new database table.  What gives?  Why did Ant finish successfully but not create the table?

This caused a lot of confusion on my part and began a period of tweaking my classpath and log4j logging levels in an effort to understand the problem.  The first thing I noticed was my updated log4j level (now DEBUG) wasn't printing anything to the console.  I was only seeing INFO level logging.  Hmmm.

Remember, up to now I've been running the Ant build directly from Eclipse.  At this point I tried running Ant directly from a Command Prompt and voila!  The output showed DEBUG log4j logging and most importantly the database table was now created in HSQL.

After some more trial and error, I modified the JRE setting in Eclipse for the Ant build file (Right click on build.xml > Run As > Ant build...) and changed the Runtime JRE from "Run in the same JRE as the workspace" to "Separate JRE".  The JRE specified in the "Separate JRE" was the EXACT same JRE that Eclipse was using.

I then reran Ant tasks from within Eclipse and this time it worked!  I don't understand why it works in a separate JRE but not within the same JRE.  I posted to the Tools forum in the Hibernate Community.  One of the guys from the Hibernate Team posted some responses but in the end suggested keeping the "Separate JRE" setting which is what I've done.  I also made a similar post on the Stack Overflow boards.