/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *  http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * Other licenses:
 * -----------------------------------------------------------------------------
 * Commercial licenses for this work are available. These replace the above
 * ASL 2.0 and offer limited warranties, support, maintenance, and commercial
 * database integrations.
 *
 * For more information, please visit: http://www.jooq.org/licenses
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */
package org.jooq;

import java.sql.Connection;

import org.jooq.exception.DataAccessException;
import org.jooq.exception.DetachedException;

import org.jetbrains.annotations.Nullable;

A connection lifecycle handler API.

The ConnectionProvider allows for abstracting the handling of
custom Connection lifecycles outside of jOOQ, injecting behaviour into jOOQ's internals. jOOQ will try to acquire a new JDBC Connection from the connection provider as early as needed, and will release it as early as possible. 
 TransactionProvider implementations may choose to influence ConnectionProvider behaviour, e.g. by acquiring connections upon TransactionProvider.begin(TransactionContext) and by releasing connections only upon TransactionProvider.commit(TransactionContext), or TransactionProvider.rollback(TransactionContext). 
Author:
Aaron Digulla, Lukas Eder/**
 * A connection lifecycle handler API.
 * <p>
 * The <code>ConnectionProvider</code> allows for abstracting the handling of
 * custom <code>Connection</code> lifecycles outside of jOOQ, injecting
 * behaviour into jOOQ's internals. jOOQ will try to acquire a new JDBC
 * {@link Connection} from the connection provider as early as needed, and will
 * release it as early as possible.
 * <p>
 * {@link TransactionProvider} implementations may choose to influence
 * {@link ConnectionProvider} behaviour, e.g. by acquiring connections upon
 * {@link TransactionProvider#begin(TransactionContext)} and by releasing
 * connections only upon {@link TransactionProvider#commit(TransactionContext)},
 * or {@link TransactionProvider#rollback(TransactionContext)}.
 *
 * @author Aaron Digulla
 * @author Lukas Eder
 */
public interface ConnectionProvider {

    
Acquire a connection from the connection lifecycle handler.
 This method is called by jOOQ exactly once per execution lifecycle, i.e. per ExecuteContext. Implementations may freely chose, whether subsequent calls to this method: 

return the same connection instance
return the same connection instance for the same thread
return the same connection instance for the same transaction (e.g. a
javax.transaction.UserTransaction)
return a fresh connection instance every time

 jOOQ will guarantee that every acquired connection is released through release(Connection) exactly once. 
Throws:
DataAccessException – If anything went wrong while acquiring a
            connection
Returns:
A connection for the current ExecuteContext. If
        null is returned (e.g. by NoConnectionProvider), then statements cannot be executed. Attempts to execute statements will result in a DetachedException./**
     * Acquire a connection from the connection lifecycle handler.
     * <p>
     * This method is called by jOOQ exactly once per execution lifecycle, i.e.
     * per {@link ExecuteContext}. Implementations may freely chose, whether
     * subsequent calls to this method:
     * <ul>
     * <li>return the same connection instance</li>
     * <li>return the same connection instance for the same thread</li>
     * <li>return the same connection instance for the same transaction (e.g. a
     * <code>javax.transaction.UserTransaction</code>)</li>
     * <li>return a fresh connection instance every time</li>
     * </ul>
     * <p>
     * jOOQ will guarantee that every acquired connection is released through
     * {@link #release(Connection)} exactly once.
     *
     * @return A connection for the current <code>ExecuteContext</code>. If
     *         <code>null</code> is returned (e.g. by NoConnectionProvider),
     *         then statements cannot be executed. Attempts to execute
     *         statements will result in a {@link DetachedException}.
     * @throws DataAccessException If anything went wrong while acquiring a
     *             connection
     */
    @Nullable
    Connection acquire() throws DataAccessException;

    
Release a connection to the connection lifecycle handler.

jOOQ will guarantee that every acquired connection is released exactly
once.
Params:
connection – A connection that was previously obtained from acquire(). This is never null.
Throws:
DataAccessException – If anything went wrong while releasing a
            connection/**
     * Release a connection to the connection lifecycle handler.
     * <p>
     * jOOQ will guarantee that every acquired connection is released exactly
     * once.
     *
     * @param connection A connection that was previously obtained from
     *            {@link #acquire()}. This is never <code>null</code>.
     * @throws DataAccessException If anything went wrong while releasing a
     *             connection
     */
    void release(Connection connection) throws DataAccessException;
}