diff --git a/documentation/src/main/asciidoc/topical/registries/ServiceRegistries.adoc b/documentation/src/main/asciidoc/topical/registries/ServiceRegistries.adoc index 32c25e5d14..32e930d23d 100644 --- a/documentation/src/main/asciidoc/topical/registries/ServiceRegistries.adoc +++ b/documentation/src/main/asciidoc/topical/registries/ServiceRegistries.adoc @@ -177,18 +177,98 @@ The service role for this service is +org.hibernate.boot.registry.selector.spi.S === 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: + +==== 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. + +==== TransactionFactory + ++org.hibernate.engine.transaction.spi.TransactionFactory+ is used to tell Hibernate how to control or integrate +with transactions. + + +==== JtaPlatform + +When using a JTA-based +TransactionFactory+, the +org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform+ +Service provides Hibernate access to the JTA +TransactionManager+ and +UserTransaction+, as well handling ++Synchronization+ registration. + +Here are the steps (in order of precedence) that Hibernate follows to determine the +JtaPlatform+ to use: + +. Explicit setting keyed as +"hibernate.transaction.jta.platform"+ which can refer to +** a +JtaPlatform+ instance +** a +Class+ reference +** the name (see StrategySelector service) of a +JtaPlatform+ strategy +** the FQN of a +JtaPlatform+ implementation +. Discover via the +org.hibernate.engine.transaction.jta.platform.spi.JtaPlatformResolver+ Service, which by default: +** looks for +org.hibernate.engine.transaction.jta.platform.spi.JtaPlatformProvider+ implementations via +ServiceLoader+, +if one is found its reported +JtaPlatform+ is used (first wins). +** Attempts a number of well-known Class lookups for various environments. + + +==== RegionFactory + +This is the second level cache service. + +==== SessionFactoryServiceRegistryFactory + ++org.hibernate.service.spi.SessionFactoryServiceRegistryFactory+ is a service that acts as a factory for building the +third type of ServiceRegistry, +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. This may very well change in 5.0 + + === SessionFactoryServiceRegistry ++org.hibernate.service.spi.SessionFactoryServiceRegistry+ is the 3rd standard Hibernate ServiceRegistry. Typically, +its parent registry is the +StandardServiceRegistry+. +SessionFactoryServiceRegistry+ is designed to hold Services +which need access to the SessionFactory. Currently that is just 3 Services. + +NOTE: Integrators, as it stands in 4.x, operate on the SessionFactoryServiceRegistry... + +==== EventListenerRegistry + ++org.hibernate.event.service.spi.EventListenerRegistry+ is the big Service managed in the +SessionFactoryServiceRegistry+. +This is the Service that manages and exposes 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 +org.hibernate.stat.Statistics+ API. The +collector portion, if you will. == Service lifecycle === Initiation (creation) -=== Starting/Stopping - === Configuration +=== Starting/Stopping + == Building ServiceRegistry diff --git a/hibernate-core/src/main/java/org/hibernate/service/StandardServiceInitiators.java b/hibernate-core/src/main/java/org/hibernate/service/StandardServiceInitiators.java index 64f8944e96..69900c3d74 100644 --- a/hibernate-core/src/main/java/org/hibernate/service/StandardServiceInitiators.java +++ b/hibernate-core/src/main/java/org/hibernate/service/StandardServiceInitiators.java @@ -78,8 +78,8 @@ public class StandardServiceInitiators { serviceInitiators.add( MutableIdentifierGeneratorFactoryInitiator.INSTANCE); - serviceInitiators.add( JtaPlatformInitiator.INSTANCE ); serviceInitiators.add( JtaPlatformResolverInitiator.INSTANCE ); + serviceInitiators.add( JtaPlatformInitiator.INSTANCE ); serviceInitiators.add( TransactionFactoryInitiator.INSTANCE ); serviceInitiators.add( SessionFactoryServiceRegistryFactoryInitiator.INSTANCE );