big improvements to docs surrounding ConnectionProvider

Author: gavinking

documentation/src/main/asciidoc/introduction/Tuning.adoc

@@ -36,6 +36,20 @@ The connection pool built in to Hibernate is suitable for testing, but isn't int
 Instead, Hibernate supports several different connection pools, including our favorite, Agroal.
 
 Hibernate will automatically make use of `AgroalConnectionProvider` if the module `org.hibernate.orm:hibernate-agroal` is available at runtime.
+So just add it as a runtime dependency, and you're all set.
+
+Well, actually, that's a bit fragile, since Hibernate silently falls back to using the default connection pool if Agroal happens to be missing at runtime.
+Perhaps it's better to set this configuration property:
+
+[%breakable,cols="37,~"]
+|===
+| Configuration property name | Purpose
+
+| link:{doc-javadoc-url}/org/hibernate/cfg/JdbcSettings.html#CONNECTION_PROVIDER[`hibernate.connection.provider_class`] | Explicitly specify a link:{doc-javadoc-url}/org/hibernate/engine/jdbc/connections/spi/ConnectionProvider.html[connection pool], for example, `agroal`, `hikaricp`, `c3p0`, or `oracleucp`.
+|===
+
+TIP: You can set `hibernate.connection.provider_class` to `agroal` so that Hibernate fails at startup if Agroal is missing.
+
 
 To properly configure Agroal, you'll need to set some extra configuration properties, in addition to the settings we already saw in <<basic-configuration-settings>>.
 Properties with the prefix `hibernate.agroal` are passed through to Agroal:
@@ -100,9 +114,11 @@ All we need to do is set a single property:
 |===
 | Configuration property name | Purpose | Alternative
 
-| `hibernate.jdbc.batch_size` | Maximum batch size for SQL statement batching | `setJdbcBatchSize()`
+| link:{doc-javadoc-url}/org/hibernate/cfg/BatchSettings.html#STATEMENT_BATCH_SIZE[`hibernate.jdbc.batch_size`] | Maximum batch size for SQL statement batching | `setJdbcBatchSize()`
 |===
 
+That said, batching is rarely the most convenient or most efficient way to update or delete many rows at once.
+
 [TIP]
 ====
 Even better than DML statement batching is the use of HQL `update` or `delete` queries, or even native SQL that calls a stored procedure!

hibernate-core/src/main/java/org/hibernate/cfg/CacheSettings.java

@@ -6,7 +6,6 @@
 
 import org.hibernate.Incubating;
 import org.hibernate.annotations.CacheLayout;
-import org.hibernate.cache.internal.NoCachingRegionFactory;
 import org.hibernate.cache.spi.RegionFactory;
 import org.hibernate.cache.spi.TimestampsCacheFactory;
 import org.hibernate.jpa.SpecHints;
@@ -111,14 +110,21 @@ public interface CacheSettings {
 	/**
 	 * The {@link RegionFactory} implementation, either:
 	 * <ul>
-	 *     <li>an instance of {@link RegionFactory},
-	 *     <li>a {@link Class} implementing {@link RegionFactory}, or
-	 *     <li>the name of a class implementing {@link RegionFactory}.
+	 *     <li>a short strategy name, for example, {@code jcache} or
+	 *         {@code infinispan},
+	 *     <li>an instance of {@code RegionFactory},
+	 *     <li>a {@link Class} object representing a class that implements
+	 *         {@code RegionFactory}, or
+	 *     <li>the name of a class implementing {@code RegionFactory}.
 	 * </ul>
-	 * <p>
-	 * Defaults to {@link NoCachingRegionFactory}, so that caching is disabled.
+	 *
+	 * @settingDefault {@link org.hibernate.cache.internal.NoCachingRegionFactory},
+	 *                 so that caching is disabled.
 	 *
 	 * @see #USE_SECOND_LEVEL_CACHE
+	 *
+	 * @apiNote The term {@code "class"} appears in the setting name due to legacy reasons;
+	 *          however it can accept instances.
 	 */
 	String CACHE_REGION_FACTORY = "hibernate.cache.region.factory_class";
 

hibernate-core/src/main/java/org/hibernate/cfg/JdbcSettings.java

@@ -234,11 +234,28 @@ public interface JdbcSettings extends C3p0Settings, AgroalSettings, HikariCPSett
 	 * Specifies a {@link ConnectionProvider} to use for obtaining JDBC connections,
 	 * either:
 	 * <ul>
+	 *     <li>a short strategy name like {@code agroal}, {@code hikaricp},
+	 *         {@code c3p0}, or {@code ucp},
 	 *     <li>an instance of {@code ConnectionProvider},
-	 *     <li>a {@link Class} representing a class that implements
+	 *     <li>a {@link Class} object representing a class that implements
 	 *         {@code ConnectionProvider}, or
 	 *     <li>the name of a class that implements {@code ConnectionProvider}.
 	 * </ul>
+	 * <p>
+	 * If this property is not explicitly set, a connection provider is chosen
+	 * automatically:
+	 * <ul>
+	 * <li>if {@link #JAKARTA_JTA_DATASOURCE} or {@link #JAKARTA_NON_JTA_DATASOURCE}
+	 *     is set, {@linkplain org.hibernate.engine.jdbc.connections.internal.DatasourceConnectionProviderImpl
+	 *     a datasource-based implementation} is used;
+	 * <li>otherwise, a {@code ConnectionProvider} is loaded automatically as a
+	 *     {@linkplain java.util.ServiceLoader Java service};
+	 * <li>but if no service is found, or if more than one service is available,
+	 *     {@linkplain org.hibernate.engine.jdbc.connections.internal.DriverManagerConnectionProviderImpl
+	 *     a default implementation} is used as a fallback.
+	 * </ul>
+	 * <p>
+	 * The default implementation is not recommended for use in production.
 	 *
 	 * @apiNote The term {@code "class"} appears in the setting name due to legacy reasons;
 	 *          however it can accept instances.

hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/ConnectionProvider.java

@@ -3,6 +3,7 @@
  * Copyright Red Hat Inc. and Hibernate Authors
  */
 package org.hibernate.engine.jdbc.connections.spi;
+
 import java.sql.Connection;
 import java.sql.SQLException;