code: /*
   * Licensed to the Apache Software Foundation (ASF) under one
   * or more contributor license agreements. See the NOTICE file
   * distributed with this work for additional information
   * regarding copyright ownership. The ASF licenses this file
   * to you 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.
   */
  /*
   * $Id$
   */
  
  package org.apache.xalan.lib.sql;
  
  import java.sql.Connection;
  import java.sql.SQLException;
  import java.util.Properties;
  
  /**
   * An interface used to build wrapper classes around existing
   * Connection Pool libraries.
   * Title:     ConnectionPool<p>
   * @author John Gentilin
   * @version 1.0
   */
  public interface ConnectionPool
  {
  
    /**
     * Determine if a Connection Pool has been disabled. If a Connection pool
     * is disabled, then it will only manage connections that are in use.
     *
     */
    public boolean isEnabled( );
  
    /**
     * The Driver and URL are the only required parmeters.
     * @param d
     *
     */
    public void setDriver( String d );
  
    /**
     * @param url
     *
     */
    public void setURL( String url );
  
    /**
     * Start downsizeing the pool, this usally happens right after the
     * pool has been marked as Inactive and we are removing connections
     * that are not currently inuse.
     *
     */
    public void freeUnused( );
  
  
    /**
     * Provide an indicator to the PoolManager when the Pool can be removed
     * from the Pool Table.
     *
     */
    public boolean hasActiveConnections( );
  
    /**
     * The rest of the protocol parameters can eiter be passed in as
     * just Username and Password or as a property collection. If the
     * property collection is used, then the sperate username and password
     * may be ignored, it is up to the wrapper implementation to handle
     * the situation. If the connection information changes while after the
     * pool has been established, the wrapper implementation should ignore
     * the change and throw an error.
     * @param p
     *
     */
    public void setPassword( String p );
  
    /**
     * @param u
     *
     */
    public void setUser( String u );
  
  
    /**
     * Set tne minimum number of connections that are to be maintained in the
     * pool.
     * @param n
     *
     */
    public void setMinConnections( int n );
  
    /**
     * Test to see if the connection info is valid to make a real connection
     * to the database. This method may cause the pool to be crated and filled
     * with min connections.
     *
     */
    public boolean testConnection( );
  
    /**
     * Retrive a database connection from the pool
     *
     * @throws SQLException
     */
    public Connection getConnection( )throws SQLException;
  
     /**
     * Return a connection to the pool, the connection may be closed if the
     * pool is inactive or has exceeded the max number of free connections
     * @param con
     *
     * @throws SQLException
     */
    public void releaseConnection( Connection con )throws SQLException;
  
     /**
     * Provide a mechinism to return a connection to the pool on Error.
     * A good default behaviour is to close this connection and build
     * a new one to replace it. Some JDBC impl's won't allow you to
     * reuse a connection after an error occurs.
     * @param con
     *
     * @throws SQLException
     */
    public void releaseConnectionOnError( Connection con )throws SQLException;
  
  
    /**
     * The Pool can be Enabled and Disabled. Disabling the pool
     * closes all the outstanding Unused connections and any new
     * connections will be closed upon release.
     * @param flag Control the Connection Pool. If it is enabled
     * then Connections will actuall be held around. If disabled
     * then all unused connections will be instantly closed and as
     * connections are released they are closed and removed from the pool.
     *
     */
    public void setPoolEnabled( final boolean flag );
  
    /**
     * Used to pass in extra configuration options during the
     * database connect phase.
     */
    public void setProtocol(Properties p);
  
  
  }
  