Our use case is sweet. We will use an example from the honey production. You need a lot of bees to get honey. Our use case includes Honey and Bee as model and a 1:n relation from Bee to Honey. Using object oriented terms: There is a 1:n association between the class Bee and Honey.

We will create a class Honey which is mapped to the table honey in the database and a class Bee mapped to the table bee. The following picture shows our database schema.

In order to get complete our application, we must undertake the following steps:

Create a new project using your development environment. I used Eclipse for this example. Using Eclipse press the keys Ctrl+n (Strg+n) to create a new project. Select Java project. We will call it FirstHibernateExample.

Create a new class named Honey in the package de.laliluna.example. Our class has four fields:

Furthermore we need:

Java version: I used Java generics, which was introduced with Version 5 (alias 1.5).

Annotations always starts with @.

Your source code should look like the code below:

Honey class. 

package de.laliluna.example;

import java.io.Serializable;
import java.util.HashSet;
import java.util.Set;

public class Honey implements Serializable {

   private Integer id;
   private String name;
   private String taste;
   private Set<Bee> bees = new HashSet<Bee>();

   public Honey() {
   }
   public Honey(String name, String taste) {
      this.name = name;
      this.taste = taste;
   }
   public Integer getId() {
      return id;
   }
   public void setId(Integer id) {
      this.id = id;
   }
   public String getName() {
      return name;
   }
   public void setName(String name) {
      this.name = name;
   }
   public String getTaste() {
      return taste;
   }
   public void setTaste(String taste) {
      this.taste = taste;
   }
   public Set<Bee> getBees() {
      return bees;
   }
   public void setBees(Set<Bee> bees) {
      this.bees = bees;
   }
   public String toString() {
      return "Honey: " + getId() + " Name: " + getName() + " Taste: "
            + getTaste();
   }
}

Create a class Bee with the fields:

The field id is once again the primary key. Please don’t forget the important requirements, I stated above.

Bee class. 

package de.laliluna.example;

import java.io.Serializable;
import java.text.MessageFormat;

public class Bee implements Serializable {

   private Integer id;
   private String name;
   private Honey honey;

   public Bee() {
   }
   public Bee(String name) {
      this.name = name;
   }
   public Integer getId() {
      return id;
   }
   public void setId(Integer id) {
      this.id = id;
   }
   public String getName() {
      return name;
   }
   public void setName(String name) {
      this.name = name;
   }
   public Honey getHoney() {
      return honey;
   }
   public void setHoney(Honey honey) {
      this.honey = honey;
   }
   public String toString() {
      return MessageFormat.format("{0}: id={1}, name={2}", new Object[] {
            getClass().getSimpleName(), id, name });
   }
}

The Hibernate configuration will define

Create a new file named hibernate.cfg.xml in your src directory.

You have to choices to map documents: Annotations and XML. They’ll be discussed later in this book. I explain both approaches for this example.

If you can use Java 1.5 alias 5 or later, I recommend to use annotations.

Below you can find a configuration for PostgreSQL using annotation based mapping. Afterwards, I will explain required changes for other databases and XML based mapping. Do not forget to change the username and the password to suit your database configuration.

hibernate.cfg.xml. 

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
     "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
     "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
   <session-factory>
      <!--  postgre SQL configuration-->
      <property name="connection.url">
         jdbc:postgresql://localhost:5432/learninghibernate
      </property>
      <property name="connection.username">postgres</property>
      <property name="connection.password">p</property>
      <property name="connection.driver_class">
         org.postgresql.Driver
      </property>
      <property name="dialect">
         org.hibernate.dialect.PostgreSQLDialect
      </property>
      <property name="cache.provider_class">
         org.hibernate.cache.NoCacheProvider
      </property>
      <property name="current_session_context_class">thread</property>
      <property name="hibernate.show_sql">true</property>
      <property name="hibernate.hbm2ddl.auto">create</property>
      <mapping class="de.laliluna.example.Honey" />
      <mapping class="de.laliluna.example.Bee" />
   </session-factory>
</hibernate-configuration>

At the beginning of the configuration, you can find the database connection. Afterwards, the dialect is specified. Hibernate will translate all queries into this dialect. Then, I configured the cache implementation and the session and transaction behaviour. The setting hbm2ddl.auto instructs Hibernate to update or create the table schema when the configuration is initialized. You only have to create the database.

The tag <mapping class> at the end of the file defines which classes are mapped using annotations. If you want to use XML based mappings then you need to reference the XML mapping files instead:

<mapping resource="de/laliluna/example/Honey.hbm.xml" />
<mapping resource="de/laliluna/example/Bee.hbm.xml" />

<property name="connection.url">jdbc:mysql://localhost/learninghibernate</property>
<property name="connection.username">root</property>
<property name="connection.password">r</property>
<property name="connection.driver_class">com.mysql.jdbc.Driver</property>
<property name="dialect">org.hibernate.dialect.MySQLDialect</property>

With the mapping we define in which table column a field of a class is saved. As already stated, we have two options for the mapping. The first one is based on annotation, it is new and the future and I recommend to use it. But it requires Java 5. The second one is based on XML mapping files. I will explain both:

.....
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.OneToMany;
import javax.persistence.SequenceGenerator;
@Entity
@SequenceGenerator(name = "honey_seq", sequenceName = "honey_id_seq")
public class Honey implements Serializable {
   @Id
   @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="honey_seq")
   private Integer id;
   private String name;
   private String taste;
   @OneToMany(mappedBy="honey")
   private Set<Bee> bees = new HashSet<Bee>();

.......
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.JoinColumn;
import javax.persistence.ManyToOne;
import javax.persistence.SequenceGenerator;

@Entity
public class Bee implements Serializable {
   @Id
   @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "bee_gen")
   @SequenceGenerator(name = "bee_gen", sequenceName = "bee_id_seq")
   private Integer id;
   private String name;

   @ManyToOne
   @JoinColumn
   private Honey honey;

   @Id
   @GeneratedValue(strategy=GenerationType.AUTO)
   private Integer id;

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
 "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd" >
<hibernate-mapping package="de.laliluna.example">
  <class name="Honey" table="thoney" >
      <id name="id" column="id">
      <generator class="sequence">
            <param name="sequence">honey_id_seq</param>
         </generator>
      </id>
      <property name="name" column="name" type="string" />
      <property name="taste" column="taste" type="string" />
      <set name="bees" inverse="true">
        <key column="honey_id"></key>
       <one-to-many class="Honey" />
      </set>
   </class>
</hibernate-mapping>

<generator class="native"/>

mvn dependency:resolve

+- junit:junit:jar:4.5:test
+- org.slf4j:slf4j-log4j12:jar:1.6.0:compile
|  +- org.slf4j:slf4j-api:jar:1.6.0:compile
|  \- log4j:log4j:jar:1.2.14:compile
+- c3p0:c3p0:jar:0.9.1.2:compile
+- org.hibernate:hibernate-core:jar:3.6.4.Final:compile
|  +- antlr:antlr:jar:2.7.6:compile
|  +- commons-collections:commons-collections:jar:3.1:compile
|  +- dom4j:dom4j:jar:1.6.1:compile
|  +- org.hibernate:hibernate-commons-annotations:jar:3.2.0.Final:compile
|  +- org.hibernate.javax.persistence:hibernate-jpa-2.0-api:jar:1.0.0.Final:compile
|  \- javax.transaction:jta:jar:1.1:compile
+- javassist:javassist:jar:3.9.0.GA:compile

+- org.hibernate:hibernate-ehcache:jar:3.6.4.Final:compile
+- net.sf.ehcache:ehcache-core:jar:2.4.2:compile
+- org.hibernate:hibernate-validator:jar:4.1.0.Final:compile
|  \- javax.validation:validation-api:jar:1.0.0.GA:compile

+- postgresql:postgresql:jar:8.3-603.jdbc3:compile
\- hsqldb:hsqldb:jar:1.8.0.7:compile

A session factory is important for Hibernate. As the name already indicates, it creates Hibernate sessions for you. A session is all you need to access a database using Hibernate. In addition, a session factory initialises your Hibernate configuration.

We need to distinguish Annotation and XML once again. Here comes the Annotation version:

Create a class named InitSessionFactory in the package de.laliluna.hibernate and add the source code below. This class guaranties that there is only once instance (Singleton pattern) and that the initialisation happens only once when the class is loaded.

package de.laliluna.hibernate;

import org.hibernate.SessionFactory;
import org.hibernate.cfg.AnnotationConfiguration;

public class InitSessionFactory {
   /** The single instance of hibernate SessionFactory */
   private static org.hibernate.SessionFactory sessionFactory;
   private InitSessionFactory() {
   }

   static {
      final Configuration cfg = new Configuration();
      cfg.configure("/hibernate.cfg.xml");
      sessionFactory = cfg.buildSessionFactory();
   }
   public static SessionFactory getInstance() {
      return sessionFactory;
   }
}

Hibernate uses log4j as logging output. As you can see above we added the log4j library. This library needs a configuration file in the source directory or it welcomes you with the following error.

log4j:WARN No appenders could be found for logger (TestClient).
log4j:WARN Please initialize the log4j system properly.

Create a file named log4j.properties in the root directory. We will configure a simple logging output in the Console.

# configuration is adapted from www.hibernate.org
### direct log messages to stdout ###
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.Target=System.out
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p %c{1}:%L - %m%n
### set log levels - for more verbose logging change 'info' to 'debug' ###
log4j.rootLogger=debug, stdout
log4j.logger.org.hibernate=info
#log4j.logger.org.hibernate=debug
### log just the SQL
log4j.logger.org.hibernate.SQL=debug

Create a database with MySql or PostgreSQL or anything you like. Call it firsthibernate. This is the same database name, we used in the hibernate.cfg.xml.

We have defined in hibernate.cfg.xml that the tables should be recreated each time when the Hibernate configuration is initialized.

<property name="hibernate.hbm2ddl.auto">create</property>

The setting create will drop and create any tables. It is only suitable during development. You might use update as well. In this case Hibernate tries to update existing tables or create missing tables. This works in most cases but not always. Therefore, I recommend to disable this for production.

We will create a Java class, which will create, update, delete and query our data.

Create a Java Class TestExample in the package de.laliluna.example.

Please look through the source code carefully and try it. I will just give you some general informations before:

In the main method we call other methods creating, updating, deleting and querying data.

package de.laliluna.example;

import java.util.Iterator;
import java.util.List;
import org.apache.log4j.Logger;
import org.hibernate.Criteria;
import org.hibernate.FetchMode;
import org.hibernate.Hibernate;
import org.hibernate.Session;
import org.hibernate.Transaction;
import de.laliluna.hibernate.InitSessionFactory;

public class TestExample {
   private static Logger log = Logger.getLogger(TestExample.class);
   public static void main(String[] args) {
      /* clean tables */
      clean();

      /* simple create example */
      createHoney();

      /* relation example */
      createRelation();

      /* delete example */
      delete();

      /* update example */
      update();

      /* query example */
      query();
   }

The method createHoney creates a new object and saves it in the database by calling session.save.

private static Honey createHoney() {
      Honey forestHoney = new Honey();
      forestHoney.setName("forest honey");
      forestHoney.setTaste("very sweet");

      Session session = InitSessionFactory.openSession();
      Transaction tx = session.beginTransaction();
      session.save(forestHoney);
      tx.commit();
      session.close();
      return forestHoney;
   }

The method update creates a new object using our last method, changes the name and updates the object using session.update.

private static void update() {
      Honey honey = createHoney();
      Session session = InitSessionFactory.openSession();
      Transaction tx = session.beginTransaction();
      honey.setName("Modern style");
      session.update(honey);
      tx.commit();
      session.close();
   }

The method delete creates an object and deletes it by calling session.delete.

private static void delete() {
      Honey honey = createHoney();
      Session session = InitSessionFactory.openSession();
      Transaction tx = session.beginTransaction();
      session.delete(honey);
      tx.commit();
      session.close();
   }

The tables are emptied with the method clean. The method session.createQuery creates a new query and runs it by calling executeUpdate.

   private static void clean() {
      Session session = InitSessionFactory.openSession();
      Transaction tx = session.beginTransaction();
      session.createQuery("delete from Bee").executeUpdate();
      session.createQuery("delete from Honey").executeUpdate();
      tx.commit();
      session.close();
   }

The method createRelation shows, how to create objects and set an association between these objects. This will write a foreign key relation to the database.

private static void createRelation() {
      Session session = InitSessionFactory.openSession();
      Transaction tx = session.beginTransaction();
      Honey honey = new Honey();
      honey.setName("country honey");
      honey.setTaste("Delicious");
      session.save(honey);
      Bee bee = new Bee("Sebastian");
      session.save(bee);

      /* create the relation on both sides */
      bee.setHoney(honey);
      honey.getBees().add(bee);
      tx.commit();
      session.close();
   }

The method query shows how to query all honeys in the database. The call to session.createQuery creates the query and list() runs the query and returns a list of Honey objects.

   private static void query() {
      Session session = InitSessionFactory.openSession();
      Transaction tx = session.beginTransaction();
      List honeys = session.createQuery("select h from Honey as h").list();
      for (Iterator iter = honeys.iterator(); iter.hasNext();) {
         Honey element = (Honey) iter.next();
         log.debug(element);
      }
      tx.commit();
      session.close();
   }

This was a fast example and it is not required to have understood anything.

MyEclipse is a plugin provided by Genuitec on http://www.myeclipseide.com/ . I use it for development of all kinds of Web applications including Hibernate, EJB 2 and EJB3. MyEclipse is very up-do-date with the support of current versions of web frameworks, EJB and of course Hibernate.

Create a webproject first and open the context menu of the project (click with right mouse button on the project in the package view). Select add Hibernate capabilities.

The wizard let you select the Hibernate version and add the needed libraries to your project.

I recommend to add the libraries to the build path and not to copy them to the lib folder of the application. This will allow to set up different configurations for deployment during development and staging.

To stage your finished application you should pack all the libraries with your project. You can configure in the project properties to deploy user libraries like the MyEclipse library in your application server.

During development, I prefer to copy all the Hibernate and Struts libraries to the shared library directory of the application server. I configure the MyEclipse configuration in the project properties to not deploy any user libraries. This makes redeployment very fast.

Lets continue with the wizard. You can select an existing Hibernate configuration file hibernate.cfg.xml or you can create a new one.

Then you can select a database connection profile for a JDBC connection or select a JNDI datasource. A connection profile is the complete configuration of a JDBC database with connection string, user name, password and DB driver.

A connection profile can be used for the database browser as well to see tables, triggers, columns. The database browser allows to generate Hibernate mappings from existing tables as well.

Finally you can create a session factory. I prefer to use my own session factory as it is simpler but the MyEclipse session factory works perfectly, as well.

Open the View DB Browser (MyEclipse). If you cannot find it open the „Show View“ Dialog and select in the MyEclipse Enterprise Workbench the DB Browser.

Open the connection profile you specified before.

Select the two tables we have just created. Right click and choose Create Hibernate Mapping.

Follow the wizard to select where to create the mapping files and classes. You can even generate DAOs.