1. /*

  2.  * The Apache Software License, Version 1.1

  3.  *

  4.  *

  5.  * Copyright (c) 1999 The Apache Software Foundation.  All rights

  6.  * reserved.

  7.  *

  8.  * Redistribution and use in source and binary forms, with or without

  9.  * modification, are permitted provided that the following conditions

  10.  * are met:

  11.  *

  12.  * 1. Redistributions of source code must retain the above copyright

  13.  *    notice, this list of conditions and the following disclaimer.

  14.  *

  15.  * 2. Redistributions in binary form must reproduce the above copyright

  16.  *    notice, this list of conditions and the following disclaimer in

  17.  *    the documentation and/or other materials provided with the

  18.  *    distribution.

  19.  *

  20.  * 3. The end-user documentation included with the redistribution,

  21.  *    if any, must include the following acknowledgment:

  22.  *       "This product includes software developed by the

  23.  *        Apache Software Foundation (http://www.apache.org/)."

  24.  *    Alternately, this acknowledgment may appear in the software itself,

  25.  *    if and wherever such third-party acknowledgments normally appear.

  26.  *

  27.  * 4. The names "Xalan" and "Apache Software Foundation" must

  28.  *    not be used to endorse or promote products derived from this

  29.  *    software without prior written permission. For written

  30.  *    permission, please contact apache@apache.org.

  31.  *

  32.  * 5. Products derived from this software may not be called "Apache",

  33.  *    nor may "Apache" appear in their name, without prior written

  34.  *    permission of the Apache Software Foundation.

  35.  *

  36.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED

  37.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES

  38.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

  39.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR

  40.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

  41.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

  42.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF

  43.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

  44.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

  45.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT

  46.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

  47.  * SUCH DAMAGE.

  48.  * ====================================================================

  49.  *

  50.  * This software consists of voluntary contributions made by many

  51.  * individuals on behalf of the Apache Software Foundation and was

  52.  * originally based on software copyright (c) 1999, Lotus

  53.  * Development Corporation., http://www.lotus.com.  For more

  54.  * information on the Apache Software Foundation, please see

  55.  * <http://www.apache.org/>.

  56.  */

  57. 

  58. package org.apache.xalan.lib.sql;

  59. 

  60. import java.util.Properties;

  61. import java.lang.String;

  62. import java.sql.Connection;

  63. import java.sql.SQLException;

  64. import java.sql.*;

  65. 

  66. /**

  67.  * An interface used to build wrapper classes around existing

  68.  * Connection Pool libraries.

  69.  * Title:     ConnectionPool<p>

  70.  * @author John Gentilin

  71.  * @version 1.0

  72.  */

  73. public interface ConnectionPool

  74. {

  75. 

  76.   /**

  77.    * Determine if a Connection Pool has been disabled. If a Connection pool

  78.    * is disabled, then it will only manage connections that are in use.

  79.    * @return

  80.    */

  81.   public boolean isEnabled( );

  82. 

  83.   /**

  84.    * The Driver and URL are the only required parmeters.

  85.    * @param d

  86.    * @return

  87.    */

  88.   public void setDriver( String d );

  89. 

  90.   /**

  91.    * @param url

  92.    * @return

  93.    */

  94.   public void setURL( String url );

  95. 

  96.   /**

  97.    * Start downsizeing the pool, this usally happens right after the

  98.    * pool has been marked as Inactive and we are removing connections

  99.    * that are not currently inuse.

  100.    * @return

  101.    */

  102.   public void freeUnused( );

  103. 

  104. 

  105.   /**

  106.    * Provide an indicator to the PoolManager when the Pool can be removed

  107.    * from the Pool Table.

  108.    * @return

  109.    */

  110.   public boolean hasActiveConnections( );

  111. 

  112.   /**

  113.    * The rest of the protocol parameters can eiter be passed in as

  114.    * just Username and Password or as a property collection. If the

  115.    * property collection is used, then the sperate username and password

  116.    * may be ignored, it is up to the wrapper implementation to handle

  117.    * the situation. If the connection information changes while after the

  118.    * pool has been established, the wrapper implementation should ignore

  119.    * the change and throw an error.

  120.    * @param p

  121.    * @return

  122.    */

  123.   public void setPassword( String p );

  124. 

  125.   /**

  126.    * @param u

  127.    * @return

  128.    */

  129.   public void setUser( String u );

  130. 

  131. 

  132.   /**

  133.    * Set tne minimum number of connections that are to be maintained in the

  134.    * pool.

  135.    * @param n

  136.    * @return

  137.    */

  138.   public void setMinConnections( int n );

  139. 

  140.   /**

  141.    * Test to see if the connection info is valid to make a real connection

  142.    * to the database. This method may cause the pool to be crated and filled

  143.    * with min connections.

  144.    * @return

  145.    */

  146.   public boolean testConnection( );

  147. 

  148.   /**

  149.    * Retrive a database connection from the pool

  150.    * @return

  151.    * @throws SQLException

  152.    */

  153.   public Connection getConnection( )throws SQLException;

  154. 

  155.    /**

  156.    * Return a connection to the pool, the connection may be closed if the

  157.    * pool is inactive or has exceeded the max number of free connections

  158.    * @param con

  159.    * @return

  160.    * @throws SQLException

  161.    */

  162.   public void releaseConnection( Connection con )throws SQLException;

  163. 

  164.    /**

  165.    * Provide a mechinism to return a connection to the pool on Error.

  166.    * A good default behaviour is to close this connection and build

  167.    * a new one to replace it. Some JDBC impl's won't allow you to

  168.    * reuse a connection after an error occurs.

  169.    * @param con

  170.    * @return

  171.    * @throws SQLException

  172.    */

  173.   public void releaseConnectionOnError( Connection con )throws SQLException;

  174. 

  175. 

  176.   /**

  177.    * The Pool can be Enabled and Disabled. Disabling the pool

  178.    * closes all the outstanding Unused connections and any new

  179.    * connections will be closed upon release.

  180.    * @param flag Control the Connection Pool. If it is enabled

  181.    * then Connections will actuall be held around. If disabled

  182.    * then all unused connections will be instantly closed and as

  183.    * connections are released they are closed and removed from the pool.

  184.    * @return

  185.    */

  186.   public void setPoolEnabled( final boolean flag );

  187. 

  188.   /**

  189.    * Used to pass in extra configuration options during the

  190.    * database connect phase.

  191.    */

  192.   public void setProtocol(Properties p);

  193. 

  194. 

  195. }