Hibernate.orgCommunity Documentation

Hibernate Getting Started Guide


February 8, 2012

Working with both Object-Oriented software and Relational Databases can be cumbersome and time consuming. Development costs are significantly higher due to a paradigm mismatch between how data is represented in objects versus relational databases. Hibernate is an Object/Relational Mapping solution for Java environments. The term Object/Relational Mapping refers to the technique of mapping data from an object model representation to a relational data model representation (and visa versa). See http://en.wikipedia.org/wiki/Object-relational_mapping for a good high-level discussion.


While having a strong background in SQL is not required to use Hibernate, having a basic understanding of the concepts can greatly help you understand Hibernate more fully and quickly. Probably the single best background is an understanding of data modeling principles. You might want to consider these resources as a good starting point:

Hibernate not only takes care of the mapping from Java classes to database tables (and from Java data types to SQL data types), but also provides data query and retrieval facilities. It can significantly reduce development time otherwise spent with manual data handling in SQL and JDBC. Hibernate’s design goal is to relieve the developer from 95% of common data persistence-related programming tasks by eliminating the need for manual, hand-crafted data processing using SQL and JDBC. However, unlike many other persistence solutions, Hibernate does not hide the power of SQL from you and guarantees that your investment in relational technology and knowledge is as valid as always.

Hibernate may not be the best solution for data-centric applications that only use stored-procedures to implement the business logic in the database, it is most useful with object-oriented domain models and business logic in the Java-based middle-tier. However, Hibernate can certainly help you to remove or encapsulate vendor-specific SQL code and will help with the common task of result set translation from a tabular representation to a graph of objects.

The Hibernate team provides release bundles hosted on the SourceForge File Release System, in ZIP and TGZ formats. Each release bundle containsJARs, documentation, source code, and other information.

You can download releases of Hibernate, in your chosen format, from the list at http://sourceforge.net/projects/hibernate/files/hibernate3/.

  • hibernate3.jar is an aggregation of all the Hibernate Core classes. This must be included in your project's classpath.

  • The lib/required/ directory contains JARs Hibernate requires. All the jars in this directory must also be included in your project's classpath as well.


    The slf4j JAR has additional requirements for it to function properly. The exact requirements depend on your logging back-end. See slf4j site for details.

  • The /lib/jpa/ directory contains the JPA API JAR. This JAR needs to be in your project's classpath if you want to use the JPA APIs or JPA annotations.


The authoritative repository for Hibernate artifacts is the JBoss Maven repository. The team responsible for the JBoss Maven repository maintains a number of Wiki pages that contain important information.

Maven Repository Wiki Pages

Hibernate produces a number of artifacts (all under the org.hibernate groupId):

Hibernate Artifacts under groupId org.hibernate


The main artifact, which contains all the Hibernate classes, in packageorg.hibernate. You need these to build applications using the native Hibernate APIs. It includes capabilities for using native Hibernate mapping in hbm.xml files, as well as annotations.


Represents Hibernate's implementation of JPA, as specified at http://jcp.org/en/jsr/detail?id=317.

This artifact depends on hibernate-core


An optional module that provides historical auditing of changes to your entities.

This artifact depends on both hibernate-core and hibernate-entitymanager.


Provides integration between Hibernate and the C3P0 connection pool library. See http://sourceforge.net/projects/c3p0/ for information about C3P0.

This artifact depends on hibernate-core, but is generally included in a project as a runtime dependency. It pulls in the C3P0 dependencies automatically.


Provides integration between Hibernate and the Proxool connection pool library. See http://proxool.sourceforge.net/ for more information about this library.

This artifact depends on hibernate-core, but is generally included in a project as a runtime dependency. It pulls in the Proxool dependencies automatically..


Privides integration between Hibernate and EhCache, as a second-level cache. See http://ehcache.sourceforge.net/ for more information aboutEhCache.

This artifact depends on hibernate-core, but is generally included in a project as a runtime dependency. It pulls in the Ehcache dependencies automatically.


Provides integration between Hibernate and Infinispan, as a second-level cache. See http://jboss.org/infinispan for more information about Infinispan.

This artifact depends on hibernate-core, but is generally included in a project as a runtime dependency. It pulls in the Infinispan dependencies automatically.


Provides integration between Hibernate and JBossCache, as a second-level cache. See http://jboss.org/jbosscache for information about JBossCache.

This artifact depends on hibernate-core, but is generally included in a project as a runtime dependency. It pulls in the JBossCache dependencies automatically.


Provides integration between Hibernate and OSCache as a second-level cache. See http://www.opensymphony.com/oscache/ for information about OSCache.

This artifact depends on hibernate-core, but is generally included in a project as a runtime dependency. It pulls in the OSCache dependencies automatically.


Provides integration between Hibernate and SwarmCache, as a second-level cache. See http://swarmcache.sourceforge.net/ for more information about SwarmCache.

This artifact depends on hibernate-core, but is generally included in a project as a runtime dependency. It pulls in the SwarmCache dependencies automatically.

This tutorial is located within the download bundle under basic and illustrates

  • using Hibernate mapping files (hbm.xml) to provide mapping information

  • using the native Hibernate APIs

The hbm.xml mapping file for this tutorial is the classpath resource org/hibernate/tutorial/hbm/Event.hbm.xml as we saw in Section 2.1, “The Hibernate configuration file”

Hibernate uses the mapping metadata to find out how to load and store objects of the persistent class. The Hibernate mapping file is one choice for providing Hibernate with this metadata.

Functions of the class mapping element

  1. The name attribute (combined here with the package attribute from the containing hibernate-mapping element) names the FQN of the class you want to define as an entity.

  2. The table attribute names the database table which contains the data for this entity.

Instances of the Event class are now mapped to rows in the EVENTS table.

Hibernate uses the property named by the id element to uniquely identify rows in the table.


It is not strictly necessary for the id element to map to the table's actual primary key column(s), but it is the normal convention. Tables mapped in Hibernate do not even need to define primary keys. However, the Hibernate team strongly recommends that all schemas define proper referential integrity. Therefore id and primary key are used interchangeably throughout Hibernate documentation.

The id element here identifies the EVENT_ID column as the primary key of the EVENTS table. It also identifies the id property of the Event class as the property containing the identifier value.

The generator element nested inside the id element informs Hibernate about which strategy is used to generated primary key values for this entity. In this example a simple incrementing count is used.

The two property elements declare the remaining two properties of the Event class: date andtitle. The date property mapping includes the column attribute, but the title does not. In the absence of a column attribute, Hibernate uses the property name as the column name. This is appropriate for title, but since date is a reserved keyword in most databases, you need to specify a non-reserved word for the column name.

The title mapping also lacks a type attribute. The types declared and used in the mapping files are neither Java data types nor SQL database types. Instead, they are Hibernate mapping types. Hibernate mapping types are converters which translate between Java and SQL data types. Hibernate attempts to determine the correct conversion and mapping type autonomously if the type attribute is not present in the mapping, by using Java reflection to determine the Java type of the declared property and using a default mapping type for that Java type.

In some cases this automatic detection might not chose the default you expect or need, as seen with the date property. Hibernate cannot know if the property, which is of type java.util.Date, should map to a SQL DATE, TIME, or TIMESTAMP datatype. Full date and time information is preserved by mapping the property to a timestamp converter (which identifies an instance of the class org.hibernate.type.TimestampType).


Hibernate makes this mapping type determination using reflection when the mapping files are processed. This process can take time and resources. If startup performance is important, consider explicitly defining the type to use.

The org.hibernate.tutorial.hbm.NativeApiIllustrationTest class illustrates using the Hibernate native API.

The org.hibernate.cfg.Configuration class is the first thing to notice. In this tutorial everything is simply configured via the hibernate.cfg.xml file discussed inSection 2.1, “The Hibernate configuration file”.

The org.hibernate.cfg.Configuration is then used to create the org.hibernate.SessionFactory which is a thread-safe object that is instantiated once to serve the entire application.

The org.hibernate.SessionFactory acts as a factory for org.hibernate.Session instances as can be seen in the testBasicUsage method. A org.hibernate.Session should be thought of as a corollary to a "unit of work".

testBasicUsage first creates some new Event objects and hands them over to Hibernate for "management" via the save method. At that point, Hibernate takes responsibility to perform an INSERT on the database.

testBasicUsage then illustrates use of the Hibernate Query Language (HQL) to load all existing Event objects from the database. Hibernate will generate the appropriate SELECT SQL, send it to the database and populate Event objects with the result set data.

This tutorial is located within the download bundle under basic and illustrates

  • using annotations to provide mapping information

  • using the native Hibernate APIs

The contents are exactly the same as in Section 2.1, “The Hibernate configuration file”. The single difference is the mapping element at the very end naming the annotated entity class using the class attribute.

The entity class in this tutorial is org.hibernate.tutorial.annotations.Event which is still following JavaBean conventions. In fact the class itself is exactly the same as we saw in Section 2.2, “The entity Java class”, the only difference being the use of annotations to provide the metadata instead of a separate hbm.xml file.

The @javax.persistence.Entity annotation is used to mark a class as an entity. It's function is essentially the same as the class mapping element discussed in Section 2.3, “The mapping file”. Additionally the @javax.persistence.Table annotation is used to explicitly specify the table name (the default table name would have been EVENT).

@javax.persistence.Id marks the property defining the entity's identifier. @javax.persistence.GeneratedValue and @org.hibernate.annotations.GenericGenerator work in tandem to indicate that Hibernate should use Hibernate's increment generation strategy for this entity's identifier values.

Just as discussed in Section 2.3, “The mapping file”, the date property needs special handling to account for its special naming and its SQL type.

This tutorial is located within the download bundle under entitymanager and illustrates

  • using annotations to provide mapping information

  • using JPA

The previous tutorials used the Hibernate-specific hibernate.cfg.xml configuration file. JPA, however, defines a different bootstrap process that uses its own configuration file named persistence.xml. How this bootstrapping works is defined by the JPA specification. In Java™ SE environments the persistence provider (Hibernate in this case) is required to locate all JPA configuration files by classpath lookup of the META-INF/persistence.xml resource name.

persistence.xml files should provide a unique name for each persistence unit. This name is how applications reference the configuration while obtaining an javax.persistence.EntityManagerFactory reference.

The settings defined in the properties element were already discussed in Section 2.1, “The Hibernate configuration file”. Here the javax.persistence-prefixed varieties are used when possible. For the remaining Hibernate-specific configuration setting names notice that they are now prefixed with hibernate..

Additionally, the class element functions the same as discussed in Section 3.1, “The Hibernate configuration file”.

The previous tutorials used the Hibernate APIs. This tutorial uses the JPA APIs.

Notice again the use of org.hibernate.tutorial.jpa as the persistence unit name, which matches from Example 4.1, “persistence.xml”

The code is pretty similar to Example 2.5, “Saving entities”. Here we use an javax.persistence.EntityManager as opposed to a org.hibernate.Session. JPA calls this operation persist instead of save.

Again, the code is pretty similar to Example 2.6, “Obtaining a list of entities”.

This tutorial is located within the download bundle under envers and illustrates

  • configuring Envers

  • using the Envers APIs to look back through history