Hibernate.orgCommunity Documentation

Chapter 4. Bootstrap

Table of Contents

4.1. Native Bootstrapping
4.1.1. Building the ServiceRegistry
4.1.2. Building the Metadata
4.1.3. Building the SessionFactory
4.2. JPA Bootstrapping
4.2.1. JPA-compliant bootstrapping
4.2.2. Proprietary 2-phase bootstrapping

The term bootstrapping refers to initializing and starting a software component. In Hibernate we are specifically talking about the process of building a fully functional SessionFactory instance or EntityManagerFactory instance for JPA. The process is very different for each.


This chapter will not focus on all the possibilities of bootstrapping. Those will be covered in each specific more-relevant chapters later on. Instead we focus here on the API calls needed to perform the bootstrapping.

This section discusses the process of bootstrapping a Hibernate SessionFactory. Specifically it discusses the bootstrapping APIs as redesigned in 5.0. For a discussion of the legacy bootstrapping API, see Appendix A, Legacy Bootstrapping

The first step in native bootstrapping is the building of a ServiceRegistry holding the services Hibernate will need at bootstrap and run time.

Actually we are concerned with building 2 different ServiceRegistries. First is the org.hibernate.boot.registry.BootstrapServiceRegistry. The BootstrapServiceRegistry is intended to hold services that Hibernate needs at both bootstrap and run time. This boils down to 3 services:

  • org.hibernate.boot.registry.classloading.spi.ClassLoaderService - which controls how Hibernate interacts with ClassLoaders

  • org.hibernate.integrator.spi.IntegratorService - which controls the management ands discovery of org.hibernate.integrator.spi.Integrator instances.

  • org.hibernate.boot.registry.selector.spi.StrategySelector - which control how Hibernate resolves implementations of various strategy contracts. This is a very powerful service, but a full discussion of it is beyond the scope of this guide.

If you are ok with the default behavior of Hibernate in regards to these BootstrapServiceRegistry services (which is quite often the case, especially in SE environments), then building the BootstrapServiceRegistry can be skipped.

If you wish to alter how the BootstrapServiceRegistry is built, that is controlled through the org.hibernate.boot.registry.BootstrapServiceRegistryBuilder:

The services of the BootstrapServiceRegistry cannot be extended (added to) nor overridden (replaced).

The second ServiceRegistry is the org.hibernate.boot.registry.StandardServiceRegistry. You will almost always need to configure the StandardServiceRegistry, which is done through org.hibernate.boot.registry.StandardServiceRegistryBuilder:

A StandardServiceRegistry is also highly configurable via the StandardServiceRegistryBuilder API. See the StandardServiceRegistryBuilder javadocs for full details. Some specific methods of interest:

The second step in native bootstrapping is the building of a org.hibernate.boot.Metadata object containing the parsed representations of an application's domain model and its mapping to a database. The first thing we obviously need to build a parsed representation is the source information to be parsed (annotated classes, `hbm.xml` files, `orm.xml` files). This is the purpose of org.hibernate.boot.MetadataSources:

MetadataSources has many other methods as well; explore its API and javadocs for more information. Also, all methods on MetadataSources allow for chaining should you prefer that style:

Once we have the sources of mapping information defined, we need to build the Metadata object. If you are ok with the default behavior in building the Metadata then you can simply call MetadataSources#buildMetadata.


Notice that a ServiceRegistry can be passed at a number of points in this bootstrapping process. The suggested approach is to build a StandardServiceRegistry yourself and pass that along to the MetadataSources constructor. From there, MetadataBuilder, Metadata, SessionFactoryBuilder and SessionFactory will all pick up that same StandardServiceRegistry.

However, if you wish to adjust the process of building Metadata from MetadataSources you will need to use the MetadataBuilder as obtained via MetadataSources#getMetadataBuilder. MetadataBuilder allows a lot of control over the Metadata building process. See its javadocs for full details.

The final step in native bootstrapping is to build the SessionFactory itself. Much like discussed above, if you are ok with the default behavior of building a SessionFactory from a Metadata reference, you can simply call Metadata#buildSessionFactory.

However, if you would like to adjust that building process you will need to use SessionFactoryBuilder as obtained via Metadata#getSessionFactoryBuilder. Again, see its javadocs for full details.

The bootstrapping API is quite flexible, but in most cases it makes the most sense to think of it as a 3 step process:

  1. Build the StandardServiceRegistry
  2. Build the Metadata
  3. Use those 2 things to build the SessionFactory

Bootstrapping Hibernate as a JPA provider can be done in a JPA-spec compliant manner or using a proprietary bootstrapping approach. The standardized approach has some limitations in certain environments, but aside from those limitations, it is *highly* recommended that you use JPA-standardized bootstrapping.

In JPA we are ultimately interested in bootstrapping an javax.persistence.EntityManagerFactory instance. The JPA specification defines 2 primary standardized bootstrap approaches depending on how the application intends to access the javax.persistence.EntityManager instances from an EntityManagerFactory. It uses the terms "EE" and "SE" for these 2 approaches, but those terms are very misleading in this context. What the JPA spec calls EE bootstrapping is cases where a container (EE, OSGi, etc) will manage and inject the persistence context on behalf of the application. What it calls SE bootstrapping is everything else. We will use the terms container-bootstrapping and application-bootstrapping in this guide.