Package org.hibernate.engine.jdbc.connections.spi

Interface ConnectionProvider

All Superinterfaces:
Serializable, Service, Wrapped
public interface ConnectionProvider extends Service, Wrapped
A contract for obtaining JDBC connections and, optionally, for pooling connections.

Implementors must provide a public default constructor.

A ConnectionProvider may be selected using the configuration property "hibernate.connection.provider_class".

It's not usual for an application to implement its own 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.

See Also:

  • Method Details

    • getConnection

      Connection getConnection() throws SQLException
      Obtains a connection for Hibernate use according to the underlying strategy of this provider.
      Returns:
      The obtained JDBC connection
      Throws:
      SQLException - Indicates a problem opening a connection
      HibernateException - Indicates a problem obtaining a connection.

    • getReadOnlyConnection

      @Incubating default Connection getReadOnlyConnection() throws SQLException
      Obtains a connection to a read-only replica for use according to the underlying strategy of this provider.
      Returns:
      The obtained JDBC connection
      Throws:
      SQLException - Indicates a problem opening a connection
      HibernateException - Indicates a problem obtaining a connection.
      Since:
      7.2
      Implementation Note:
      This default implementation simply calls getConnection(), which returns a connection to a writable replica. If this operation is overridden to return a connection to a distinct read-only replica, the matching operation closeReadOnlyConnection(Connection) must also be overridden.

    • closeConnection

      void closeConnection(Connection connection) throws SQLException
      Release a connection from Hibernate use.
      Parameters:
      connection - The JDBC connection to release
      Throws:
      SQLException - Indicates a problem closing the connection
      HibernateException - Indicates a problem releasing a connection.

    • closeReadOnlyConnection

      @Incubating default void closeReadOnlyConnection(Connection connection) throws SQLException
      Release a connection to a read-only replica from Hibernate use.
      Parameters:
      connection - The JDBC connection to release
      Throws:
      SQLException - Indicates a problem closing the connection
      HibernateException - Indicates a problem otherwise releasing a connection.
      Since:
      7.2
      Implementation Note:
      This default implementation simply calls closeConnection(Connection). If getReadOnlyConnection() is overridden to return a connection to a distinct read-only replica, this operation must also be overridden.

    • supportsAggressiveRelease

      boolean supportsAggressiveRelease()
      Does this connection provider support aggressive release of JDBC connections and later re-acquisition of those connections if needed?

      This is used in conjunction with ConnectionReleaseMode.AFTER_STATEMENT to aggressively release JDBC connections. However, the configured 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.

      Returns:
      true if aggressive releasing is supported; false otherwise.

    • handlesConnectionSchema

      @Incubating default boolean handlesConnectionSchema()
      Does this connection provider correctly set the schema of the returned JDBC connections?
      Returns:
      true if the connection provider handles this; false if the client should set the schema
      Implementation Note:
      If necessary, a ConnectionProvider may call MultiTenancy.getTenantSchemaMapper(java.util.Map<java.lang.String, java.lang.Object>, org.hibernate.boot.registry.StandardServiceRegistry) to obtain the TenantSchemaMapper.

    • handlesConnectionReadOnly

      @Incubating default boolean handlesConnectionReadOnly()
      Does this connection provider correctly set the read-only mode of the returned JDBC connections?
      Returns:
      true if the connection provider handles this; false if the client should set the read-only mode

    • getDatabaseConnectionInfo

      default DatabaseConnectionInfo getDatabaseConnectionInfo(Dialect dialect)
      Returns:
      an informative instance of DatabaseConnectionInfo for logging.
      Since:
      6.6

    • getDatabaseConnectionInfo

      default DatabaseConnectionInfo getDatabaseConnectionInfo(Dialect dialect, ExtractedDatabaseMetaData metaData)
      Returns:
      an informative instance of DatabaseConnectionInfo for logging.
      Since:
      7.0