Hibernate.orgCommunity Documentation

Chapter 7. Services

Table of Contents

7.1. What are services?
7.2. Service contracts
7.3. Service dependencies
7.3.1. @org.hibernate.service.spi.InjectService
7.3.2. org.hibernate.service.spi.ServiceRegistryAwareService
7.4. ServiceRegistry
7.5. Standard services
7.5.1. org.hibernate.engine.jdbc.batch.spi.BatchBuilder
7.5.2. org.hibernate.service.config.spi.ConfigurationService
7.5.3. org.hibernate.service.jdbc.connections.spi.ConnectionProvider
7.5.4. org.hibernate.service.jdbc.dialect.spi.DialectFactory
7.5.5. org.hibernate.service.jdbc.dialect.spi.DialectResolver
7.5.6. org.hibernate.engine.jdbc.spi.JdbcServices
7.5.7. org.hibernate.service.jmx.spi.JmxService
7.5.8. org.hibernate.service.jndi.spi.JndiService
7.5.9. org.hibernate.service.jta.platform.spi.JtaPlatform
7.5.10. org.hibernate.service.jdbc.connections.spi.MultiTenantConnectionProvider
7.5.11. org.hibernate.persister.spi.PersisterClassResolver
7.5.12. org.hibernate.persister.spi.PersisterFactory
7.5.13. org.hibernate.cache.spi.RegionFactory
7.5.14. org.hibernate.service.spi.SessionFactoryServiceRegistryFactory
7.5.15. org.hibernate.stat.Statistics
7.5.16. org.hibernate.engine.transaction.spi.TransactionFactory
7.5.17. org.hibernate.tool.hbm2ddl.ImportSqlCommandExtractor
7.6. Custom services
7.7. Special service registries
7.7.1. Boot-strap registry
7.7.2. SessionFactory registry
7.8. Using services and registries
7.9. Integrators
7.9.1. Integrator use-cases

Services are classes that provide Hibernate with pluggable implementations of various types of functionality. Specifically they are implementations of certain service contract interfaces. The interface is known as the service role; the implementation class is know as the service implementation. 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).

The basic requirement for a service is to implement the marker interface org.hibernate.service.Service. Hibernate uses this internally for some basic type safety.

Optionally, the service can also implement the org.hibernate.service.spi.Startable and org.hibernate.service.spi.Stoppable interfaces to receive notifications of being started and stopped. Another optional service contract is org.hibernate.service.spi.Manageable which marks the service as manageable in JMX provided the JMX integration is enabled.

Services are allowed to declare dependencies on other services using either of 2 approaches.

The central service API, aside from the services themselves, is the org.hibernate.service.ServiceRegistry interface. The main purpose of a service registry is to hold, manage and provide access to services.

Service registries are hierarchical. Services in one registry can depend on and utilize services in that same registry as well as any parent registries.

Use org.hibernate.service.ServiceRegistryBuilder to build a org.hibernate.service.ServiceRegistry instance.


Provides an abstraction from the underlying JTA platform when JTA features are used.




JtaPlatformInitiator provides mapping against the legacy, now-deprecated org.hibernate.transaction.TransactionManagerLookup names internally for the Hibernate-provided org.hibernate.transaction.TransactionManagerLookup implementations.

  • org.hibernate.service.jta.platform.internal.BitronixJtaPlatform - Integration with the Bitronix stand-alone transaction manager.

  • org.hibernate.service.jta.platform.internal.BorlandEnterpriseServerJtaPlatform - Integration with the transaction manager as deployed within a Borland Enterprise Server

  • org.hibernate.service.jta.platform.internal.JBossAppServerJtaPlatform - Integration with the transaction manager as deployed within a JBoss Application Server

  • org.hibernate.service.jta.platform.internal.JBossStandAloneJtaPlatform - Integration with the JBoss Transactions stand-alone transaction manager

  • org.hibernate.service.jta.platform.internal.JOTMJtaPlatform - Integration with the JOTM stand-alone transaction manager

  • org.hibernate.service.jta.platform.internal.JOnASJtaPlatform - Integration with the JOnAS transaction manager.

  • org.hibernate.service.jta.platform.internal.JRun4JtaPlatform - Integration with the transaction manager as deployed in a JRun 4 application server.

  • org.hibernate.service.jta.platform.internal.NoJtaPlatform - No-op version when no JTA set up is configured

  • org.hibernate.service.jta.platform.internal.OC4JJtaPlatform - Integration with transaction manager as deployed in an OC4J (Oracle) application server.

  • org.hibernate.service.jta.platform.internal.OrionJtaPlatform - Integration with transaction manager as deployed in an Orion application server.

  • org.hibernate.service.jta.platform.internal.ResinJtaPlatform - Integration with transaction manager as deployed in a Resin application server.

  • org.hibernate.service.jta.platform.internal.SunOneJtaPlatform - Integration with transaction manager as deployed in a Sun ONE (7 and above) application server.

  • org.hibernate.service.jta.platform.internal.TransactionManagerLookupBridge - Provides a bridge to legacy (and deprecated) org.hibernate.transaction.TransactionManagerLookup implementations

  • org.hibernate.service.jta.platform.internal.WebSphereExtendedJtaPlatform - Integration with transaction manager as deployed in a WebSphere Application Server (6 and above).

  • org.hibernate.service.jta.platform.internal.WebSphereJtaPlatform - Integration with transaction manager as deployed in a WebSphere Application Server (4, 5.0 and 5.1).

  • org.hibernate.service.jta.platform.internal.WeblogicJtaPlatform - Integration with transaction manager as deployed in a Weblogic application server.


A variation of Section 7.5.3, “org.hibernate.service.jdbc.connections.spi.ConnectionProvider providing access to JDBC connections in multi-tenant environments.




Intended that users provide appropriate implementation if needed.

Once a org.hibernate.service.ServiceRegistry is built it is considered immutable; the services themselves might accept re-configuration, but immutability here means adding/replacing services. So another role provided by the org.hibernate.service.ServiceRegistryBuilder is to allow tweaking of the services that will be contained in the org.hibernate.service.ServiceRegistry generated from it.

There are 2 means to tell a org.hibernate.service.ServiceRegistryBuilder about custom services.

  • Implement a org.hibernate.service.spi.BasicServiceInitiator class to control on-demand construction of the service class and add it to the org.hibernate.service.ServiceRegistryBuilder via its addInitiator method.

  • Just instantiate the service class and add it to the org.hibernate.service.ServiceRegistryBuilder via its addService method.

Either approach the adding a service approach or the adding an initiator approach are valid for extending a registry (adding new service roles) and overriding services (replacing service implementations).

The boot-strap registry holds services that absolutely have to be available for most things to work. The main service here is the Section, “org.hibernate.service.classloading.spi.ClassLoaderService which is a perfect example. Even resolving configuration files needs access to class loading services (resource look ups). This is the root registry (no parent) in normal use.

Instances of boot-strap registries are built using the org.hibernate.service.BootstrapServiceRegistryBuilder class.

Coming soon...

The org.hibernate.integrator.spi.Integrator is intended to provide a simple means for allowing developers to hook into the process of building a functioning SessionFactory. The The org.hibernate.integrator.spi.Integrator interface defines 2 methods of interest: integrate allows us to hook into the building process; disintegrate allows us to hook into a SessionFactory shutting down.


There is a 3rd method defined on org.hibernate.integrator.spi.Integrator, an overloaded form of integrate accepting a org.hibernate.metamodel.source.MetadataImplementor instead of org.hibernate.cfg.Configuration. This form is intended for use with the new metamodel code scheduled for completion in 5.0

See Section, “org.hibernate.integrator.spi.IntegratorService

In addition to the discovery approach provided by the IntegratorService, applications can manually register Integrator implementations when building the BootstrapServiceRegistry. See Example 7.1, “Using BootstrapServiceRegistryBuilder”

The main use cases for an org.hibernate.integrator.spi.Integrator right now are registering event listeners and providing services (see org.hibernate.integrator.spi.ServiceContributingIntegrator). With 5.0 we plan on expanding that to allow altering the metamodel describing the mapping between object and relational models.