Hibernate.orgCommunity Documentation

Chapter 2. Tutorial Using Native Hibernate APIs and hbm.xml Mappings

2.1. The Hibernate configuration file
2.2. The entity Java class
2.3. The mapping file
2.4. Example code
2.5. Take it further!

This tutorial is located within the download bundle under basic/.


The resource file hibernate.cfg.xml defines Hibernate configuration information.

The connection.driver_class, connection.url, connection.username and connection.password property elements define JDBC connection information. These tutorials utilize the H2 in-memory database, So the values of these properties are all specific to running H2 in its in-memory mode. connection.pool_size is used to configure the number of connections in Hibernate's built-in connection pool.

The dialect property specifies the particular SQL variant with which Hibernate will converse.

The hbm2ddl.auto property enables automatic generation of database schemas directly into the database.

Finally, add the mapping file(s) for persistent classes to the configuration. The resource attribute of the mapping element causes Hibernate to attempt to locate that mapping as a classpath resource, using a java.lang.ClassLoader lookup.

The entity class for this tutorial is org.hibernate.tutorial.hbm.Event.

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 determine 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 to be defined 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 required 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, it is strongly recommend 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. This example uses a simple incrementing count.

The two property elements declare the remaining two properties of the Event class: date and title. 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 determines the mapping type using reflection when the mapping files are processed. This process adds overhead in terms of 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.

Procedure 2.1. Tutorial Workflow

  1. The configuration is loaded.

    The org.hibernate.cfg.Configuration class is the first thing to notice. In this tutorial, all configuration details are located in the hibernate.cfg.xml file discussed in Section 2.1, “The Hibernate configuration file”.

  2. The org.hibernate.SessionFactory is created.

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

  3. SessionFactory creates Session instances.

    The org.hibernate.SessionFactory acts as a factory for org.hibernate.Session instances as can be seen in the testBasicUsage method.

  4. Sessions perform work.

    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, using the save method. Hibernate now takes responsibility to perform an INSERT on the database.

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