diff --git a/documentation/src/main/docbook/integration/en-US/chapters/services/Services.xml b/documentation/src/main/docbook/integration/en-US/chapters/services/Services.xml
index 3701eb21b6..384e40640a 100644
--- a/documentation/src/main/docbook/integration/en-US/chapters/services/Services.xml
+++ b/documentation/src/main/docbook/integration/en-US/chapters/services/Services.xml
@@ -9,1105 +9,515 @@
- Services
+ Services and Registries
+
+
+ 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.
+
- What are services?
-
- 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).
-
-
+ What is a Service?
-
- Service contracts
- 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.
+ 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.
-
- 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.
-
-
-
- Service dependencies
- Services are allowed to declare dependencies on other services using either of 2 approaches.
+ 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.
+
+
- @<interfacename>org.hibernate.service.spi.InjectService</interfacename>
+ Service contracts
+
- Any method on the service implementation class accepting a single parameter and annotated with
- @InjectService is considered requesting injection of another service.
+ 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.
+
- 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 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
- should be declared as false (default is true).
+ 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
+ .
+
+
+
+
+ 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
+
+
+
+
-
- <interfacename>org.hibernate.service.spi.ServiceRegistryAwareService</interfacename>
+
+
+ Service dependencies
- 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.
+ Services are allowed to declare dependencies on other services using either of 2 approaches.
+
+ @<interfacename>org.hibernate.service.spi.InjectService</interfacename>
+
+ 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).
+
+
+
+ <interfacename>org.hibernate.service.spi.ServiceRegistryAwareService</interfacename>
+
+ 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.
+
+
+
- ServiceRegistry
+ What is a ServiceRegistry?
+
- 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.
+ A ServiceRegistry, at its most basic, hosts and manages Services. Its contract is defined by the
+ org.hibernate.service.ServiceRegistry interface.
+
- Service registries are hierarchical. Services in one registry can depend on and utilize services in that
- same registry as well as any parent registries.
+ 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.
+
- Use org.hibernate.boot.registry.StandardServiceRegistryBuilder to build a
- org.hibernate.service.ServiceRegistry instance.
+ In a concise definition, the ServiceRegistry acts as a inversion-of-control (IoC) container.
-
-
-
- Standard services
-
-
- <interfacename>org.hibernate.engine.jdbc.batch.spi.BatchBuilder</interfacename>
-
-
- Notes
-
-
- Defines strategy for how Hibernate manages JDBC statement batching
-
-
-
-
- Initiator
-
-
- org.hibernate.engine.jdbc.batch.internal.BatchBuilderInitiator
-
-
-
-
- Implementations
-
-
- org.hibernate.engine.jdbc.batch.internal.BatchBuilderImpl
-
-
-
-
-
-
-
- <interfacename>org.hibernate.engine.config.spi.ConfigurationService</interfacename>
-
-
- Notes
-
-
- Provides access to the configuration settings, combining those explicitly provided as well
- as those contributed by any registered
- org.hibernate.integrator.spi.Integrator implementations
-
-
-
-
- Initiator
-
-
- org.hibernate.engine.config.internal.ConfigurationServiceInitiator
-
-
-
-
- Implementations
-
-
- org.hibernate.engine.config.internal.ConfigurationServiceImpl
-
-
-
-
-
-
-
- <interfacename>ConnectionProvider</interfacename>
-
-
- Notes
-
-
- Defines the means in which Hibernate can obtain and release
- java.sql.Connection instances for its use.
-
-
-
-
- Initiator
-
-
- ConnectionProviderInitiator
-
-
-
-
- Implementations
-
-
-
-
- org.hibernate.service.jdbc.connections.internal.C3P0ConnectionProvider -
- provides connection pooling based on integration with the C3P0 connection pooling library
-
-
-
-
- DatasourceConnectionProviderImpl -
- provides connection managed delegated to a
- javax.sql.DataSource
-
-
-
-
- DriverManagerConnectionProviderImpl -
- provides rudimentary connection pooling based on simple custom pool. Note intended
- production use!
-
-
-
-
- org.hibernate.service.jdbc.connections.internal.ProxoolConnectionProvider -
- provides connection pooling based on integration with the proxool connection pooling library
-
-
-
-
- UserSuppliedConnectionProviderImpl -
- Provides no connection support. Indicates the user will supply connections to Hibernate directly.
- Not recommended for use.
-
-
-
-
-
-
-
-
-
- <interfacename>org.hibernate.engine.jdbc.dialect.spi.DialectFactory</interfacename>
-
-
- Notes
-
-
- Contract for Hibernate to obtain org.hibernate.dialect.Dialect
- instance to use. This is either explicitly defined by the
- hibernate.dialect property or determined by the
- service which is a delegate to this service.
-
-
-
-
- Initiator
-
-
- org.hibernate.engine.jdbc.dialect.internal.DialectFactoryInitiator
-
-
-
-
- Implementations
-
-
- org.hibernate.engine.jdbc.dialect.internal.DialectFactoryImpl
-
-
-
-
-
-
-
- <interfacename>org.hibernate.engine.jdbc.dialect.spi.DialectResolver</interfacename>
-
-
- Notes
-
-
- Provides resolution of org.hibernate.dialect.Dialect to use based on
- information extracted from JDBC metadata.
-
-
- The standard resolver implementation acts as a chain, delegating to a series of individual
- resolvers. The standard Hibernate resolution behavior is contained in
- org.hibernate.engine.jdbc.dialect.internal.StandardDatabaseMetaDataDialectResolver.
- org.hibernate.engine.jdbc.dialect.internal.DialectResolverInitiator
- also consults with the hibernate.dialect_resolvers setting for any
- custom resolvers.
-
-
-
-
- Initiator
-
-
- org.hibernate.engine.jdbc.dialect.internal.DialectResolverInitiator
-
-
-
-
- Implementations
-
-
- org.hibernate.engine.jdbc.dialect.internal.DialectResolverSet
-
-
-
-
-
-
-
- <interfacename>org.hibernate.engine.jdbc.spi.JdbcServices</interfacename>
-
-
- Notes
-
-
- Special type of service that aggregates together a number of other services and provides
- a higher-level set of functionality.
-
-
-
-
- Initiator
-
-
- org.hibernate.engine.jdbc.internal.JdbcServicesInitiator
-
-
-
-
- Implementations
-
-
- org.hibernate.engine.jdbc.internal.JdbcServicesImpl
-
-
-
-
-
-
-
- <interfacename>org.hibernate.jmx.spi.JmxService</interfacename>
-
-
- Notes
-
-
- Provides simplified access to JMX related features needed by Hibernate.
-
-
-
-
- Initiator
-
-
- org.hibernate.jmx.internal.JmxServiceInitiator
-
-
-
-
- Implementations
-
-
-
-
- org.hibernate.jmx.internal.DisabledJmxServiceImpl -
- A no-op implementation when JMX functionality is disabled.
-
-
-
-
- org.hibernate.jmx.internal.JmxServiceImpl -
- Standard implementation of JMX handling
-
-
-
-
-
-
-
-
-
- <interfacename>org.hibernate.engine.jndi.spi.JndiService</interfacename>
-
-
- Notes
-
-
- Provides simplified access to JNDI related features needed by Hibernate.
-
-
-
-
- Initiator
-
-
- org.hibernate.engine.jndi.internal.JndiServiceInitiator
-
-
-
-
- Implementations
-
-
- org.hibernate.engine.jndi.internal.JndiServiceImpl
-
-
-
-
-
-
-
- <interfacename>org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform</interfacename>
-
-
- Notes
-
-
- Provides an abstraction from the underlying JTA platform when JTA features are used.
-
-
-
-
- Initiator
-
-
- org.hibernate.engine.transaction.jta.platform.internal.JtaPlatformInitiator
-
-
-
- As of 5.0 support has been completely removed for mapping against legacy
- org.hibernate.transaction.TransactionManagerLookup
- names and custom implementations. Applications implementing
- org.hibernate.transaction.TransactionManagerLookup
- or using the hibernate.transaction.manager_lookup_class setting
- should update to use JtaPlatform.
-
-
-
-
-
- Implementations
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.BitronixJtaPlatform -
- Integration with the Bitronix stand-alone transaction manager. Can also be referenced
- using the Bitronix configuration short name
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.BorlandEnterpriseServerJtaPlatform -
- Integration with the transaction manager as deployed within a Borland Enterprise Server.
- Can also be referenced using the Borland configuration short name
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.JBossAppServerJtaPlatform -
- Integration with the transaction manager as deployed within a JBoss Application Server.
- Can also be referenced using the JBossAS configuration short name
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.JBossStandAloneJtaPlatform -
- Integration with the JBoss Transactions stand-alone transaction manager.
- Can also be referenced using the JBossTS configuration short name
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.JOTMJtaPlatform -
- Integration with the JOTM stand-alone transaction manager. Can also be referenced
- using the JOTM configuration short name
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.JOnASJtaPlatform -
- Integration with the JOnAS transaction manager. Can also be referenced using the
- JOnAS configuration short name
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.JRun4JtaPlatform -
- Integration with the transaction manager as deployed in a JRun 4 application server.
- Can also be referenced using the JRun4 configuration short name
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.NoJtaPlatform -
- No-op version when no JTA set up is configured
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.OC4JJtaPlatform -
- Integration with transaction manager as deployed in an OC4J (Oracle) application
- Can also be referenced using the OC4J configuration short name
- server.
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.OrionJtaPlatform -
- Integration with transaction manager as deployed in an Orion application server.
- Can also be referenced using the Orion configuration short name
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.ResinJtaPlatform -
- Integration with transaction manager as deployed in a Resin application server.
- Can also be referenced using the Resin configuration short name
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.SunOneJtaPlatform -
- Integration with transaction manager as deployed in a Sun ONE (7 and above)
- application server. Can also be referenced using the SunOne
- configuration short name
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.WebSphereExtendedJtaPlatform -
- Integration with transaction manager as deployed in a WebSphere Application Server
- (6 and above). Can also be referenced using the WebSphereExtended
- configuration short name
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.WebSphereJtaPlatform -
- Integration with transaction manager as deployed in a WebSphere Application Server
- (4, 5.0 and 5.1). Can also be referenced using the WebSphere
- configuration short name
-
-
-
-
- org.hibernate.engine.transaction.jta.platform.internal.WeblogicJtaPlatform -
- Integration with transaction manager as deployed in a Weblogic application server.
- Can also be referenced using the Weblogic configuration short name
-
-
-
-
-
-
-
-
-
- <interfacename>MultiTenantConnectionProvider</interfacename>
-
-
- Notes
-
-
- A variation of providing access to JDBC
- connections in multi-tenant environments.
-
-
-
-
- Initiator
-
-
- N/A
-
-
-
-
- Implementations
-
-
- Intended that users provide appropriate implementation if needed.
-
-
-
-
-
-
-
- <interfacename>org.hibernate.persister.spi.PersisterClassResolver</interfacename>
-
-
- Notes
-
-
- Contract for determining the appropriate
- org.hibernate.persister.entity.EntityPersister
- or org.hibernate.persister.collection.CollectionPersister
- implementation class to use given an entity or collection mapping.
-
-
-
-
- Initiator
-
-
- org.hibernate.persister.internal.PersisterClassResolverInitiator
-
-
-
-
- Implementations
-
-
- org.hibernate.persister.internal.StandardPersisterClassResolver
-
-
-
-
-
-
-
- <interfacename>org.hibernate.persister.spi.PersisterFactory</interfacename>
-
-
- Notes
-
-
- Factory for creating
- org.hibernate.persister.entity.EntityPersister
- and org.hibernate.persister.collection.CollectionPersister
- instances.
-
-
-
-
- Initiator
-
-
- org.hibernate.persister.internal.PersisterFactoryInitiator
-
-
-
-
- Implementations
-
-
- org.hibernate.persister.internal.PersisterFactoryImpl
-
-
-
-
-
-
-
- <interfacename>org.hibernate.cache.spi.RegionFactory</interfacename>
-
-
- Notes
-
-
- Integration point for Hibernate's second level cache support.
-
-
-
-
- Initiator
-
-
- org.hibernate.cache.internal.RegionFactoryInitiator
-
-
-
-
- Implementations
-
-
-
-
- org.hibernate.cache.ehcache.EhCacheRegionFactory
-
-
-
-
- org.hibernate.cache.infinispan.InfinispanRegionFactory
-
-
-
-
- org.hibernate.cache.infinispan.JndiInfinispanRegionFactory
-
-
-
-
- org.hibernate.cache.internal.NoCachingRegionFactory
-
-
-
-
- org.hibernate.cache.ehcache.SingletonEhCacheRegionFactory
-
-
-
-
-
-
-
-
-
- <interfacename>org.hibernate.service.spi.SessionFactoryServiceRegistryFactory</interfacename>
-
-
- Notes
-
-
- Factory for creating
- org.hibernate.service.spi.SessionFactoryServiceRegistry
- instances which acts as a specialized
- org.hibernate.service.ServiceRegistry for
- org.hibernate.SessionFactory scoped services. See
- for more details.
-
-
-
-
- Initiator
-
-
- org.hibernate.service.internal.SessionFactoryServiceRegistryFactoryInitiator
-
-
-
-
- Implementations
-
-
- org.hibernate.service.internal.SessionFactoryServiceRegistryFactoryImpl
-
-
-
-
-
-
-
- <interfacename>org.hibernate.stat.Statistics</interfacename>
-
-
- Notes
-
-
- Contract for exposing collected statistics. The statistics are collected through the
- org.hibernate.stat.spi.StatisticsImplementor contract.
-
-
-
-
- Initiator
-
-
- org.hibernate.stat.internal.StatisticsInitiator
-
-
- Defines a hibernate.stats.factory setting to allow
- configuring the
- org.hibernate.stat.spi.StatisticsFactory to use internally
- when building the actual
- org.hibernate.stat.Statistics instance.
-
-
-
-
- Implementations
-
-
- org.hibernate.stat.internal.ConcurrentStatisticsImpl
-
-
- The default org.hibernate.stat.spi.StatisticsFactory
- implementation builds a
- org.hibernate.stat.internal.ConcurrentStatisticsImpl instance.
-
-
-
-
-
-
-
- <interfacename>org.hibernate.engine.transaction.spi.TransactionFactory</interfacename>
-
-
- Notes
-
-
- Strategy defining how Hibernate's org.hibernate.Transaction
- API maps to the underlying transaction approach.
-
-
-
-
- Initiator
-
-
- org.hibernate.engine.transaction.internal.TransactionFactoryInitiator
-
-
- Defines a hibernate.transaction.factory_class setting to allow
- configuring which TransactionFactory to use.
- hibernate.transaction.factory_class follows the rules set forth
- under .
-
-
-
-
- Implementations
-
-
-
-
- org.hibernate.engine.transaction.internal.jdbc.JdbcTransactionFactory -
- A non-JTA strategy in which the transactions are managed using the JDBC
- java.sql.Connection. This implementation's short
- name is jdbc.
-
-
-
-
- org.hibernate.engine.transaction.internal.jta.CMTTransactionFactory -
- A JTA-based strategy in which Hibernate is not controlling the transactions. An
- important distinction here is that interaction with the underlying JTA implementation
- is done through the
- javax.transaction.TransactionManager. This
- implementation's short name is cmt.
-
-
-
-
- org.hibernate.engine.transaction.internal.jta.JtaTransactionFactory -
- A JTA-based strategy in which Hibernate *may* be controlling the transactions. An
- important distinction here is that interaction with the underlying JTA
- implementation is done through the
- javax.transaction.UserTransaction. This
- implementation's short name is jta.
-
-
-
-
-
-
-
-
-
- <interfacename>org.hibernate.tool.hbm2ddl.ImportSqlCommandExtractor</interfacename>
-
-
- Notes
-
-
- Contract for extracting statements from import.sql scripts.
-
-
-
-
- Initiator
-
-
- org.hibernate.tool.hbm2ddl.ImportSqlCommandExtractorInitiator
-
-
-
-
- Implementations
-
-
-
-
- org.hibernate.tool.hbm2ddl.SingleLineSqlCommandExtractor
- treats each line as a complete SQL statement. Comment lines shall start with
- --, // or /* character
- sequence.
-
-
-
-
- org.hibernate.tool.hbm2ddl.MultipleLinesSqlCommandExtractor
- supports instructions/comments and quoted strings spread over multiple lines. Each
- statement must end with semicolon.
-
-
-
-
-
-
-
-
-
-
-
-
- Custom services
-
- 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.boot.registry.StandardServiceRegistryBuilder 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.boot.registry.StandardServiceRegistryBuilder about
- custom services.
-
-
-
-
- Implement a org.hibernate.boot.registry.StandardServiceInitiator class
- to control on-demand construction of the service class and add it to the
- org.hibernate.boot.registry.StandardServiceRegistryBuilder via its
- addInitiator method.
-
-
-
-
- Just instantiate the service class and add it to the
- org.hibernate.boot.registry.StandardServiceRegistryBuilder 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).
-
-
-
-
-
- Special service registries
-
-
- Boot-strap registry
-
- The boot-strap registry holds services that absolutely have to be available for most things to work.
- The main service here is the 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.boot.registry.BootstrapServiceRegistryBuilder class.
-
-
-
- Using BootstrapServiceRegistryBuilder
-
-
-
-
- Bootstrap registry services
-
- <interfacename>org.hibernate.boot.registry.classloading.spi.ClassLoaderService</interfacename>
-
- Hibernate needs to interact with ClassLoaders. However, 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 single-swappable-component manner.
-
-
- In terms of interacting with a ClassLoader, Hibernate needs the following capabilities:
-
-
-
- the ability to locate application classes
-
-
-
-
- the ability to locate integration classes
-
-
-
-
- the ability to locate resources (properties files, xml files, etc)
-
-
-
-
- the ability to load java.util.ServiceLoader
-
-
-
-
-
-
- Currently, the ability to load application classes and the ability to load integration
- classes are combined into a single "load class" capability on the service. That may
- change in a later release.
-
-
-
-
-
- <interfacename>org.hibernate.integrator.spi.IntegratorService</interfacename>
-
- Applications, add-ons and others all need to integrate with Hibernate which used to require
- something, usually the application, to coordinate registering the pieces of each integration
- needed on behalf of each integrator. The intent of this service is to allow those integrators
- to be discovered and to have them integrate themselves with Hibernate.
-
-
- This service focuses on the discovery aspect. It leverages the standard Java
- java.util.ServiceLoader capability provided by the
- org.hibernate.boot.registry.classloading.spi.ClassLoaderService
- in order to discover implementations of the
- org.hibernate.integrator.spi.Integrator contract.
- Integrators would simply define a file named
- /META-INF/services/org.hibernate.integrator.spi.Integrator and make it
- available on the classpath. java.util.ServiceLoader covers the
- format of this file in detail, but essentially it list classes by FQN that implement the
- org.hibernate.integrator.spi.Integrator one per line.
-
-
- See
-
-
-
-
-
-
- SessionFactory registry
-
- While it is best practice to treat instances of all the registry types as targeting a given
- org.hibernate.SessionFactory, the instances of services in this group
- explicitly belong to a single org.hibernate.SessionFactory. The
- difference is a matter of timing in when they need to be initiated. Generally they need access to the
- org.hibernate.SessionFactory to be initiated. This special registry is
- org.hibernate.service.spi.SessionFactoryServiceRegistry
-
-
-
- <interfacename>org.hibernate.event.service.spi.EventListenerRegistry</interfacename>
-
-
- Notes
-
-
- Service for managing event listeners.
-
-
-
-
- Initiator
-
-
- org.hibernate.event.service.internal.EventListenerServiceInitiator
-
-
-
-
- Implementations
-
-
- org.hibernate.event.service.internal.EventListenerRegistryImpl
-
-
-
-
-
-
-
-
-
-
-
- Using services and registries
-
- Coming soon...
-
-
-
-
- Integrators
-
- 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
+ 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.
+
- See
-
-
- In addition to the discovery approach provided by the IntegratorService, applications can manually
- register Integrator implementations when building the BootstrapServiceRegistry.
- See
+ 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.
-
- Integrator use-cases
+
+ 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.
+
+
+
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+
+
+ Types of ServiceRegistries
+
+
+ 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.
+
+
+
+ BootstrapServiceRegistry
+
- 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.
+ 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.
-
- Registering event listeners
-
-
+
+
+ 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).
+
+
+
+ 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 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
+
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+ 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 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
+
+
+
+
+
+
+
+
+ StandardServiceRegistry
+
+
+ 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).
+
+
+
+ ConnectionProvider/MultiTenantConnectionProvider
+
+ 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
+
+
+
+
+
+
+ JdbcServices
+
+ org.hibernate.engine.jdbc.spi.JdbcServices is an aggregator
+ Service (a Service that aggregates other Services) exposing unified functionality around JDBC
+ accessibility.
+
+
+
+
+ TransactionCoordinatorBuilder
+
+ 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.
+
+
+
+
+ JtaPlatform
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+
+
+ SessionFactoryServiceRegistry
+
+
+ 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:
+
+
+
+ EventListenerRegistry
+
+ 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)
+
+
+
+
+
+ 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
+
+ To be honest, I have no idea why this is a service... :)
+
+
+
\ No newline at end of file
diff --git a/documentation/src/main/docbook/integration/en-US/images/hibernate_logo_a.png b/documentation/src/main/docbook/integration/en-US/images/hibernate_logo_a.png
new file mode 100644
index 0000000000..0a343c4bca
Binary files /dev/null and b/documentation/src/main/docbook/integration/en-US/images/hibernate_logo_a.png differ
diff --git a/documentation/src/main/docbook/manual/en-US/chapters/transactions/Transactions.xml b/documentation/src/main/docbook/manual/en-US/chapters/transactions/Transactions.xml
index dce2e2754a..842cb71991 100644
--- a/documentation/src/main/docbook/manual/en-US/chapters/transactions/Transactions.xml
+++ b/documentation/src/main/docbook/manual/en-US/chapters/transactions/Transactions.xml
@@ -74,6 +74,13 @@
+
+
+ For details on implementing a custom TransactionCoordinatorBuilder, or simply better understanding
+ how it works, see the Integrations Guide
+
+
+
Hibernate uses JDBC connections and JTA resources directly, without adding any additional locking behavior.
Hibernate does not lock objects in memory. The behavior defined by the isolation level of your database