HHH-8607 - Start Topical Guide - Service Registries

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<? extends JtaPlatform>+ 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
 

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 );