/*
* This software and supporting documentation were developed by
*
* Siemens Corporate Technology
* Competence Center Knowledge Management and Business Transformation
* D-81730 Munich, Germany
*
* Authors (representing a really great team ;-) )
* Stefan B. Augustin, Thorbj�rn Hansen, Manfred Langen
*
* This software is Open Source under GNU General Public License (GPL).
* Read the text of this license in LICENSE.TXT
* or look at www.opensource.org/licenses/
*
* Once more we emphasize, that:
* THIS SOFTWARE IS MADE AVAILABLE, AS IS, WITHOUT ANY WARRANTY
* REGARDING THE SOFTWARE, ITS PERFORMANCE OR
* FITNESS FOR ANY PARTICULAR USE, FREEDOM FROM ANY COMPUTER DISEASES OR
* ITS CONFORMITY TO ANY SPECIFICATION. THE ENTIRE RISK AS TO QUALITY AND
* PERFORMANCE OF THE SOFTWARE IS WITH THE USER.
*
*/
// KFM_DbConnectionBrokerPool
// ************ package ******************************************************
package KFM.DB.ConnectionPooling;
// ************ imports ******************************************************
// KFM packages
import KFM.log.*;
import KFM.Exceptions.KFMException;
// java packages
import java.util.Hashtable;
import java.sql.Connection;
import java.sql.SQLException;
import java.io.IOException;
// external packages
import com.javaexchange.dbConnectionBroker.DbConnectionBroker;
/** KFM_DbConnectionBrokerPool is a concrete DB Connection Pool implementation.
*
* <P>Please read the package documentation in
* <A HREF="file:/o:/KFM/www-docs/protected/developer/KFM/DB/ConnectionPooling/ConnectionPooling.html"
* >o:/KFM/www-docs/protected/developer/KFM/DB/ConnectionPooling/ConnectionPooling.html</A>
* . Also note the Admin Servlet in <CODE>mod.Admin</CODE>.</P>
*
* <P>KFM_DbConnectionBrokerPool is a concrete DB Connection Pool implementation. As such, it is a subclass of KFM_Pool.</P>
*
* <P>It implements the pooling by using a class of an external package (the Db Connection Broker)
* which can be obtained for free from <CODE> http://www.javaexchange.com/ </CODE>.</P>
*
* <P>For a usage example, see class comment in KFM_Pool.</P>
*
* <P>These are the pool attributes required (or optional) by this pool implementation class:
*
* <UL>
* <LI> JdbcDriver (required) </LI>
* <LI> JdbcConnectionURL (required) </LI>
* <LI> JdbcUser (required) </LI>
* <LI> JdbcPassword (required) </LI>
* <LI> MinConnections (optional, defaults to 2) </LI>
* <LI> MaxConnections (optional, defaults to 5) </LI>
* <LI> LogFile (required), the full path name is needed </LI>
* <LI> MaxConnectionTime (optional, defaults to 7 days), the time in days between connection resets </LI>
* </UL>
*
* @version 1.0 (2000-04-13), ready to use
* @see KFM_PoolManager
*/
public class KFM_DbConnectionBrokerPool extends KFM_Pool
{
/**
* The instance of the external DbConnectionBroker class that does the actual pooling.
*/
DbConnectionBroker mDbConnectionBroker;
/**
* Construct a KFM_DbConnectionBrokerPool object. A do-nothing method.
* Note: The real initialization work is performed in method init().
*/
public KFM_DbConnectionBrokerPool()
{
}
public DbConnectionBroker getDbConnectionBroker()
{
return mDbConnectionBroker;
}
/**
* Initialize the pool, i.e. give the pool a chance to set up its resources.
* The main resource for class KFM_DbConnectionBrokerPool is the DbConnectionBroker object
* that that does the actual pooling.
*
* @param poolAttributes a Hashtable with all the attributes that a specific pool implementation
* need to know about.
* @exception KFMException on any initialization problem, e.g.
* if the pool implementation class requires attributes that were not specified
* or the log file could not be opened for write access
*/
public void init(Hashtable poolAttributes) throws KFMException
{
super.init(poolAttributes);
String tJdbcDriver = (String) poolAttributes.get("JdbcDriver");
String tJdbcConnectionURL = (String) poolAttributes.get("JdbcConnectionURL");
String tJdbcUser = (String) poolAttributes.get("JdbcUser");
String tJdbcPassword = (String) poolAttributes.get("JdbcPassword");
String tLogFile = (String) poolAttributes.get("LogFile");
String tOriginator = (String) poolAttributes.get("Originator");
// Check for the presence of the required attributes
if (tJdbcDriver == null || tJdbcConnectionURL == null || tJdbcUser == null ||
tJdbcPassword == null || tLogFile == null || tOriginator == null) {
throw new KFMException("KFM_DbConnectionBrokerPool::init: Some required pool attribute missing.");
}
// Set the defaults for the optional attributes if they were not provided
int tMinConnectionsNr = 2;
String tMinConnections = (String) poolAttributes.get("MinConnections");
if (tMinConnections != null) {
try {
tMinConnectionsNr = Integer.parseInt(tMinConnections);
} catch (NumberFormatException ex) {}
}
int tMaxConnectionsNr = 5;
String tMaxConnections = (String) poolAttributes.get("MaxConnections");
if (tMaxConnections != null) {
try {
tMaxConnectionsNr = Integer.parseInt(tMaxConnections);
} catch (NumberFormatException ex) {}
}
double tMaxConnectionsTimeNr = 7.0;
String tMaxConnectionTime = (String) poolAttributes.get("MaxConnectionTime");
if (tMaxConnectionTime != null) {
try {
tMaxConnectionsTimeNr = Double.valueOf(tMaxConnectionTime).doubleValue();
} catch (NumberFormatException ex) {}
}
try {
KFMLog tLog = KFMLog.getInstance(tOriginator, tLogFile, KFMLog.ERROR_LEVEL,
// Hack but works.
KFMSystem.log.getAdminMail(), KFMSystem.log.getMailHost());
mDbConnectionBroker = new DbConnectionBroker(
tJdbcDriver,
tJdbcConnectionURL,
tJdbcUser,
tJdbcPassword,
tMinConnectionsNr,
tMaxConnectionsNr,
tLog,
tMaxConnectionsTimeNr);
} catch(IOException e1) {
throw new KFMException(e1, "KFM_DbConnectionBrokerPool::init: Failed to initialize DbConnectionBroker.");
} catch(ClassNotFoundException e2) {
throw new KFMException(e2, "KFM_DbConnectionBrokerPool::init: Failed to initialize DbConnectionBroker.");
}
}
/**
* Destroy the pool, i.e. give the pool a chance to free its resources.
*
* @see com.javaexchange.dbConnectionBroker.DbConnectionBroker#destroy(int)
*/
public void destroy()
{
if (mDbConnectionBroker == null)
// Nothing to do
return;
// Perform a multi-phase shutdown (allowing 10 seconds for this).
// This can throw a SQLException, if connections are still in use after that amount of time.
try {
mDbConnectionBroker.destroy(10000);
} catch (SQLException ex) {}
}
/** Get a valid Connection to the DB out of the pool.
*
* <P>Note that the connection is set to `autocommit�, because the
* `com.javaexchange.dbConnectionBroker.DbConnectionBroker� does not work well otherwise,
* ask ThH for full explanation.</P>
*
* @param aDescription identifying what the Connection is used for, where it was called, etc.
* @return the Connection to the DB
* @exception SQLException is thrown when no Connection was available.
* @see java.sql.Connection
* @see com.javaexchange.dbConnectionBroker.DbConnectionBroker#getConnection
*/
public Connection getConnection(String aDescription)
throws SQLException
{
if (mDbConnectionBroker == null)
// This can only happen when we use a KFM_DbConnectionBrokerPool object
// that was not at all or not properly initialized.
throw new SQLException("The Connection Pool object was not (or not properly) initialized.");
// Get the connection from the mDbConnectionBroker object.
// Attention: This can return a null object, which we map to the throwing of an SQLException.
Connection tCon = mDbConnectionBroker.getConnection(aDescription);
if (tCon == null)
throw new SQLException("The Connection Broker could not get a connection.");
return tCon;
}
/** Get a valid Connection to the DB out of the pool.
*
* @deprecated use getConnection(aDescription)
*/
public Connection getConnection()
throws SQLException
{
return getConnection(null);
}
/** Free the Connection con that was handed out before (with getConnection),
* that is, return it back to the pool.
*
* <P>Note that the connection is set to `autocommit�, because the
* `com.javaexchange.dbConnectionBroker.DbConnectionBroker� does not work well otherwise,
* ask ThH for full explanation.</P>
*
* @param aCon the connection to be freed
* @see java.sql.Connection
* @see com.javaexchange.dbConnectionBroker.DbConnectionBroker#freeConnection
*/
public void freeConnection (Connection aCon)
throws SQLException
{
if (mDbConnectionBroker == null)
// Do nothing
return;
try {
aCon.setAutoCommit(true);
} catch(SQLException e) {
KFMSystem.log.detail("KFM_DbConnectionBrokerPool::freeConnection setAutoCommit caused SQLException");
throw new SQLException(e.toString());
} finally {
mDbConnectionBroker.freeConnection(aCon);
}
}
}