improve documentation of stats.spi

hibernate-core/src/main/java/org/hibernate/stat/Statistics.java

@@ -10,13 +10,21 @@ import java.util.Map;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
- * Exposes statistics collected from all sessions belonging to a
- * particular {@link org.hibernate.SessionFactory}.
+ * Exposes statistics collected from all sessions belonging to a given
+ * {@link org.hibernate.SessionFactory}.
+ * <ul>
+ * <li>Collection of statistics is enabled if the configuration property
+ *     {@value org.hibernate.cfg.AvailableSettings#GENERATE_STATISTICS}
+ *     is set to {@code true}.
+ * <li>Alternatively, statistics collection may be enabled or disabled
+ *     at runtime by calling {@link #setStatisticsEnabled(boolean)}.
+ * </ul>
  * <p>
- * Collection of statistics is enabled if the configuration property
- * {@value org.hibernate.cfg.AvailableSettings#GENERATE_STATISTICS} is
- * set to {@code true}. It may be dynamically enabled or disabled at
- * runtime by calling {@link #setStatisticsEnabled(boolean)}.
+ * A custom statistics collector may be supplied by implementing the
+ * {@link org.hibernate.stat.spi.StatisticsImplementor} SPI, and
+ * supplying a {@link org.hibernate.stat.spi.StatisticsFactory} via
+ * the configuration setting
+ * {@value org.hibernate.cfg.StatisticsSettings#STATS_BUILDER}.
  *
  * @author Emmanuel Bernard
  */

hibernate-core/src/main/java/org/hibernate/stat/internal/StatisticsInitiator.java

@@ -38,10 +38,9 @@ public class StatisticsInitiator implements SessionFactoryServiceInitiator<Stati
 
 	@Override
 	public StatisticsImplementor initiateService(SessionFactoryServiceInitiatorContext context) {
-		final Object configValue = context.getServiceRegistry()
-				.requireService( ConfigurationService.class )
-				.getSettings()
-				.get( STATS_BUILDER );
+		final Object configValue =
+				context.getServiceRegistry().requireService( ConfigurationService.class )
+						.getSettings().get( STATS_BUILDER );
 		return initiateServiceInternal( context.getSessionFactory(), configValue, context.getServiceRegistry() );
 	}
 
@@ -50,18 +49,30 @@ public class StatisticsInitiator implements SessionFactoryServiceInitiator<Stati
 			@Nullable Object configValue,
 			ServiceRegistryImplementor registry) {
 
-		final StatisticsFactory statisticsFactory;
+		final StatisticsFactory statisticsFactory = statisticsFactory( configValue, registry );
+		final StatisticsImplementor statistics =
+				statisticsFactory == null
+						? new StatisticsImpl( sessionFactory )  // default impl
+						: statisticsFactory.buildStatistics( sessionFactory );
+		final boolean enabled = sessionFactory.getSessionFactoryOptions().isStatisticsEnabled();
+		statistics.setStatisticsEnabled( enabled );
+		LOG.debugf( "Statistics initialized [enabled=%s]", enabled );
+		return statistics;
+	}
+
+	private static @Nullable StatisticsFactory statisticsFactory(
+			@Nullable Object configValue, ServiceRegistryImplementor registry) {
 		if ( configValue == null ) {
-			statisticsFactory = null; //We'll use the default
+			return null; //We'll use the default
 		}
-		else if ( configValue instanceof StatisticsFactory ) {
-			statisticsFactory = (StatisticsFactory) configValue;
+		else if ( configValue instanceof StatisticsFactory factory ) {
+			return factory;
 		}
 		else {
 			// assume it names the factory class
 			final ClassLoaderService classLoaderService = registry.requireService( ClassLoaderService.class );
 			try {
-				statisticsFactory = (StatisticsFactory) classLoaderService.classForName( configValue.toString() ).newInstance();
+				return (StatisticsFactory) classLoaderService.classForName( configValue.toString() ).newInstance();
 			}
 			catch (HibernateException e) {
 				throw e;
@@ -73,18 +84,5 @@ public class StatisticsInitiator implements SessionFactoryServiceInitiator<Stati
 				);
 			}
 		}
-		final StatisticsImplementor statistics;
-		if ( statisticsFactory == null ) {
-			// Default:
-			statistics = new StatisticsImpl( sessionFactory );
-		}
-		else {
-			statistics = statisticsFactory.buildStatistics( sessionFactory );
-		}
-		final boolean enabled = sessionFactory.getSessionFactoryOptions().isStatisticsEnabled();
-		statistics.setStatisticsEnabled( enabled );
-		LOG.debugf( "Statistics initialized [enabled=%s]", enabled );
-		return statistics;
 	}
-
 }

hibernate-core/src/main/java/org/hibernate/stat/spi/StatisticsFactory.java

@@ -8,6 +8,9 @@ import org.hibernate.engine.spi.SessionFactoryImplementor;
 
 /**
  * Factory for custom implementations of {@link StatisticsImplementor}.
+ * <p>
+ * A custom implementation may be selected via the configuration property
+ * {@value org.hibernate.cfg.StatisticsSettings#STATS_BUILDER}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/stat/spi/StatisticsImplementor.java

@@ -13,7 +13,9 @@ import java.util.Map;
 import static java.util.Collections.emptyMap;
 
 /**
- * A service SPI for collecting statistics about various events that occur at runtime.
+ * A service SPI for collecting statistics about various events occurring at runtime.
+ * <p>
+ * A custom implementation may be provided via a {@link StatisticsFactory}.
  *
  * @author Emmanuel Bernard
  */