Hibernate ORM 5.5 Integration Guide
Hibernate ORM 5.5 Integration Guide
5 Integration Guide
Table of Contents
Preface
Audience
1. Services and Registries
1.1. What is a Service?
1.1.1. Service contracts
1.1.2. Service dependencies
1.2. What is a ServiceRegistry ?
1.3. ServiceBinding
1.4. Types of ServiceRegistries
1.4.1. BootstrapServiceRegistry
1.4.2. StandardServiceRegistry
1.4.3. SessionFactoryServiceRegistry
1.5. Custom Services
1.5.1. Custom Service Implementations (overriding)
1.5.2. Custom Service Roles (extending)
Preface
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.
Audience
This guide is for software developers and architects who will be integrating Hibernate with Java EE application servers, Spring framework, caching
solutions (e.g. Infinispan, Ehcache, Hazelcast).
Services and registries are new as a formalized concept starting in 4.0. But the functionality provided by the different Services have actually been
around in Hibernate much, much longer. What is new is managing them, their lifecycles and dependencies through a lightweight, dedicated container we
call a ServiceRegistry . The goal of this guide is to describe the design and purpose of these Services and Registries , as well as to look at
details of their implementations where appropriate. It will also delve into the ways third-party integrators and applications can leverage and
customize Services and Registries .
https://docs.jboss.org/hibernate/orm/5.5/integrationguide/html_single/Hibernate_Integration_Guide.html 1/12
7/31/22, 7:43 PM Hibernate ORM 5.5 Integration Guide
Generally speaking, users can plug in alternate implementations of all standard Service roles (overriding); they can also define additional services
beyond the base set of Service roles (extending).
Let’s look at an example to better define what a Service is. Hibernate needs to be able to access JDBC Connections to the database. The way it
obtains and releases these Connections is through the ConnectionProvider service. The Service is defined by the interface (service
role) org.hibernate.engine.jdbc.connections.spi.ConnectionProvider which declares methods for obtaining and releasing
the Connections . There are then multiple implementations of that Service contract, varying in how they actually manage the Connections .
There is nothing revolutionary here; programming to interfaces is generally accepted as good programming practice. What’s interesting is
the ServiceRegistry and the pluggable swapping of the different implementors.
The Service can also implement a number of optional life-cycle related contracts:
org.hibernate.service.spi.Startable
allows the Service impl to be notified that it is being started and about to be put into use.
org.hibernate.service.spi.Stoppable
allows the Service impl to be notified that it is being stopped and will be removed from use.
org.hibernate.service.spi.ServiceRegistryAwareService
allows the Service to be injected with a reference to the registry that is managing it. See Service dependencies for more details.
org.hibernate.service.spi.Manageable
marks the Service as manageable in JMX provided the JMX integration is enabled. This feature is still incomplete.
Other
The different registry implementations also understand additional optional contracts specific to that registry. For details, see the details for each
registry in What is a ServiceRegistry ?.
@org.hibernate.service.spi.InjectService
Any method on the Service implementation class accepting a single parameter and annotated with @InjectService is considered requesting
injection of another service.
By default, the type of the method parameter is expected to be the Service role to be injected. If the parameter type is different than
the Service role, the serviceRole attribute of the @InjectService annotation should be used to explicitly name the role.
By default, injected services are considered required, that is the start up will fail if a named dependent Service is missing. If the Service to be
injected is optional, the required attribute of the @InjectService annotation should be declared as false (default is true ).
org.hibernate.service.spi.ServiceRegistryAwareService
The second approach is a pull approach where the Service implements the
optional Service interface org.hibernate.service.spi.ServiceRegistryAwareService which declares a
single injectServices method.
https://docs.jboss.org/hibernate/orm/5.5/integrationguide/html_single/Hibernate_Integration_Guide.html 2/12
7/31/22, 7:43 PM Hibernate ORM 5.5 Integration Guide
During startup, Hibernate will inject the org.hibernate.service.ServiceRegistry itself into services which implement this interface.
The Service can then use the ServiceRegistry reference to locate any additional services it needs.
We already gave a basic overview and definition of services. But services have other interesting characteristics as well:
Why not just use an existing IoC framework? The main reason was that this had to be as light-weight and as small of a footprint as possible. The initial
design also had called for Services to be swappable at runtime, which unfortunately had to be removed due to performance problems in the proxy-
based swapping-solution; the plan is to investigate alternate ways to achieve swap-ability with better performance at a later date.
A Service is associated with a ServiceRegistry . The ServiceRegistry scopes the Service . The ServiceRegistry manages the lifecycle
of the Service . The ServiceRegistry handles injecting dependencies into the Service (actually both a pull and a push/injection approach are
supported). ServiceRegistries are also hierarchical, meaning a ServiceRegistry can have a parent ServiceRegistry . Services in one registry
can depend on and utilize services in that same registry as well as any parent registries.
1.3. ServiceBinding
The association of a given Service to a given ServiceRegistry is called a binding and is represented by
the org.hibernate.service.spi.ServiceBinding interface. Furthermore, the specific contract between a ServiceBinding and
the ServiceRegistry is represented by the org.hibernate.service.spi.ServiceBinding.ServiceLifecycleOwner interface.
the Service can be directly instantiated and then handed to the ServiceRegistry
a ServiceInitiator can be given to the ServiceRegistry (which the ServiceRegistry will use if and when the Service is needed)
1.4.1. BootstrapServiceRegistry
The org.hibernate.boot.registry.BootstrapServiceRegistry holds three Service and is normally built by means of
the org.hibernate.boot.registry.BootstrapServiceRegistryBuilder factory class. The builder gives type safe access to customizing these
three Services .
https://docs.jboss.org/hibernate/orm/5.5/integrationguide/html_single/Hibernate_Integration_Guide.html 3/12
7/31/22, 7:43 PM Hibernate ORM 5.5 Integration Guide
This registry holds services that absolutely have to be available for most things in Hibernate to work.
The services of the BootstrapServiceRegistry cannot be extended (added to) nor overridden (replaced).
ClassLoaderService
The Service role for this Service is org.hibernate.boot.registry.classloading.spi.ClassLoaderService . This Service defines
Hibernate’s ability to interact with ClassLoaders . The manner in which Hibernate (or any library) should interact with ClassLoaders varies based
on the runtime environment which is hosting the application. Application servers, OSGi containers, and other modular class loading systems impose very
specific class-loading requirements. This Service provides Hibernate an abstraction from this environmental complexity. And just as important, it does
so in a centralized, swappable manner.
Locating Class references by name. This includes application classes as well as integration classes.
IntegratorService
The Service role for this Service is org.hibernate.integrator.spi.IntegratorService. Applications, third-party integrators and others
all need to integrate with Hibernate. Historically this used to require something (usually the application) to coordinate registering the pieces of each
integration needed on behalf of each integration. The org.hibernate.integrator.spi.Integrator contract formalized this "integration SPI". The
IntegratorService manages all known integrators.
The concept of "Integrator" is still being actively defined and developed. Expect changes in these SPIs.
The integrator may be discovered, leveraging the standard Java ServiceLoader capability provided by
the ClassLoaderService . Integrators would simply define a file named /META-
INF/services/org.hibernate.integrator.spi.Integrator and make it available on the classpath. ServiceLoader covers the format of
this file in detail, but essentially it lists classes by fully-qualified name that implement Integrator one per line.
StrategySelector
The Service role for this Service is org.hibernate.boot.registry.selector.spi.StrategySelector . Think of this as the short
naming service. Historically to configure Hibernate users would often need to give fully-qualified name references to internal Hibernate classes. Of
course, this has caused lots of problems as we refactor internal code and move these classes around into different package structures. Enter the concept of
short-naming, using a well defined and well known short name for the strategy/implementation class.
The short name mappings in this Service can be managed, even by applications and integrators which can be very powerful. For more information on
this aspect, see:
BootstrapServiceRegistryBuilder#applyStrategySelector
BootstrapServiceRegistryBuilder#applyStrategySelectors
https://docs.jboss.org/hibernate/orm/5.5/integrationguide/html_single/Hibernate_Integration_Guide.html 4/12
7/31/22, 7:43 PM Hibernate ORM 5.5 Integration Guide
1.4.2. StandardServiceRegistry
The org.hibernate.boot.registry.StandardServiceRegistry defines the main Hibernate ServiceRegistry , building on
the BootstrapServiceRegistry which is its parent. This registry is generally built using
the org.hibernate.boot.registry.StandardServiceRegistryBuilder class. By default, it holds most of the Services used by Hibernate.
For the full list of Services typically held in the StandardServiceRegistry , see the source code
of org.hibernate.service.StandardServiceInitiators .
The services of the StandardServiceRegistry can be extended (added to) and overridden (replaced).
ConnectionProvider/MultiTenantConnectionProvider
The Service providing Hibernate with Connections as needed. Comes in two distinct (and mutually exclusive) roles:
org.hibernate.engine.jdbc.connections.spi.ConnectionProvider
org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider
JdbcServices
org.hibernate.engine.jdbc.spi.JdbcServices is an aggregator Service (a Service that aggregates other Services) exposing unified
functionality around JDBC accessibility.
TransactionCoordinatorBuilder
JtaPlatform
JndiService
The org.hibernate.engine.jndi.spi.JndiService Service is used by Hibernate to interact with JNDI contexts. Hibernate’s
default JndiService assumes just a single InitialContext .
RegionFactory
The org.hibernate.cache.spi.RegionFactory Service defines the integration with third party cache implementors as second-level caching
providers.
SessionFactoryServiceRegistryFactory
org.hibernate.service.spi.SessionFactoryServiceRegistryFactory is a Service that acts as a factory for building the third type
of ServiceRegistry (the SessionFactoryServiceRegistry) which we will discuss next. I opted for the factory as service approach because in the
current design there is really not a good exposed hook-in spot for when the SessionFactoryServiceRegistry needs to be built.
1.4.3. SessionFactoryServiceRegistry
org.hibernate.service.spi.SessionFactoryServiceRegistry is the third standard
Hibernate ServiceRegistry . SessionFactoryServiceRegistry is designed to hold Services which need access to the SessionFactory .
https://docs.jboss.org/hibernate/orm/5.5/integrationguide/html_single/Hibernate_Integration_Guide.html 5/12
7/31/22, 7:43 PM Hibernate ORM 5.5 Integration Guide
EventListenerRegistry
If doing custom listener registration, it is important to understand the org.hibernate.event.service.spi.DuplicationStrategy and its effect
on registration. The basic idea is to tell Hibernate:
StatisticsImplementor
org.hibernate.stat.spi.StatisticsImplementor is the SPI portion of the Statistics API; the collector portion, if you will.
NativeQueryInterpreter
org.hibernate.engine.query.spi.NativeQueryInterpreter is the Service Hibernate uses for interpreting native queries. Exists as
a Service mainly so that integrations such as OGM can override it.
CacheImplementor
org.hibernate.engine.spi.CacheImplementor provides a way to customize the way Hibernate interacts with the second-level caching
implementation.
The first step is to develop the actual integration by implementing the ConnectionProvider contract.
https://docs.jboss.org/hibernate/orm/5.5/integrationguide/html_single/Hibernate_Integration_Guide.html 6/12
7/31/22, 7:43 PM Hibernate ORM 5.5 Integration Guide
import java.lang.Override;
@Override
@Override
lagPool = lagPoolBuilder.buildPool();
available = true;
@Override
available = false;
lagPool.shutdown();
@Override
if ( !available ) {
throwException(
return lagPool.borrowConnection();
@Override
if ( !available ) {
warn(
if ( conn == null ) {
return;
lagPool.releaseConnection( conn );
...
At this point we have a decision about how to integrate this new ConnectionProvider into Hibernate. As you might guess, there are multiple ways.
As a first option, we might just require that the code bootstrapping the StandardServiceRegistry do the integration.
https://docs.jboss.org/hibernate/orm/5.5/integrationguide/html_single/Hibernate_Integration_Guide.html 7/12
7/31/22, 7:43 PM Hibernate ORM 5.5 Integration Guide
...
builder.addService(
ConnectionProvider.class,
new LatestAndGreatestConnectionProviderImpl()
);
...
implements ServiceContributor {
@Override
serviceRegistryBuilder.addService(
ConnectionProvider.class,
new LatestAndGreatestConnectionProviderImpl()
);
We still need to be able to tell Hibernate to perform this integration for us. To do that we leverage Java’s ServiceLoader . When building
the StandardServiceRegistry , Hibernate will look for JDK Service providers of
type org.hibernate.service.spi.ServiceContributor and automatically integrate them. We discussed this behavior above. Here we’d define a
classpath resource named META-INF/services/org.hibernate.service.spi.ServiceContributor . This file will have just a single line naming
our impl.
fully.qualified.package.LatestAndGreatestConnectionProviderImplContributor1
A third option, if we simply want to make our LatestAndGreatestConnectionProviderImpl available as a configuration choice, we would again
use a ServiceContributor but in a slightly different way.
implements ServiceContributor {
@Override
standardserviceregistrybuilder serviceregistrybuilder) {
.getbootstrapserviceregistry().
.getservice( strategyselector.class );
selector.registerstrategyimplementor(
connectionprovider.class,
"lag"
latestandgreatestconnectionproviderimpl.class
);
https://docs.jboss.org/hibernate/orm/5.5/integrationguide/html_single/Hibernate_Integration_Guide.html 8/12
7/31/22, 7:43 PM Hibernate ORM 5.5 Integration Guide
That all allows the application to pick our LatestAndGreatestConnectionProviderImpl by a short-name.
...
...
https://docs.jboss.org/hibernate/orm/5.5/integrationguide/html_single/Hibernate_Integration_Guide.html 9/12
7/31/22, 7:43 PM Hibernate ORM 5.5 Integration Guide
ServiceRegistryAwareService {
@Override
this.serviceRegistry = serviceRegistry;
this.jmsConnectionFactoryName = configurationValues
.get( JMS_CONNECTION_FACTORY_NAME_SETTING );
this.destinationName = configurationValues
.get( JMS_DESTINATION_NAME_SETTING );
@Override
.getService( JndiService.class );
.locate( jmsConnectionFactoryName );
this.jmsConnection = jmsConnectionFactory.createConnection();
this.jmsSession = jmsConnection.createSession(
true,
Session.AUTO_ACKNOWLEDGE
);
@Override
publisher.send( theEvent );
@Override
publisher.close();
jmsSession.close();
jmsConnection.close();
https://docs.jboss.org/hibernate/orm/5.5/integrationguide/html_single/Hibernate_Integration_Guide.html 10/12
7/31/22, 7:43 PM Hibernate ORM 5.5 Integration Guide
new DisabledEventPublishingServiceImpl();
private DisabledEventPublishingServiceImpl() {
@Override
// nothing to do...
Because we have alternative implementations, it is a good idea to develop an initiator as well that can choose between them at runtime.
implements StandardServiceInitiator<EventPublishingService> {
new EventPublishingServiceInitiator();
"com.acme.EventPublishingService.enabled";
@Override
return EventPublishingService.class;
@Override
public R initiateService(
Map configurationValues,
ServiceRegistryImplementor registry) {
configurationValues,
ENABLE_PUBLISHING_SETTING
);
if ( enabled ) {
else {
return DisabledEventPublishingServiceImpl.INSTANCE;
...
We could have the application register the EventPublishingServiceInitiator with the StandardServiceRegistryBuilder , but it is much
nicer to write a ServiceContributor to handle this for the application.
https://docs.jboss.org/hibernate/orm/5.5/integrationguide/html_single/Hibernate_Integration_Guide.html 11/12
7/31/22, 7:43 PM Hibernate ORM 5.5 Integration Guide
implements ServiceContributor {
@Override
builder.addinitiator( eventpublishingserviceinitiator.instance );
https://docs.jboss.org/hibernate/orm/5.5/integrationguide/html_single/Hibernate_Integration_Guide.html 12/12