/* ======================================================================
   Parts Copyright 2006 University of Leeds, Oxford University, University of the Highlands and Islands.

   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.

====================================================================== */

package org.bodington.database;

import java.sql.Connection;

/**
 * Any class that to manage database connection pooling for Bodington 
 * should implement this interface.
 * @author buckett
 */
public interface ConnectionPool
{
    /**
     * Get a connection.
     * @param user An object to associate this connection with. This can be used
     * to enforce per user limits. It can be null, in which case no limits should be
     * enforced.
     * @return A database connection. Not null.
     * @throws ConnectionPoolException If a connection could not be returned or the
     * connection limit has been hit.
     */
    public Connection getConnection(Object user) throws ConnectionPoolException;

    /**
     * Put a database connection back in the pool.
     * @param free_con The database connection to return to the pool.
     * @throws ConnectionPoolException If something we wrong return the item to
     * the pool. Most of the time this can be ignored.
     */
    public void freeConnection(Connection free_con) throws ConnectionPoolException;
}
