Hibernate.orgCommunity Documentation
5.1.17.Final
Copyright © 2011 Red Hat, Inc.
2018-11-28
Table of Contents
List of Examples
Table of Contents
Working with both Object-Oriented software and Relational Databases can be cumbersome and time consuming. Development costs are significantly higher due to a paradigm mismatch between how data is represented in objects versus relational databases. Hibernate is an Object/Relational Mapping solution for Java environments. The term Object/Relational Mapping refers to the technique of mapping data from an object model representation to a relational data model representation (and visa versa). See http://en.wikipedia.org/wiki/Object-relational_mapping for a good high-level discussion.
While having a strong background in SQL is not required to use Hibernate, having a basic understanding of the concepts can greatly help you understand Hibernate more fully and quickly. Probably the single best background is an understanding of data modeling principles. You might want to consider these resources as a good starting point:
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.
Hibernate may not be the best solution for data-centric applications that only use stored-procedures to implement the business logic in the database, it is most useful with object-oriented domain models and business logic in the Java-based middle-tier. However, Hibernate can certainly help you to remove or encapsulate vendor-specific SQL code and will help with the common task of result set translation from a tabular representation to a graph of objects.
Use Hibernate and report any bugs or issues you find. See http://hibernate.org/issuetracker.html for details.
Try your hand at fixing some bugs or implementing enhancements. Again, see http://hibernate.org/issuetracker.html.
Engage with the community using mailing lists, forums, IRC, or other ways listed at http://hibernate.org/community.html.
Help improve or translate this documentation. Contact us on the developer mailing list if you have interest.
Spread the word. Let the rest of your organization know about the benefits of Hibernate.
Table of Contents
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.
A services provides a certain types of functionality, in a pluggable manner. Specifically they are interfaces defining certain functionality and then implementations of those service contract interfaces. The interface is known as the service role; the implementation class is known as the service implementation. The pluggability comes from the fact that the service implementation adheres to contract defined by the interface of the service role and that consumers of the service program to the service role, not the 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).
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.
Internally Hibernate always references org.hibernate.engine.jdbc.connections.spi.ConnectionProvider
rather than specific implementations in consuming the service (we will get to producing the service later
when we talk about registries). Because of that fact, other ConnectionProvider service implementations
could easily be plugged in.
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 basic requirement for a service is to implement the marker interface
org.hibernate.service.Service. Hibernate uses this internally for some
basic type safety.
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
Section 1.1.2, “Service dependencies”.
org.hibernate.service.spi.Manageable - marks the service
as manageable in JMX provided the JMX integration is enabled. This feature is still incomplete.
The different registry implementations also understand additional optional contracts specific to that registry. For details, see the details for each registry under Section 1.2, “What is a ServiceRegistry?”
Services are allowed to declare dependencies on other services using either of 2 approaches.
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).
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. 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.
A ServiceRegistry, at its most basic, hosts and manages Services. Its contract is defined by the
org.hibernate.service.ServiceRegistry interface.
We already gave a basic overview and definition of services. But services have other interesting characteristics as well. Services have a lifecycle. They have a scope. Services might depend on other services. And they need to be produced (choose using one implementation over another). The ServiceRegistry fulfills all these needs.
In a concise definition, the ServiceRegistry acts as a inversion-of-control (IoC) container.
Despite some recent revisionist history, Spring did not invent IoC nor dependency injection nor were they even the first to bring it into Java. Projects like JBoss MicroContainer and Apache Avalon pre-date Spring by many years and each did IoC and dependency injection. The concepts in ServiceRegistry are actually very similar to Apache Avalon.
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.
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.
There are 2 ways a Service becomes associated (bound) to a ServiceRegistry.
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)
ServiceRegistry implementations register bindings through calls to the overloaded
org.hibernate.service.internal.AbstractServiceRegistryImpl#createServiceBinding
method accepting either a Service instance or a ServiceInitiator instance.
Each specific type of registry defines its own ServiceInitiator specialization.
Currently Hibernate utilizes 3 different ServiceRegistry implementations forming a hierarchy. Each type is a specialization for the purpose of type-safety, but they add no new functionality.
The org.hibernate.boot.registry.BootstrapServiceRegistry
holds 3 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 3 Services.
This registry holds services that absolutely have to be available for most things in Hibernate to work.
In normal usage, the BootstrapServiceRegistry has no parent.
The services of the BootstrapServiceRegistry cannot be extended (added to) nor overridden (replaced).
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 is provides Hibernate an abstraction from this environmental complexity. And just as importantly, it does so in a centralized, swappable manner.
The specific capabilities exposed on this service include:
Locating Class references by name. This includes application classes as well as "integration" classes.
Locating resources (properties files, xml files, etc) as "classpath resources"
Interacting with java.util.ServiceLoader, Java's own service
provider discovery mechanism
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.
There are 2 ways an integrator becomes known.
The integrator may be manually registered by calling
BootstrapServiceRegistryBuilder#with(Integrator)
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 FQN that implement Integrator one
per line.
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 FQN 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
org.hibernate.boot.registry.selector.StrategyRegistrationProvider
via ServiceLoader discovery
StrategySelector#registerStrategyImplementor` /
StrategySelector#unRegisterStrategyImplementor
The org.hibernate.boot.registry.StandardServiceRegistry defines the
main Hibernate ServiceRegistry, building on the BootstrapServiceRegistry (BootstrapServiceRegistry 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.
Some particular StandardServiceRegistry Services of note include:
In normal usage, the parent of the StandardServiceRegistry is the BootstrapServiceRegistry.
The services of the StandardServiceRegistry can be extended (added to) and overridden (replaced).
The Service providing Hibernate with Connections as needed. Comes in 2 distinct (and mutually exclusive) roles:
org.hibernate.engine.jdbc.connections.spi.ConnectionProvider -
provides Connections in normal environments
org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider -
provides (tenant-specific) Connections in multi-tenant environments
org.hibernate.engine.jdbc.spi.JdbcServices is an aggregator
Service (a Service that aggregates other Services) exposing unified functionality around JDBC
accessibility.
org.hibernate.resource.transaction.TransactionCoordinatorBuilder
is used by Hibernate to integrate with and underlying transaction system. It is responsible for
building org.hibernate.resource.transaction.TransactionCoordinator
instances for use by each Hibernate Session.
When using a JTA-based TransactionCoordinatorBuilder, the
org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform Service
provides Hibernate access to the JTA TransactionManager and UserTransaction, as well handling
Synchronization registration.
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.
The org.hibernate.cache.spi.RegionFactory service defines the
integration with third party cache implementors as second-level caching providers.
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.
org.hibernate.service.spi.SessionFactoryServiceRegistry is the 3rd
standard Hibernate ServiceRegistry. SessionFactoryServiceRegistry is designed to hold Services which
need access to the SessionFactory.
Typically its parent registry is the StandardServiceRegistry.
Integrators, as it stands in 4.x, operate on the SessionFactoryServiceRegistry...
Currently SessionFactoryServiceRegistry holds just 4 Services:
org.hibernate.event.service.spi.EventListenerRegistry is the main
service managed in the SessionFactoryServiceRegistry. The is the Service that manages all of
Hibernate's event listeners. A major use-case for Integrators is to alter the listener registry.
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:
what makes a listener a duplicate
how to handle duplicate registrations (error, first wins, last wins)
org.hibernate.stat.spi.StatisticsImplementor is the SPI portion of
the Statistics API; the collector portion, if you will.
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.
So far we have focused on the Hibernate provided services. But applications and integrations can provide their own services as well, either
providing a new implementation of a standard service (overriding)
providing a whole new service role (extending)
We discussed swappability of service implementations above. Lets look at an example in practice. For the sake of illustration, lets say that we have developed a new ConnectionProvider integrating with the wonderful new latest-and-greatest connection pooling library. Let's look at the steps necessary to make that happen.
The first step is to develop the actual integration by implementing the ConnectionProvider contract.
Example 1.1. Custom ConnectionProvider implementation
import java.lang.Override;
public class LatestAndGreatestConnectionProviderImpl
implements ConnectionProvider, Startable, Stoppable, Configurable {
private LatestAndGreatestPoolBuilder lagPoolBuilder;
private LatestAndGreatestPool lagPool;
private boolean available = false;
@Override
public void configure(Map configurationValues) {
// extract our config from the settings map
lagPoolBuilder = buildBuilder( configurationValues );
}
@Override
public void start() {
// start the underlying pool
lagPool = lagPoolBuilder.buildPool();
available = true;
}
@Override
public void stop() {
available = false;
// stop the underlying pool
lagPool.shutdown();
}
@Override
public Connection getConnection() throws SQLException {
if ( !available ) {
throwException( "LatestAndGreatest ConnectionProvider not available for use" )
}
return lagPool.borrowConnection();
}
@Override
public void closeConnection(Connection conn) throws SQLException {
if ( !available ) {
warn( "LatestAndGreatest ConnectionProvider not available for use" )
}
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.
Example 1.2. Overriding service implementation via StandardServiceRegistryBuilder
StandardServiceRegistryBuilder builder = ...; ... builder.addService( ConnectionProvider.class, new LatestAndGreatestConnectionProviderImpl() ); ...
A second option, if our LatestAndGreatestConnectionProviderImpl should always be used, would be to
provide a org.hibernate.service.spi.ServiceContributor implementation
as well to handle the integration on the users behalf.
Example 1.3. LatestAndGreatestConnectionProviderImplContributor
public class LatestAndGreatestConnectionProviderImplContributor1
implements ServiceContributor {
@Override
public void contribute(StandardServiceRegistryBuilder serviceRegistryBuilder) {
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.
Example 1.4. META-INF/services/org.hibernate.service.spi.ServiceContributor
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.
Example 1.5. LatestAndGreatestConnectionProviderImplContributor
public class LatestAndGreatestConnectionProviderImplContributor1
implements ServiceContributor {
@Override
public void contribute(StandardServiceRegistryBuilder serviceRegistryBuilder) {
// here we will register a short-name for our service strategy
StrategySelector selector = serviceRegistryBuilder.getBootstrapServiceRegistry().
.getService( StrategySelector.class );
selector.registerStrategyImplementor(
ConnectionProvider.class,
"lag"
LatestAndGreatestConnectionProviderImpl.class
);
}
}
That all allows the appication to pick our LatestAndGreatestConnectionProviderImpl by a short-name.
Example 1.6. Custom service short-name
StandardServiceRegistryBuilder builder = ...; ... builder.applySetting( "hibernate.connection.provider_class", "lag" ); ...
We can also have the ServiceRegistry host custom services (completely new Service roles). As an example, let's say our application publishes Hibernate events to a JMS Topic and that we want to leverage the Hibernate ServiceRegistry to host a Service representing our publishing of events. So we will expand the ServiceRegistry to host this completely new Service role for us and manage its lifecycle.
Example 1.7. The EventPublishingService service role
public interface EventPublishingService extends Service {
public void publish(Event theEvent);
}
Example 1.8. The EventPublishingService implementation
public class EventPublishingServiceImpl
implements EventPublishingService,
Configurable,
Startable,
Stoppable,
ServiceRegistryAwareService {
private ServiceRegistryImplementor serviceRegistry;
private String jmsConnectionFactoryName;
private String destinationName;
private Connection jmsConnection;
private Session jmsSession;
private MessageProducer publisher;
@Override
public void injectServices(ServiceRegistryImplementor serviceRegistry) {
this.serviceRegistry = serviceRegistry;
}
public void configure(Map configurationValues) {
this.jmsConnectionFactoryName = configurationValues.get( JMS_CONNECTION_FACTORY_NAME_SETTING );
this.destinationName = configurationValues.get( JMS_DESTINATION_NAME_SETTING );
}
@Override
public void start() {
final JndiService jndiService = serviceRegistry.getService( JndiService.class );
final ConnectionFactory jmsConnectionFactory = jndiService.locate( jmsConnectionFactoryName );
this.jmsConnection = jmsConnectionFactory.createConnection();
this.jmsSession = jmsConnection.createSession( true, Session.AUTO_ACKNOWLEDGE );
final Destination destination = jndiService.locate( destinationName );
this.publisher = jmsSession.createProducer( destination );
}
@Override
public void publish(Event theEvent) {
publisher.send( theEvent );
}
@Override
public void stop() {
publisher.close();
jmsSession.close();
jmsConnection.close();
}
}
Example 1.9. An alternative EventPublishingService implementation
public class EventPublishingServiceImpl
implements EventPublishingService,
Configurable,
Startable,
Stoppable,
ServiceRegistryAwareService {
private ServiceRegistryImplementor serviceRegistry;
private String jmsConnectionFactoryName;
private String destinationName;
private Connection jmsConnection;
private Session jmsSession;
private MessageProducer publisher;
@Override
public void injectServices(ServiceRegistryImplementor serviceRegistry) {
this.serviceRegistry = serviceRegistry;
}
public void configure(Map configurationValues) {
this.jmsConnectionFactoryName = configurationValues.get( JMS_CONNECTION_FACTORY_NAME_SETTING );
this.destinationName = configurationValues.get( JMS_DESTINATION_NAME_SETTING );
}
@Override
public void start() {
final JndiService jndiService = serviceRegistry.getService( JndiService.class );
final ConnectionFactory jmsConnectionFactory = jndiService.locate( jmsConnectionFactoryName );
this.jmsConnection = jmsConnectionFactory.createConnection();
this.jmsSession = jmsConnection.createSession( true, Session.AUTO_ACKNOWLEDGE );
final Destination destination = jndiService.locate( destinationName );
this.publisher = jmsSession.createProducer( destination );
}
@Override
public void publish(Event theEvent) {
publisher.send( theEvent );
}
@Override
public void stop() {
publisher.close();
jmsSession.close();
jmsConnection.close();
}
}
Because we have alternative implementations, it is a good idea to develop an initiator as well that can choose between them at runtime.
Example 1.10. The EventPublishingServiceInitiator
public class EventPublishingServiceInitiator implements StandardServiceInitiator<EventPublishingService> {
public static EventPublishingServiceInitiator INSTANCE = new EventPublishingServiceInitiator();
public static final String ENABLE_PUBLISHING_SETTING = "com.acme.EventPublishingService.enabled";
@Override
public Class<R> getServiceInitiated() {
return EventPublishingService.class;
}
@Override
public R initiateService(Map configurationValues, ServiceRegistryImplementor registry) {
final boolean enabled = extractBoolean( configurationValues, ENABLE_PUBLISHING_SETTING );
if ( enabled ) {
return new EventPublishingServiceImpl();
}
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.