001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018 /*
019 * $Id: ConnectionPool.java 468638 2006-10-28 06:52:06Z minchau $
020 */
021
022 package org.apache.xalan.lib.sql;
023
024 import java.sql.Connection;
025 import java.sql.SQLException;
026 import java.util.Properties;
027
028 /**
029 * An interface used to build wrapper classes around existing
030 * Connection Pool libraries.
031 * Title: ConnectionPool<p>
032 * @author John Gentilin
033 * @version 1.0
034 */
035 public interface ConnectionPool
036 {
037
038 /**
039 * Determine if a Connection Pool has been disabled. If a Connection pool
040 * is disabled, then it will only manage connections that are in use.
041 *
042 */
043 public boolean isEnabled( );
044
045 /**
046 * The Driver and URL are the only required parmeters.
047 * @param d
048 *
049 */
050 public void setDriver( String d );
051
052 /**
053 * @param url
054 *
055 */
056 public void setURL( String url );
057
058 /**
059 * Start downsizeing the pool, this usally happens right after the
060 * pool has been marked as Inactive and we are removing connections
061 * that are not currently inuse.
062 *
063 */
064 public void freeUnused( );
065
066
067 /**
068 * Provide an indicator to the PoolManager when the Pool can be removed
069 * from the Pool Table.
070 *
071 */
072 public boolean hasActiveConnections( );
073
074 /**
075 * The rest of the protocol parameters can eiter be passed in as
076 * just Username and Password or as a property collection. If the
077 * property collection is used, then the sperate username and password
078 * may be ignored, it is up to the wrapper implementation to handle
079 * the situation. If the connection information changes while after the
080 * pool has been established, the wrapper implementation should ignore
081 * the change and throw an error.
082 * @param p
083 *
084 */
085 public void setPassword( String p );
086
087 /**
088 * @param u
089 *
090 */
091 public void setUser( String u );
092
093
094 /**
095 * Set tne minimum number of connections that are to be maintained in the
096 * pool.
097 * @param n
098 *
099 */
100 public void setMinConnections( int n );
101
102 /**
103 * Test to see if the connection info is valid to make a real connection
104 * to the database. This method may cause the pool to be crated and filled
105 * with min connections.
106 *
107 */
108 public boolean testConnection( );
109
110 /**
111 * Retrive a database connection from the pool
112 *
113 * @throws SQLException
114 */
115 public Connection getConnection( )throws SQLException;
116
117 /**
118 * Return a connection to the pool, the connection may be closed if the
119 * pool is inactive or has exceeded the max number of free connections
120 * @param con
121 *
122 * @throws SQLException
123 */
124 public void releaseConnection( Connection con )throws SQLException;
125
126 /**
127 * Provide a mechinism to return a connection to the pool on Error.
128 * A good default behaviour is to close this connection and build
129 * a new one to replace it. Some JDBC impl's won't allow you to
130 * reuse a connection after an error occurs.
131 * @param con
132 *
133 * @throws SQLException
134 */
135 public void releaseConnectionOnError( Connection con )throws SQLException;
136
137
138 /**
139 * The Pool can be Enabled and Disabled. Disabling the pool
140 * closes all the outstanding Unused connections and any new
141 * connections will be closed upon release.
142 * @param flag Control the Connection Pool. If it is enabled
143 * then Connections will actuall be held around. If disabled
144 * then all unused connections will be instantly closed and as
145 * connections are released they are closed and removed from the pool.
146 *
147 */
148 public void setPoolEnabled( final boolean flag );
149
150 /**
151 * Used to pass in extra configuration options during the
152 * database connect phase.
153 */
154 public void setProtocol(Properties p);
155
156
157 }