7/31/22, 7:43 PM Hibernate Getting Started Guide

1.1. The Hibernate Modules/Artifacts

Hibernate’s functionality is split into a number of modules/artifacts meant to isolate dependencies (modularity).

hibernate-core
The main (core) Hibernate module. Defines its ORM features and APIs as well as the various integration SPIs.

hibernate-envers
Hibernate’s historical entity versioning feature

hibernate-spatial
Hibernate’s Spatial/GIS data-type support

hibernate-osgi
Hibernate support for running in OSGi containers.

hibernate-agroal
Integrates the Agroal connection pooling library into Hibernate

hibernate-c3p0
Integrates the C3P0 connection pooling library into Hibernate

hibernate-hikaricp
Integrates the HikariCP connection pooling library into Hibernate

hibernate-vibur
Integrates the Vibur DBCP connection pooling library into Hibernate

hibernate-proxool
Integrates the Proxool connection pooling library into Hibernate

hibernate-jcache
Integrates the JCache caching specification into Hibernate, enabling any compliant implementation to become a
second-level cache provider.

hibernate-ehcache
Integrates the Ehcache caching library into Hibernate as a second-level cache provider.

1.2. Release Bundle Downloads

https://docs.jboss.org/hibernate/orm/5.5/quickstart/html_single/#_the_hibernate_modules_artifacts 1/5
7/31/22, 7:43 PM Hibernate Getting Started Guide

The Hibernate team provides release bundles hosted on the SourceForge File Release System, in
both  TGZ  and  ZIP  formats. Each release bundle contains  JAR  files, documentation, source code, and other
goodness.

You can download releases of Hibernate, in your chosen format, from the list
at https://sourceforge.net/projects/hibernate/files/hibernate-orm/. The release bundle is structured as follows:

The  lib/required/  directory contains the  hibernate-core  jar and all of its dependencies. All of these
jars are required to be available on your classpath no matter which features of Hibernate are being used.

The  lib/envers  directory contains the  hibernate-envers  jar and all of its dependencies (beyond those
in  lib/required/  and  lib/jpa/ ).

The  lib/spatial/  directory contains the  hibernate-spatial  jar and all of its dependencies (beyond
those in  lib/required/ )

The  lib/osgi/  directory contains the  hibernate-osgi  jar and all of its dependencies (beyond those
in  lib/required/  and  lib/jpa/ )

The  lib/jpa-metamodel-generator/  directory contains the jar needed for generating the Criteria API
type-safe Metamodel.

The  lib/optional/  directory contains the jars needed for the various connection pooling and second-level
cache integrations provided by Hibernate, along with their dependencies.

1.3. Maven Repository Artifacts

The authoritative repository for Hibernate artifacts is the JBoss Maven repository. The Hibernate artifacts are
synced to Maven Central as part of an automated job (some small delay may occur).

The team responsible for the JBoss Maven repository maintains a number of Wiki pages that contain important
information:

https://community.jboss.org/docs/DOC-14900 - General information about the repository.

https://community.jboss.org/docs/DOC-15170 - Information about setting up the JBoss repositories in order to

do development work on JBoss projects themselves.

https://community.jboss.org/docs/DOC-15169 - Information about setting up access to the repository to use

JBoss projects as part of your own software.

The Hibernate ORM artifacts are published under the  org.hibernate  groupId.

2. Tutorial Using Native Hibernate APIs and hbm.xml Mapping

https://docs.jboss.org/hibernate/orm/5.5/quickstart/html_single/#_the_hibernate_modules_artifacts 2/5
7/31/22, 7:43 PM Hibernate Getting Started Guide

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

Objectives
 Bootstrap a Hibernate  SessionFactory

 Use Hibernate mapping ( hbm.xml ) files to provide mapping information

 Use the Hibernate native APIs

2.1. The Hibernate configuration file

For this tutorial, the  hibernate.cfg.xml  file defines the Hibernate configuration information.

The  connection.driver_class ,  connection.url ,  connection.username  and  connection.passwor

d   <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 built-in Hibernate connection pool is in no way intended for production use. It lacks
several features found on production-ready connection pools.

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

In most cases, Hibernate is able to properly determine which dialect to use. This is
particularly useful if your application targets multiple databases.

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.

There are many ways and options to bootstrap a Hibernate  SessionFactory . For additional details, see
the Native Bootstrapping topical guide.

2.2. The entity Java class

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

Notes About the Entity

https://docs.jboss.org/hibernate/orm/5.5/quickstart/html_single/#_the_hibernate_modules_artifacts 3/5
7/31/22, 7:43 PM Hibernate Getting Started Guide

This class uses standard JavaBean naming conventions for property getter and setter methods, as well as
private visibility for the fields. Although this is the recommended design, it is not required.

The no-argument constructor, which is also a JavaBean convention, is a requirement for all persistent classes.
Hibernate needs to create objects for you, using Java Reflection. The constructor can be private. However,
package or public visibility is required for runtime proxy generation and efficient data retrieval without
bytecode instrumentation.

2.3. The mapping file

The mapping file for this tutorial is the classpath
resource  org/hibernate/tutorial/hbm/Event.hbm.xml  (as discussed above).

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.

Example 1. The class mapping element

<class name="Event" table="EVENTS">

...

</class>

Functions of the <varname>class</varname> mapping element

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.

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  database table.

Example 2. The id mapping element

<id name="id" column="EVENT_ID">

...

</id>

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

https://docs.jboss.org/hibernate/orm/5.5/quickstart/html_single/#_the_hibernate_modules_artifacts 4/5
7/31/22, 7:43 PM Hibernate Getting Started Guide

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 names 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 informs Hibernate about which strategy is used to generated primary key values for this
entity. This example uses a simple incrementing count.

Example 3. The property mapping element

<property name="date" type="timestamp" column="EVENT_DATE"/>

<property name="title"/>

The two  <property/>  elements declare the remaining two persistent 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 na

https://docs.jboss.org/hibernate/orm/5.5/quickstart/html_single/#_the_hibernate_modules_artifacts 5/5