I’m just starting to build out an app that uses Hibernate. I started with Hibernate mapping files but switched over to using JPA annotations. I wanted to record the changes I needed to make and also a non-obvious exception (to my newbie eyes) and the solution.

When using Hibernate with mapping files you’ll have files like:

org/terracotta/reference/exam/domain/User.java
org/terracotta/reference/exam/domain/User.hbm.xml
org/terracotta/reference/exam/domain/HibernateUtil.java
hibernate.cfg.xml
log4j.properties

To switch to annotations, you’ll need to:

1. Add hibernate-annotations and JPA jars
2. Annotate your classes
3. Modify hibernate.cfg.xml to use classes instead of mapping files
4. Modify your HibernateUtil class to use a different configuration (this is the step that tripped me up)

To add the right jars, I’m using Maven and added the following additional dependencies:

<dependency>
  <groupId>javax.persistence</groupId>
  <artifactId>persistence-api</artifactId>
  <version>1.0</version>
</dependency>
<dependency>
  <groupId>org.hibernate</groupId>
  <artifactId>hibernate-annotations</artifactId>
  <version>3.3.1.GA</version>
</dependency>

There are many fine resources available on JPA annotations so I’m not going to discuss this in detail. You’ll have something that looks like this:

@Entity
@Table(name = “USERS”)
public class User {

@Id @GeneratedValue
@Column(name = “USER_ID”)
private Long id;

@Column(name = “FIRST_NAME”)
private String firstName;

@Column(name = “LAST_NAME”)
private String lastName;

@Column(name = “EMAIL”)
private String email;

// etc
}

To update your hibernate.cfg.xml file, you’ll want to change lines like this:

  <mapping resource="org/terracotta/reference/exam/domain/User.hbm.xml"/>

to something like this:

  <mapping class="org.terracotta.reference.exam.domain.User">

If you did all that and stopped there, you might see an exception like this:

Exception in thread "main" java.lang.ExceptionInInitializerError
	at org.terracotta.reference.exam.domain.HibernateUtil.<clinit>(HibernateUtil.java:15)
	at org.terracotta.reference.exam.domain.Main.main(Main.java:12)
Caused by: org.hibernate.MappingException: An AnnotationConfiguration instance is required to use <mapping class="org.terracotta.reference.exam.domain.User"/>
	at org.hibernate.cfg.Configuration.parseMappingElement(Configuration.java:1600)
	at org.hibernate.cfg.Configuration.parseSessionFactory(Configuration.java:1555)
	at org.hibernate.cfg.Configuration.doConfigure(Configuration.java:1534)
	at org.hibernate.cfg.Configuration.doConfigure(Configuration.java:1508)
	at org.hibernate.cfg.Configuration.configure(Configuration.java:1428)
	at org.hibernate.cfg.Configuration.configure(Configuration.java:1414)
	at org.terracotta.reference.exam.domain.HibernateUtil.<clinit>(HibernateUtil.java:13)

And, like me, you would be puzzled. It turns out that when using annotations you need to use AnnotationConfiguration, which is a subclass of Configuration, specific to annotations. So, your HibernateUtil might look like this instead:

package org.terracotta.reference.exam.domain;

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

public class HibernateUtil {
private static SessionFactory sessionFactory;

static {
try {
sessionFactory = new AnnotationConfiguration().configure().buildSessionFactory();
} catch(Throwable t) {
throw new ExceptionInInitializerError(t);
}
}

public static SessionFactory getSessionFactory() {
return sessionFactory;
}

public static void shutdown() {
getSessionFactory().close();
}
}

Hope that helps someone down the line…