true if the connection is valid, false 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;
diff --git a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/AbstractMultiTenantConnectionProvider.java b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/AbstractMultiTenantConnectionProvider.java
index c4fbdd49bd..b383666864 100644
--- a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/AbstractMultiTenantConnectionProvider.java
+++ b/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.
+ * + * This class is meant to be subclassed to implement application-specific + * requirements. * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/ConnectionProvider.java b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/ConnectionProvider.java index 45d78b79aa..542b0414c2 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/ConnectionProvider.java +++ b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/ConnectionProvider.java @@ -18,9 +18,18 @@ import org.hibernate.service.spi.Wrapped; *
* A {@code ConnectionProvider} may be selected using the configuration property * {@value org.hibernate.cfg.AvailableSettings#CONNECTION_PROVIDER}. + *
+ * 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. + *
+ * 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? *
* 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. *
* Typically, this is only true in managed environments where a container tracks connections diff --git a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/MultiTenantConnectionProvider.java b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/MultiTenantConnectionProvider.java index b9fed3a2ce..9668124fd6 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/MultiTenantConnectionProvider.java +++ b/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. + *
+ * A {@code MultiTenantConnectionProvider} may be selected using the configuration property + * {@value org.hibernate.cfg.AvailableSettings#MULTI_TENANT_CONNECTION_PROVIDER}. + *
+ * 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? *
* 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. *
* Typically, this is only true in managed environments where a container tracks connections * by transaction or thread. - * + *
* Note that JTA semantic depends on the fact that the underlying connection provider does * support aggressive release. * diff --git a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/package-info.java b/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/package-info.java index b3f79460ac..da15f40c22 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/package-info.java +++ b/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}. + *
+ * Typically, the provider is responsible not just for connecting to the database, + * but also for pooling connections and caching {@link java.sql.PreparedStatement}s. + *
+ * There are two flavors of connection provider: + *