Hibernate and You

By Peter Deschere, Jason Fillo and Becky Beale, CISC474 06S. Lovingly edited by P. Conrad

Getting started

Let me be blunt, hibernate is a pain. It is cranky, tempermental, and at times cryptic. But even with those flaws it is one heck of a great product. Hibernate abstracts all of your persistent storage and allows you to learn one "language" (HQL - Hibernate Query Language) to save, retrieve, and load your data. This means, once learned, you can concentrate your efforts on your business logic instead of your persistence framework.

First things first, the best way to acclimate yourself to hibernate is....tada...go to the hibernate webiste. Specifically, read through the hibernate quickstart and tutorial.

Once you have read the quick start (don't sweat that the test doesn't completely work on porsche or strauss) and tutorial, you have the basic structural knowledge to work with hibernate. The reading in BFLJ, is also useful if you want a different view of how hibernate works. I did not find it as useful since their examples required a large amount of change to make them work. The saving grace of the BFLJ book is that it does show you how to properly set-up a "List" of items. This is the biggest stumbling block and the most difficult thing to master in hibernate.

Next steps

The easiest part of Hibernate, though also the easiest part to mess up, is the configuration file. I used the hbm.xml file as I prefer the structure that XML provides, it makes finding things really easy. Hibernate supports multiple other initialization files, including hibernate.properties and nested code. Use what feels right. The tricky part to the configuration files (for hibernate and each of your classes) is that they have to follow your class files. This was a steep learning curve for us as the errors were pretty cryptic. If you receive an initialization error or NoClassDefError, you most likely have misplaced XMLs.

Build jUnit tests

I repeated that three times because it is the most important thing you can do. First, because you can use it to "bootstrap" data into your db for testing. Second because test driven development creates good code. Period, end of story.

Finally, make sure to build CRUD (CReate,Update,Delete) functions for all of your objects in some *Manager.java. I prefer to use one class, I have seen many people who make a Manager per object, again pros and cons to both.

Build a HibernateUtil class (feel free to use ours) as a singleton. This is just good practice as you will not create more references in memory than you need.

Permissions and Authors

This code is useable for commercial, academic, or personal use. The authors, as listed below, hold no responsibility to any harm, loss, or damages caused by using our code.

Authors

Peter Deschere peter@deschere.com
Jason Fillo jfillo@gmail.com

Contents of the README file

Welcome to the README for the simple Bulletin board webapp.

Coded by: Peter Deschere and Jason Fillo.  (Becky Beale helped too.)
Date: 05/15/2006

Permission:  The code for this project is subject to the open GNU licensing agreement.  
Additional considerations (for full use of said code as well as changing the terms of
this license) are given to Prof. Phillip Conrad.  The code was heavily influenced by
the documentation found at www.hibernate.org and the O'reilly book "Better, Faster, Lighter Java"
by Tate & Gehtland.

INSTALLATION
1) Modify the global.properties file in the root directory to map to your local directories,
specifically: {sections that require changing are after the =} 
porsche.tomcat.dir=/porsche/cisc474/tomcat
porsche.hibernate.dir=/m/imageua/deschere/workspace/BB/lib     ********see NOTES below
porsche.tomcat.jar=/porsche/cisc474/tomcat/common/lib/servlet-api.jar
porsche.mysql.jar=/porsche/cisc474/mysql-connector-java-3.1.12/mysql-connector-java-3.1.12-bin.jar
porsche.war.desination=/m/imageua/deschere/tomcat/webapps

2) Modify the hibernate.cfg.xml file to access your database (url), with your id, and your password. 
(as I doubt mine will work any longer)
		<property name="connection.url">jdbc:mysql://jaguar.cis.udel.edu:8099/deschere</property>
		<property name="connection.username">deschere</property>
		<property name="connection.password">q465hi</property>
***see NOTES below

3) Run "ant" to display the menu of options (for deploy)

NOTES:
The Hibernate files are most appropriately stored to some group directory.  As of this writing
the miserly "professor" has not given us a group directory with write access to store these files.
For shame.

Near the bottom of the hibernate.cfg.xml file is a line:
		<property name="hbm2ddl.auto">update</property>
You can change the "update" to "create" which will destroy and recreate all necessary tables, in essence 
no longer being persistent.  But it works great for testing. 

Don't sweat the small stuff, let Hibernate rock and roll all the way, it bootstraps your database for you
(at least in mysql).  

Love to live and live to love.

***************************************************************************************

More Info from Peter:

All database stored objects must have a *.hbm.xml file to map them to
the database.

All *.hbm.xml files must be in the hibernate.cfg.xml.

If you want to create an object that contains one to many of another
object, one of the easiest options to use (as hibernate supports
collections) is a simple List.  To use the list you must create the
one to many relationship within in the object that contains objects
hbm.xml file.  (An example is Topic.hbm.xml)

Steps:

1) Use Hibernate tutorial to get "checklist" of files needed (lib) and
templates for cfg.xml and hbm.xml files.

2) Now create objects / hit the whiteboards.  Classes with just
getters and setters for all properties, plus a "ID" field.

3) Create jUnit tests for all getters/setters and what you expect your
program to do. (use examples from tar file)

4) At this point in your root directory create the hibernate.cfg.xml
file (template from Tutorial can be used).

5) Create HibernateUtil.java either using our tar file or the template
in the tutorial.

6a) Create an hbm.xml file.
 b) test the jUnit for that object.
 c) lather rinse repeat

7) Create a *Manager.java class.  This is your abstraction for your
programers so they don't have to learn HQL or SQL.  This is
transaction, you should have all CRUD operations in the Manager.  You
can do one generic manager for all your objects (such as DBManager) or
you can have one per object, ad naseum.

8) Finish your controller code using the Manager class.