Introduction to Hibernate
Preface
This chapter is an introductory tutorial for new users of Hibernate. We start
with a simple command line application using an in-memory database and develop
it further in small steps, until we reach a full fledged J2EE application using
Tomcat and WebWork.
This tutorial is intended for new users of Hibernate, but with advanced Java knowledge.
It you work on it and find it difficult to understand, please let us know.
This tutorial was written by Michael Gloegl, he also maintains an online version
at http://www.gloegl.de/5.html - please direct comments and corrections to
michael@hibernate.org. If you need assistance with Hibernate, use the
Hibernate users forum at http://forum.hibernate.org/
Part 1 - The first Hibernate Application
First we'll create a simple console-based Hibernate Application. We use an
in-memory database (HSQL DB), so we do not have to install any database server.
Let's assume we want to have a small application that can store events we want to
attend and information about the hosts of these events.
The first thing we do is set up our development directory and put all the
Java libraries we need into it. Download the Hibernate distribution from the
Hibernate website's download page. Extract the archive and place all libraries
found in /lib/ into into the /lib/ directory of your new development workdir.
It should look like this:
This is the minimum set of required libraries (note that we also copied
hibernate3.jar, the main archive) for Hibernate. See the Readme.txt file
in the /lib/ directory of the Hibernate distribution for more information
about required and optional third-party libraries.
The first class
Next we create a class that represents the events we want to store in
the database. This is just a simple JavaBean class with some simple
properties. Let's have a look at the code:
You can see that this class uses standard JavaBean naming conventions for property
getter and setter methods, as well as private visibility for the fields. This is
a recommended design - but not required. Hibernate can also access fields directly,
the benefit of accessor methods is robustness for application refactorings.
The id property holds a unique identifier value for a particular.
Event instance - all our persistent entity classes (there are less important dependent
classes as well) will need such an identifer property if we want to use the full feature
set of Hibernate. In fact, most applications (esp. web applications) need to identify
particular objects, so you should consider this a feature rather than a limitation.
However, we usually don't manipulate the identity of an object, hence the setter method
should be private. Only Hibernate will assign identifiers when an object is saved. You
can see that Hibernate can access public, private, and protected accessor methods, as
well as (public, private, protected) fields directly. The choice is up to you and you
can match it to fit your application design.
The no-argument constructor is a requirement for all persistent classes as Hibernate
has to instanciate objects for you, using Java Reflection. The constructor can be
private, however, package visibility is required for runtime proxy generation and
efficient data retrieval.
We place this Java source file in a directory called src in our
development folder. The directory should now look like this:
+src
+de
+gloegl
+road2hibernate
Event.java]]>
In the next step, we tell Hibernate about this persisten class.
The mapping file
Hibernate needs to know how to load and store objects of our entity class.
This is where the Hibernate mapping file comes into play. The mapping file
tells Hibernate what table in the database it has to access, and what columns
in that table it should use.
The basic structure of a mapping file looks like this:
[...]
]]>
Note that the Hibernate DTD is very sophisticated. You can use it for
auto-completion of XML mapping elements and attributes in your editor or
IDE. You also should open up the DTD file in your text editor - it's the
easiest way to get an overview of all elements and attributes and see
the defaults, as well as some comments. Also note that Hibernate will not
load the DTD file from the web, as the URL might suggest, but first looks
into the classpath of your application. The DTD file is included in hibernate3.jar
as well as in the src/ directory of the Hibernate distribution.
We will ommit the DTD declaration in future examples to shorten the code.
Between the two hibernate-mapping tags, we include a
class element. All persistent entity classes (again, there
might be dependent classes later on, which are not first-class entities) need
such a mapping, to a table in our SQL database:
]]>
What we have done so far is telling Hibernate how to persist and load objects
of our class Event to the table EVENTS. Now
we continue with a mapping of the unique identifier property. In addition, as we
don't want to care about handling this identifier, we configure Hibernate's
identifier generation strategy:
]]>
The id element is the declaration of the identifer property,
name="id" declares the name of the Java property -
Hibernate will use getId() and setId() to
access it. The column attribute tells Hibernate which column of the
EVENTS table we use for this primary key. The nested
generator element specifies the identifier generation strategy
- in this case we use increment, which is a very simple in-memory
number generation method useful mostly for testing (and tutorials). Hibernate also
supports database generated, globally unique, as well as application assigned
identifiers.
Finally we have to include declarations for the persistent properties in
the mapping file. By default, no properties of the class are considered
persistent:
]]>
Just as with the id element, the name
attribute of the property element tells Hibernate which getter
and setter methods to use.
Why does the date property mapping include the
column attribute, but the title
doesn't? When the column attribute is ommitted, Hibernate
by default uses the property name as the column name. This works fine for
title. However, date is a reserved
keyword in most database, so we better map it to a different name.
The next interesting thing is that the title property lacks
a type attribute. The types we declare and use in the mapping
files are not, like you might expect, Java data types. They are also not SQL
database types. These types are so called Hibernate mapping types,
converters which can translate from Java to SQL data types and vice versa. Again,
Hibernate will try to determine the correct conversion and mapping type itself if
the mapping attribute is not present. In some cases this automatic detection (using
Reflection on the Java class) might not have the default you expect or need.
This is the case with the date property. Hibernate can't know if
the property will map to a SQL date, timestamp
or time column. We declare that we want to preserve full date
and time information by mapping the property with a timestamp.
This mapping file should be saved as Event.hbm.xml, right in
the directory where our Event Java source class is located.
The naming of mapping files can be arbitrary, however the hbm.xml
became convention in the Hibernate developer community. The directory structure
should now look like this:
+src
+de
+gloegl
+road2hibernate
Event.java
Event.hbm.xml]]>
We continue with the main configuration of Hibernate.
Hibernate configuration
As we now have the persistent class and the mapping file
in place, it is time to configure Hibernate. Before we do this, we will need
a database. HSQL DB, a java-based in-memory SQL Database, can be downloaded from
the HSQL DB website. Actually, you only need the hsqldb.jar
from the /lib/ directory of the download. Place this file in the lib directory
of the development folder.
Create a directory called data in the development
directory - this is where HSQL DB will store its data files.
Hibernate will connect to this database, so it needs connection information. The
connections will be made through a JDBC connection pool, which we also have to
configure. The Hibernate distribution contains several open source connection pools,
but we have decided to use the buil-in connection pool for this tutorial. Note that
you have to copy the required library into your classpath and use different
connection pooling settings if you want to use a production-quality third party
JDBC pooling software.
We can use a simple hibernate.properties file, a slightly
more sophisticated hibernate.cfg.xml file, or even complete
programmatic setup to configure Hibernate. Most users prefer the XML configuration
file:
org.hsqldb.jdbcDriver
jdbc:hsqldb:data/test
sa
1
org.hibernate.dialect.HSQLDialect
true
create
]]>
Note that this XML configuration uses a different DTD. We configure
Hibernate's SessionFactory - a global factory responsible
for a particular database. If you have several databases, use several
<session-factory> configurations, usually in
several configuration files.
The first four property elements contain the necessary
configuration for the JDBC connection. The dialect property
element specifies the particular SQL variant Hibernate generates.
The hbm2ddl.auto option turns on automatic generation of
database schemas - directly into the database. This can of course also be turned
off (by removing the config option) or redirected to a file for tuning, through
an Ant task. Finally, we point Hibernate to our mapping file(s).
Building
For convenience, we create a batch file in our development directory that
contains all commands necessary for compilation of the application. Under
Windows, this would look like this:
Place this file called build.bat in the development directory
and create the build subdirectory. If you are using Linux, you
can create an equivalent shell script. We'll migrate to an Ant build later.
Setup and helpers
It's time to load and store some Event objects, but first
we have to complete the setup with some infrastructure code. We have to startup
Hibernate (this means creating a SessoinFactory and store it
somewhere for easy access) and we will need some convenience methods for accessing
Hibernate Session's. A particular Session
represents a single-threaded unit of work, the SessionFactory
is a thread-safe global object, instantiated once.
We'll create a HibernateUtil helper class that takes care
of startup and makes Session handling convenient. This helper
classes will use the so called ThreadLocal Session pattern to
keep the current unit of work associated with the current thread. Let\s have a look
at it:
This class does not only produce the global SessionFactory in
it's static initializer (called once by the JVM when the class is loaded), but also
has a ThreadLocal variable that holds the
Session for the current thread. No matter when you call
HibernateUtil.currentSession(), it will always return the same
Hibernate unit of work in the same thread. A call to HibernateUtil.closeSession()
ends the unit of work currently associated with the thread.
Make sure you understand the Java concept of a thread-local variables before you
use this helper. A more powerful HibernateUtil helper can be found
in CaveatEmptor on http://caveatemptor.hibernate.org/ - as well as
in the book "Hibernate in Action".
Place HibernateUtil.java in the development source directory, next
to Event.java:
Now compile everything by calling build.bat in the development
directory. Run the application by executin in the development directory (all in one line):
This should produce the following output:
Let's place this line in a batch file, to save time. Put it in the development directory
as run.bat and add %1 %2 %3 %4 %5 at the end of the line.
We didn't see any errors in the run output but we still want to see what Hibernate is
doing during startup and want to get rid of the log4j warnings. We have to configure
log4j to solve both issues. Put a file called log4j.properties into
your src directory, next to hibernate.cfg.xml:
In addition, the following line has to be added to build.bat:
This configuration tells log4j to write all INFO level log output to the console.
Recompile the application by calling build.bat again, and rerun
it - you should now see detailed Hibernate startup info. Have a look and verify that
your Hibernate configuration options are all set correctly.
Loading and storing objects
Finally, we can use Hibernate to load and store objects. We write an
EventManager class with a main() method:
We read some arguments from the command line, and if the first argument is
"store", we take the second argument as the title of the event, create a new
Date and pass both to the store method:
We create a new Event object, and hand it over to Hibernate.
Hibernate now takes care of creating the SQL, and sending INSERTs
to the database. Let's spent a second on the Session and
Transaction-handling code. TODO: continue here
The method hsqlCleanup listed below performs some necessary shutdown code telling HsqlDB to remove all its lock-files and flush its logs. This is not a direct hibernate requirement, so this would not be necessary when using a "real" database.
Please not that all the transaction and session handling code in these examples is extremely unclean, mainly for shortness. Please don't use that in a production app. For a more detailed explanation on how to handle transactions properly see .
If we now run the application with run.bat store Party an Event object will be created an persisted to the database.
But now we want to list our stored events, so we modify the main method some more:
When the first argument is "list", we call listEvents() and print all Events contained in the returned list. listEvents() is where the interesting stuff happens:
What we do here is using a HQL (Hibernate Query Language) query to load all existing Event objects from the database. Hibernate will generate the appropriate SQL, send it to the database and populate Event objects with the data. You can create more complex querys with HQL of course, which we will see in later chapters.
So in this chapter we learned how to setup Hibernate, how to create a mapping for our classes, and how to store and retrieve objects using Hibernate.
That's it for the first chapter, in the next part we will replace our ugly build.bat with an ant-based build system.
Part 2 - Building with Ant
In this short chapter we will replace the ugly build.bat file we created with a nice little Ant build file. You will need to have Ant installed - get it from the Ant download page. How to install Ant will not be covered here. Please refer to the Ant manual. After you have installed Ant, we can start to create the buildfile. It will be called build.xml and placed directly in the development directory and will replace the build.bat (which you can delete).
A basic build file
A basic build file looks like this:
]]>
The project tags surround the whole buildfile. There are two attributes, the name attribute which gives a name for the project being built, and the default attribute which specifies the default target which will be run if we launch Ant without specifying a target.
Inside of the project tags, we have to give at least one target block, where we can tell Ant what to do - in this case, ant will do just nothing. You can now run the build by running ant on the command line inside the development directory.
You should get an output like this:
This tells us Ant did run successfully and which build file was used. The default target was run, which is why the compile: part of the output shows us the compile target was executed. We can however give Ant an explicit target to run by calling ant compile from the command line, which will run the compile target.
So now we want Ant to actually compile our classes. So we insert the javac task inside the target elements:
]]>
This will tell Ant to launch the java compiler and compile everything it can find under the the src directory and place the generated class files in the bin directory. However if we now run Ant, we will get a lot of compile errors, because the compiler can not find the hibernate classes. So we have to tell the compiler about the classpath to use, just as we did in the old build.bat:
]]>
This will tell Ant to find all files in the lib directory with .jar as file ending and add them to the classpath used for compilation. If you now run Ant, you should get an output like this:
ant
Buildfile: build.xml
compile:
[javac] Compiling 2 source files to C:\hibernateTutorial\part2\bin
BUILD SUCCESSFUL
Total time: 1 second ]]>
Dependant targets
Great, so now we got ant to compile our two java files. This however still leaves the log4j.properties and the mapping file, which are not copied to the bin directory. We will take care of this now by adding an additional target:
]]>
So this tells ant when it executes the copy-resources target to copy everything it can find in the src directory or in any directories below to the bin directory but exclude all java files anywhere under the src directory (this is what the ** in front of the / means).
So if you run Ant now, you will see ... actually nothing. Ant will execute the compile target and not touch our copy-resources target. So what we need to do now is to tell ant it has to execute copy-resources before the compile target - this is what the depends attribute of the target element is for:
]]>
So if you now execute ant you should see output like this:
So Ant has now executed both targets and copied our resources over to the bin directory. You will notice that ant does not print anything under the compile target. Ant notices that no source files have changed and does not compile them again. The same will happen for copy-resources - ant will not copy our files again unless we change them, or remove them from the bin directory.
Using Properties
So now we have a nice little build script in place. We could well go on from here. You will notice however that our directory names are spread all over the build file. Should we ever want to change them, we would have to change them all over the build file. We will solve this problem by using Ant property declarations:
]]>
So we can define our properties using the property tag, and can insert them anywhere in the build file using the name we declared for the property surrounded with ${}. Notice the ${basedir} property we use in the property declarations - this is a property predefined by Ant, which contains the path of the directory where Ant is executed.
In the next chapter, we will create associations between our classes using java collections.
Part 3 - Mapping Associations
As we now have mapped a single object, we are now going to add various object associations. For a starter, we will add users to our application, and store a list of participating users with every event. In addition, we will give each user the possibility to watch various events for updates. Every user will have the standard personal data, including a list of email addresses.
Mapping the User class
For the beginning, our User class will be very simple:
And the mapping in User.hbm.xml:
]]>
The hibernate.cfg.xml needs to be adjusted as well to add the new resource:
org.hsqldb.jdbcDriver
jdbc:hsqldb:data/test
sa
org.hibernate.dialect.HSQLDialect
true
org.hibernate.transaction.JDBCTransactionFactory
org.hibernate.cache.HashtableCacheProvider
update
]]>
An unidirectional Set-based association
So far this is only basic hibernate usage. But now we will add the collection of favorite events to the User class. For this we can use a simple java collection - a Set in this case, because the collection will not contain duplicate elements and the ordering is not relevant for us.
So our User class now looks like this:
Now we need to tell hibernate about the association, so we adjust the User.hbm.xmlmapping document:
]]>
As you can see, we tell Hibernate about the set property called favouriteEvents. The set element tells Hibernate that the collection property is a Set. We have to consider what kind of association we have: Every User my have multiple favorite events, but every Event may be a favorite of multiple users. So we have a many-to-many association here, which we tell Hibernate using the many-to-many tag. For many to many associations, we need an association table where hibernate can store the associations. The table name can be configured using the table attribute of the set element. The association table needs at least two columns, one for every side of the association. The column name for the User side can be configured using the key element. The column name for the Event side is configured using the column attribute of the many-to-many element.
So the relational model used by hibernate now looks like this:
| *EVENT_UID | | |
| DATE | | *USER_UID | <--> | *UID |
| EVENTTITLE | |__________________| | AGE |
|_____________| | FIRSTNAME |
| LASTNAME |
|_____________|
]]>
Modifying the association
As we now have mapped the association, modifying it in EventManager is very easy:
After loading an User and an Event with Hibernate, we can simply modify the collection using the normal collection methods. As you can see, there is no explicit call to session.update() or session.save(), Hibernate automatically detects the collection has been modified and needs to be saved.
Sometimes however, we will have a User or an Event loaded in a different session. This is of course possible to:
This time, we need an explicit call to update - Hibernate can't know if the object actually changed since it was loaded in the previous session. So if we have an object from an earlier session, we must update it explicitly. If the object gets changed during session lifecycle we can rely on Hibernates automatic dirty checking.
Since Hibernate 2.1 there is a third way - the object can be reassociated with the new session using session.lock(object, LockMode.NONE):
Collections of Values
Often you will want to map collections of simple value types - like a collections of Integers or a collection of Strings. We will do this for our User class with a collection of Strings representing email addresses. So we add another Set to our class:
Next we will add the mapping of the Set to our User.hbm.xmlmapping document:
]]>
As you can see, the new set mapping looks a lot like the last one. The difference is the element part, which tells Hibernate that the collection does not contain an association with a mapped class, but a collection of elements of type String. Once again, the table attribute of the set element determines the table name. The key element determines the column name in the USER_EMAILS table which establishes the relation to the USERS table. The column attribute in the element element determines the column name where the String values will be actually stored.
So now our relational model looks like this:
| *EVENT_UID | | | | *ID |
| DATE | | *USER_UID | <--> | *UID | <--> | USER_UID |
| EVENTTITLE | |__________________| | AGE | | EMAIL |
|_____________| | FIRSTNAME | |_____________|
| LASTNAME |
|_____________|
]]>
Using value collections
Using value collections works the same way as we have already seen:
As you see, you can use the mapped collection just like every java collection. Hibernates automatic dirty detection will do the rest of the job. For objects from another session - or disconnected objects, as we will call them from now - the same as above aplies. Explicitly update them, or reassociate them before updating using session.lock(object, LockMode.NONE).
Bidirectional associations using Sets
Next we are going to map a bidirectional association - the User class will contain a list of events where the user participates, and the Event class will contain a list of participating users. So first we adjust our classes:
The mapping for a bidirectional association looks very much like a unidirectional one, except the set elements are mapped for both classes:
]]>
As you see, this are normal set mappings in both mapping documents. Notice that the column names in key and many-to-many are swapped in both mapping documents. The most important addition here is the inverse="true" attribute in the set element of the User mapping.
What this means is the other side - the Event class - will manage the relation. So when only the Set in the User class is changed, this will not get perstisted. Also when using explicit update for detatched objects, you need to update the one not marked as inverse. Let's see an example:
Using bidirectional mappings
At first it is important to know that we are still responsible for keeping our associations properly set up on the java side - that means if we add an Event to the eventsJoined Set of an User object, we also have to add this User object to the participatingUsers Set in the Event object. So we will add some convenience methods to the Event class:
Notice that the get and set methods for participatingUsers are now protected - this allows classes in the same package and subclasses to still access the methods, but prevents everybody else from messing around with the collections directly. We should do the same to the getEventsJoined() and setEventsJoined() methods in the User class.
Now using the association in EventManager is very easy:
In the next chapter we will integrate Hibernate with Tomcat and WebWork to create a better test environment - as you will notice when you look at the code, the EventManager class is really ugly now.
Part 4 - Tomcat and WebWork
In this chapter we will finally get rid of our ugly command-line-based test application and integrate Tomcat, WebWork and Hibernate to create a little web-based application.
The first step for you is to install Tomcat - you can download it here. You can find documentation and install instructions for Tomcat here.
Restructuring the development directory
At first, we will restructure our working directory, to keep the parts of our application nicely separated:
We moved our classes and mappings to the data subdirectory of road2hibernate. Of course we need to adjust our package declaration in the java files and the classnames in the mapping files.
In addition, we created various new directories:
src/de/gloegl/road2hibernate/actions will contain the source code for our WebWork actions.
config will contain the config files which will later be placed in WEB-INF/config of our web app.
static-web will contain all static content of our application, like html and image files.
views will contain our view files which contain the html later displayed to the user.
As we will use WebWork for our application and Velocity as template engine for the views, you will need to get WebWork from here. You will need the webwork-2.1.7.jar from the WebWork download, and all jar files in the lib/core folder of the WebWork distribution. Place all of them into the lib directory of the development dir.
Configuring WebWork
Now we will configure our application to use WebWork. At first we need a web.xml which we will place in the config directory:
Eventmanager
webwork
com.opensymphony.webwork.dispatcher.ServletDispatcher
1
velocity
com.opensymphony.webwork.views.velocity.WebWorkVelocityServlet
10
webwork
*.action
velocity
*.vm
index.html
]]>
This files contains all the servlets and servlet mappings which WebWork needs to run.
In addition, we will need a xwork.xml file, which is placed directly in the src dir:
]]>
This file contains only the declaration of the packages where WebWork will look for its actions.
Updating the build process
Now we will make our build process place all the files together and generate the appropriate structure for the web application. We update our build.xml:
... ]]>
Running this target will create a directory called war, which will contain the web application just like it will later be structured in the war file. After running this target, the war directory will look like this:
]]>
Now we will add Tomcat specific tasks to our build file, so we can directly install our application into Tomcat using Ant. You need to adjust the example to your environment. Modify the build.xml again:
....
...
]]>
So now startup Tomcat and run ant install from the commandline - this will install the application to Tomcat. Now you should be able to access the eventmanager application by pointing your browser to http://localhost:8080/eventmanager/ - however you will only get a directory listing produced by Tomcat. We will now have to create some content for the application to display.
A first WebWork action
Our first WebWork action will be very simple - it will do nothing so far but forwarding to a view. We create /src/de/gloegl/road2hibernate/actions/EventList.java:
The class extends ActionSupport but does not override any methods. So this will rely on the default behavior of ActionSupport: The action will forward to the view defined as the SUCCESS view. This is what we still have to do in the xwork.xml file:
/WEB-INF/views/eventlist.vm
]]>
This defines an action called eventlist which will be handled by our EventList class. In addition, the success view gets defined. We now have to write the eventlist.vm file, which will be placed in the views folder - Ant will copy it to the correct location.
Event List
Successful