jdoc for org.hibernate.engine.jdbc.connections.spi

hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/internal/ConnectionCreator.java

@@ -22,9 +22,9 @@ interface ConnectionCreator {
 	String getUrl();
 
 	/**
-	 * Create a Connection
+	 * Create a {@link Connection}
 	 *
-	 * @return The created Connection
+	 * @return The newly-created {@link Connection}
 	 */
 	Connection createConnection();
 }

hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/internal/ConnectionValidator.java

@@ -19,9 +19,9 @@ public interface ConnectionValidator {
 	ConnectionValidator ALWAYS_VALID = connection -> true;
 
 	/**
-	 * Checks if the connection is still valid
+	 * Checks if the given connection is still valid.
 	 *
-	 * @return <code>true</code> if the connection is valid, <code>false</code> otherwise
+	 * @return {@code true} if the connection is valid, {@code false} otherwise
 	 * @throws SQLException when an error happens due to the connection usage leading to a connection close
 	 */
 	boolean isValid(Connection connection) throws SQLException;

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

@@ -14,6 +14,9 @@ import org.hibernate.service.UnknownUnwrapTypeException;
 /**
  * Basic support for {@link MultiTenantConnectionProvider} implementations using
  * individual {@link ConnectionProvider} instances per tenant behind the scenes.
+ * <p>
+ * This class is meant to be subclassed to implement application-specific
+ * requirements.
  *
  * @author Steve Ebersole
  */

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

@@ -18,9 +18,18 @@ import org.hibernate.service.spi.Wrapped;
  * <p>
  * A {@code ConnectionProvider} may be selected using the configuration property
  * {@value org.hibernate.cfg.AvailableSettings#CONNECTION_PROVIDER}.
+ * <p>
+ * It's not usual for an applications to implement its on {@code ConnectionProvider}.
+ * Instead, the Hibernate project provides pre-built implementations for a variety of
+ * connection pools as add-on modules.
+ * <p>
+ * On the other hand, this is an extremely important extension point for integration
+ * with containers and frameworks.
  *
  * @author Gavin King
  * @author Steve Ebersole
+ *
+ * @see org.hibernate.cfg.AvailableSettings#CONNECTION_PROVIDER
  */
 public interface ConnectionProvider extends Service, Wrapped {
 	/**
@@ -48,7 +57,7 @@ public interface ConnectionProvider extends Service, Wrapped {
 	 * re-acquisition of those connections if needed?
 	 * <p>
 	 * This is used in conjunction with {@link org.hibernate.ConnectionReleaseMode#AFTER_STATEMENT}
-	 * to aggressively release JDBC connections.  However, the configured ConnectionProvider
+	 * to aggressively release JDBC connections.  However, the configured {@link ConnectionProvider}
 	 * must support re-acquisition of the same underlying connection for that semantic to work.
 	 * <p>
 	 * Typically, this is only true in managed environments where a container tracks connections

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

@@ -13,15 +13,24 @@ import org.hibernate.service.Service;
 import org.hibernate.service.spi.Wrapped;
 
 /**
- * A specialized Connection provider contract used when the application is using multi-tenancy support requiring
- * tenant aware connections.
+ * A specialized {@link Connection} provider contract used when the application is using
+ * multi-tenancy support requiring tenant-aware connections.
+ * <p>
+ * A {@code MultiTenantConnectionProvider} may be selected using the configuration property
+ * {@value org.hibernate.cfg.AvailableSettings#MULTI_TENANT_CONNECTION_PROVIDER}.
+ * <p>
+ * An application usually implements its own custom {@code MultiTenantConnectionProvider}
+ * by subclassing {@link AbstractMultiTenantConnectionProvider}.
  *
  * @author Steve Ebersole
+ *
+ * @see AbstractMultiTenantConnectionProvider
+ * @see org.hibernate.cfg.AvailableSettings#MULTI_TENANT_CONNECTION_PROVIDER
  */
 public interface MultiTenantConnectionProvider extends Service, Wrapped {
 	/**
-	 * Allows access to the database metadata of the underlying database(s) in situations where we do not have a
-	 * tenant id (like startup processing, for example).
+	 * Allows access to the database metadata of the underlying database(s) in situations
+	 * where we do not have a tenant id (like startup processing, for example).
 	 *
 	 * @return The database metadata.
 	 *
@@ -39,7 +48,7 @@ public interface MultiTenantConnectionProvider extends Service, Wrapped {
 	void releaseAnyConnection(Connection connection) throws SQLException;
 
 	/**
-	 * Obtains a connection for Hibernate use according to the underlying strategy of this provider.
+	 * Obtains a connection for use according to the underlying strategy of this provider.
 	 *
 	 * @param tenantIdentifier The identifier of the tenant for which to get a connection
 	 *
@@ -66,12 +75,12 @@ public interface MultiTenantConnectionProvider extends Service, Wrapped {
 	 * re-acquisition of those connections if needed?
 	 * <p>
 	 * This is used in conjunction with {@link org.hibernate.ConnectionReleaseMode#AFTER_STATEMENT}
-	 * to aggressively release JDBC connections.  However, the configured ConnectionProvider
+	 * to aggressively release JDBC connections. However, the configured {@link ConnectionProvider}
 	 * must support re-acquisition of the same underlying connection for that semantic to work.
 	 * <p>
 	 * Typically, this is only true in managed environments where a container tracks connections
 	 * by transaction or thread.
-	 *
+	 * <p>
 	 * Note that JTA semantic depends on the fact that the underlying connection provider does
 	 * support aggressive release.
 	 *

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

@@ -8,7 +8,19 @@
 /**
  * Defines SPI contracts for obtaining JDBC {@link java.sql.Connection}s from a
  * provider implemented as a {@linkplain org.hibernate.service.Service service}.
+ * <p>
+ * Typically, the provider is responsible not just for connecting to the database,
+ * but also for pooling connections and caching {@link java.sql.PreparedStatement}s.
+ * <p>
+ * There are two flavors of connection provider:
+ * <ul>
+ * <li>{@link org.hibernate.engine.jdbc.connections.spi.ConnectionProvider} is
+ *     for general use, and
+ * <li>{@link org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider}
+ *     for use in a multi-tenant environment.
+ * </ul>
  *
  * @see org.hibernate.engine.jdbc.connections.spi.ConnectionProvider
+ * @see org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider
  */
 package org.hibernate.engine.jdbc.connections.spi;