This tutorial refines what is presented in the Tutorial section that is included with the Hibernate documentation for the 3.6.2-Final release. I had a few problems while working through the tutorial contained in the documentation, thus this is my attempt to simplify things so that others can also understand how Hibernate works. The code listings contain commands that you enter at the command line. The ‘$’ character indicates that this is the prompt. Don’t type it. The code is also available as a full download if you don’t feel like entering it in increments.
First, we need to do a simple configuration setup to get Maven working. I assume that you have Maven installed. If you don’t grab a copy and install it. Copy the settings.xml (bellow) file into your Maven directory. You need to configure Maven so that it can see the JBoss repository for this tutorial to work. The file that needs modification is located in the $HOME/.m2/settings.xml . Download the copy I have and place it there. If you are already a Maven user and have custom settings, make the modifications I included in this settings.xml file.
$ wget http://www.brie.com/brian/hibernate/start/settings.xml
$ cp settings.xml $HOME/.m2
Make a directory for your first Hibernate Project
$ mkdir myfirst-hibernate
This is the way you enter code. In this directory, you are going to place a pom.xml, which you can download from my site. The pom.xml is the Maven file that tells what files are in the project, the structure, etc.
$ cd myfirst-hibernate
$ wget http://www.brie.com/brian/hibernate/start/pom.xml
Now, start the database server using the following command (all on one line):
$ mvn exec:java -Dexec.mainClass="org.hsqldb.Server" -Dexec.args="-database.0 file:target/data/tutorial"
Start the DB Manager in a separate window from the same directory. Enter the following (all on one line):
$ mvn exec:java -Dexec.mainClass="org.hsqldb.util.DatabaseManagerSwing" -Dexec.args="-url jdbc:hsqldb:hsql://localhost/ -driver org.hsqldb.jdbcDriver"
Now you have a pom.xml file that details the dependencies for your project, a running database server (HSQLDB) and the database manager. Other than that, you have no code. We will fix that. Open yet a third terminal window. Your current working directory should be that of the pom.xml. Do an ls command just to be sure. Now create the following directories. If you are not used to using Maven, the source files go into src/main/java and the accompanying .hbm.xml files go into a resource directory.
$ mkdir -p src/main/java/org/hibernate/tutorial/domain
$ mkdir -p src/main/java/org/hibernate/tutorial/util
$ mkdir -p src/main/resources/org/hibernate/tutorial/domain
We will now create our first Java class: Event.java. To simplify this blog, just download the class file and either copy it to the directory or type it in. I assume that you are in the directory that has the pom.xml file.
$ wget http://www.brie.com/brian/hibernate/start/Event.java
$ mv Event.java src/main/java/org/hibernate/tutorial/domain
Now, we will add a corresponding mapping file from Hibernate that will map an Event object to the database. The mapping file maps each attribute to a column, yet when it comes to creating an identifier for the object, we let Hibernate handle it. The mapping file goes into a parallel directory to the that of the class.
$ wget http://www.brie.com/brian/hibernate/start/Event.hbm.xml
$ mv Event.hbm.xml src/main/resources/org/hibernate/tutorial/domain
The project now has a class (Event.java), and a mapping file, but now it misses the file that tells hibernate what database to connect to and what type of database it is. It is the main configuration file, hibernate.cfg.xml . It also tells Hibernate to create the database schema automatically, something good for a tutorial, but not quite as wise for production. As before, download it and move it to the proper place.
$ wget http://www.brie.com/brian/hibernate/start/hibernate.cfg.xml
$ mv hibernate.cfg.xml src/main/resources
Compile your code using Maven. It should compile without errors, assuming the repository, etc has not changed since this was written. You should execute this command at the same location as the pom.xml file is located.
$ mvn compile
If all is well, you now have a way to connect. The original tutorial off which this is based uses a utility class. I believe a different approach now works, but we will follow what works. Download the utility class and move it to the proper area. It uses a singleton pattern.
$ wget http://www.brie.com/brian/hibernate/start/HibernateUtil.java
$ mv HibernateUtil.java src/main/java/org/hibernate/tutorial/util
Now is the time to do something with this domain that we have created. We will write a small program that creates an Event object. The event will get saved to the database automatically. First, get the code, for the EventManager, compile, and then run it. Refresh the dbmanager tool so that you can see the tables and query for your newly created Event.
$ wget http://www.brie.com/brian/hibernate/start/EventManager1.java
$ mv EventManager1.java src/main/java/org/hibernate/tutorial/EventManager.java
$ mvn compile
$ mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="store"
$ mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="list"
If all worked well, check the graphical DataBase manager and query for the new Event. Enter the text, and press execute. You may have to press the refresh button to see the newly created table in the HSQLDB database.
select * from events
This concludes this brief introduction to using Hibernate. I will add the second class in another blog where I will add the Person class presented in the original tutorial and the web application, for now. You can grab the full code from here. Just remember to also add the settings.xml to your Maven configuration.
-brian
Back to March 21, 2011 LUGOD meeting presentation page: MyForth-Arduino & Hibernate Java ORM