Hibernate 5 Bootstrapping API

1. Overview

In this tutorial, we’ll explore the new mechanism by which we can initialize and start a Hibernate SessionFactory. We’ll especially focus on the new native bootstrapping process as it was redesigned in version 5.0.

Prior to version 5.0, applications had to use the Configuration class to bootstrap the SessionFactory. This approach is now deprecated, as the Hibernate documentation recommends using the new API based on the ServiceRegistry.

Simply put, building a SessionFactory is all about having a ServiceRegistry implementation that holds the Services needed by Hibernate during both startup and runtime.

2. Maven Dependencies

Before we start exploring the new bootstrapping process, we need to add the hibernate-core jar file to the project classpath. In a Maven based project, we just need to declare this dependency in the pom.xml file:

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>5.4.24.Final</version>
</dependency>

As Hibernate is a JPA provider, this will also include the JPA API dependency transitively.

We also need the JDBC driver of the database that we’re working with. In this example, we’ll use an embedded H2 database:

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>2.1.214</version>
</dependency>

Feel free to check the latest versions of hibernate-core and H2 driver on Maven Central.

3. Bootstrapping API

Bootstrapping refers to the process of building and initializing a SessionFactory.

To achieve this purpose, we need to have a ServiceRegistry that holds the Services needed by Hibernate. From this registry, we can build a Metadata object that represents the application’s domain model and its mapping to the database.

Let’s explore these major objects in greater detail.

3.1. Service

Before we dig into the ServiceRegistry concept, we first need to understand what a Service is. In Hibernate 5.0, a Service is a type of functionality represented by the interface with the same name:

org.hibernate.service.Service

By default, Hibernate provides implementations for the most common Services, and they are sufficient in most cases. Otherwise, we can build our own Services to either modify original Hibernate functionalities or add new ones.

In the next subsection, we’ll show how Hibernate makes these Services available through a lightweight container called ServiceRegistry.

3.2. ServiceRegistry

The first step in building a SessionFactory is to create a ServiceRegistry. This allows holding various Services that provide functionalities needed by Hibernate and is based on the Java SPI functionality.

Technically speaking, we can see the ServiceRegistry as a lightweight Dependency Injection tool where beans are only of type Service.

There are two types of ServiceRegistry and they are hierarchical. The first is the BootstrapServiceRegistry, which has no parent and holds these three required services:

• ClassLoaderService: allows Hibernate to interact with the ClassLoader of the various runtime environments
• IntegratorService: controls the discovery and management of the Integrator service allowing third-party applications to integrate with Hibernate
• StrategySelector: resolves implementations of various strategy contracts

To build a BootstrapServiceRegistry implementation, we use the BootstrapServiceRegistryBuilder factory class, which allows customizing these three services in a type-safe manner:

BootstrapServiceRegistry bootstrapServiceRegistry = new BootstrapServiceRegistryBuilder()
  .applyClassLoader()
  .applyIntegrator()
  .applyStrategySelector()
  .build();

The second ServiceRegistry is the StandardServiceRegistry, which builds on the previous BootstrapServiceRegistry and holds the three Services mentioned above. Additionally, it contains various other Services needed by Hibernate, listed in the StandardServiceInitiators class.

Like the previous registry, we use the StandardServiceRegistryBuilder to create an instance of the StandardServiceRegistry:

StandardServiceRegistryBuilder standardServiceRegistry =
  new StandardServiceRegistryBuilder();

Under the hood, the StandardServiceRegistryBuilder creates and uses an instance of BootstrapServiceRegistry. We can also use an overloaded constructor to pass an already created instance:

BootstrapServiceRegistry bootstrapServiceRegistry = 
  new BootstrapServiceRegistryBuilder().build();
StandardServiceRegistryBuilder standardServiceRegistryBuilder = 
  new StandardServiceRegistryBuilder(bootstrapServiceRegistry);

We use this builder to load a configuration from a resource file, such as the default hibernate.cfg.xml, and finally, we invoke the build() method to get an instance of the StandardServiceRegistry.

StandardServiceRegistry standardServiceRegistry = standardServiceRegistryBuilder
  .configure()
  .build();

3.3. Metadata

Having configured all the Services needed by instantiating a ServiceRegistry either of type BootstrapServiceRegistry or StandardServiceRegistry, we now need to provide the representation of the application’s domain model and its database mapping.

The MetadataSources class is responsible for this:

MetadataSources metadataSources = new MetadataSources(standardServiceRegistry);
metadataSources.addAnnotatedClass();
metadataSources.addResource()

Next, we get an instance of Metadata, which we’ll use in the last step:

Metadata metadata = metadataSources.buildMetadata();

3.4. SessionFactory

The last step is to create the SessionFactory from the previously created Metadata:

SessionFactory sessionFactory = metadata.buildSessionFactory();

We can now open a Session and start persisting and reading entities:

Session session = sessionFactory.openSession();
Movie movie = new Movie(100L);
session.persist(movie);
session.createQuery("FROM Movie").list();

4. Conclusion

In this article, we explored the steps needed to build a SessionFactory. Although the process seems complex, we can summarize it in three major steps: we first created an instance of StandardServiceRegistry, then we built a Metadata object, and finally, we built the SessionFactory.