View Javadoc
   /* ====================================================================
    * License:
    *
    * Redistribution and use in source and binary forms, with or without
    * modification, are permitted provided that the following conditions
    * are met:
    *
    * 1. Redistributions of source code must retain the above copyright
    *    notice, this list of conditions and the following disclaimer.
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution,
   *    if any, must include the following acknowledgment:
   *       "This product includes software developed by
   *        Robert Half International (http://www.rhi.com/)."
   *    Alternately, this acknowledgment may appear in the software itself,
   *    if and wherever such third-party acknowledgments normally appear.
   *
   * 4. The names "Parc", "RHI", and "Robert Half International" must
   *    not be used to endorse or promote products derived from this
   *    software without prior written permission. For written
   *    permission, please contact pete.mckinstry@rhi.com.
   *
   * 5. Products derived from this software may not be called "PARC",
   *    nor may "PARC" appear in their name, without prior written
   *    permission of Robert Half International.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   */
  package com.rhi.architecture.db;
  
  import com.rhi.architecture.logging.LogUtil;
  import com.rhi.architecture.logging.Logger;
  import com.rhi.architecture.config.ConfigurationException;
  import com.rhi.architecture.resource.Resource;
  
  import java.util.*;
  
  import javax.sql.DataSource;
  
  import org.apache.commons.dbcp.ConnectionFactory;
  import org.apache.commons.dbcp.DriverManagerConnectionFactory;
  import org.apache.commons.dbcp.PoolableConnectionFactory;
  import org.apache.commons.pool.KeyedObjectPoolFactory;
  import org.apache.commons.pool.impl.GenericObjectPool;
  import org.apache.commons.pool.impl.StackKeyedObjectPoolFactory;
  
  /***
   * Factory for creating DataSources that pool database connections.
   * Encapsulates creation of DataSource so that user deals w/ DataSource
   * objects in an entirely standard way. The DataSource returned is
   * a 100% compliant DataSource that pool DB connections for the user.
   * In addition, the factory provides a static reference to the
   * DataSources so that only 1 will be created per JVM. Multiple DBs
   * can be connected to by providing different ResourceBundle filenames
   * to the getBundle() method. The filename makes the bundle unique.
   *
   * @author Pete McKinstry
   * @copyright 2002, Robert Half Int'l., Inc. All rights reserved.
   *
   * @since 1.0
   */
  public class DataSourceFactory implements Resource {
  
     /***
      * the configuration key used by the ResourceContext to look for & return 
      * the configured DataSourceFactory
      */
     public static final String KEY = "Resource.DataSourceFactory";
  
     /***
      * config key for optional sql string to be run upon new Connection checkout.
      */
     public static final String INIT_SQL_KEY = "DataSourceFactory.INIT_SQL";
  
     /***
      * the max size of the connection pool
      */
     public static final String MAX_SIZE_KEY = "DataSourceFactory.maxSize";
     private static final String DEFAULT_MAX_SIZE = "10";
     /***
      * the max wait for a connection before timing out & throwing an exception
     */
    public static final String MAX_WAIT_KEY = "DataSourceFactory.maxWait";
    private static final String DEFAULT_MAX_WAIT = "-1"; /* block forever */
    /***
     * the max idle time for a connection in the pool before it is closed. 
     */
    public static final String MAX_IDLE_KEY = "maxidle";
    private static final String DEFAULT_MAX_IDLE = "5";
    /***
     * the initial size of the connection pool. (# of connections checked out 
     * immediately)
     */
    public static final String INIT_SIZE_KEY = "initsize";
    private static final String DEFAULT_INIT_SIZE = "1";
    /***
     * max number of Statements to be stored per connection.
     */
    public static final String MAX_STMTS_KEY =
       "DataSourceFactory.maxStatements";
    private static final String DEFAULT_MAX_STMTS = "25";
 
    private static final String DATA_SOURCE_NAME_KEY = "DataSource.";
    /***
     * the default datasource name prefix.
     */
    public static final String DEFAULT_DATA_SOURCE_NAME = "default";
 
    /***
     * the config key for the DB url.
     */
    public static final String DB_URL_KEY = "db_url";
    /***
     * the config key for the jdbc driver name.
     */
    public static final String DRIVER_KEY = "driver";
    /***
     * the config key for the db user name.
     */
    public static final String USERNAME_KEY = "username";
    /***
     * the config key for the db password.
     */
    public static final String PASSWORD_KEY = "password";
 
    private static Logger log = null;
 
    // for handling thread safety
    private static Object lock = new Object();
 
    private static HashMap sources = new HashMap();
 
    private byte action = GenericObjectPool.WHEN_EXHAUSTED_BLOCK;
 
    /***
     * Default Constructor
     *
     * @since 1.0
     */
    public DataSourceFactory() {
       super();
    }
 
 
    /***
     * No initialization required.
     * @param p
     */
    public void init(Properties p) {
       try {
          log = LogUtil.getLogger();
       }
       catch (ConfigurationException e) {
          log = LogUtil.getDefaultLogger();
       }
 
       Enumeration pnames = p.propertyNames();
       while ( pnames.hasMoreElements() ) {
           String pname = ( String )pnames.nextElement();
           if ( ! pname.startsWith( DATA_SOURCE_NAME_KEY ) ) {
                continue;
           }
 
           String key = getDataSourceName( pname );
           sources.put( key, createDataSource( p, key ) );
           log.info( " created DataSource [ " + key + " ] " );
       }
    }
 
    /***
     * DataSource.web.properties as property name should give 'web'
     * as data source name
     * @param pname
     * @return String
     */
    private static String getDataSourceName( String pname ) {
       int firstDot = pname.indexOf( "." );
       int lastDot = pname.lastIndexOf( "." ); // optional
       if ( lastDot == firstDot ) {
           lastDot = pname.length();
       }
       return pname.substring( firstDot + 1, lastDot );
    }
 
    /***
     * create new datasource from provided properties file. Extracts
     * info from properties file & calls buildDataSource.
     * @param props
     * @param dsName
     * @return DataSource
     * @throws ConfigurationException
     * @since 1.1
     */
    private DataSource createDataSource( Properties props, String dsName )
       throws ConfigurationException {
       log.debug("Creating new DataSource.");
 
       int maxSize = -1;
       long maxWait = -1;
       int maxIdle = -1;
       int initSize = -1;
       int maxStatements = -1;
 
       String db_url = "";
       String driver = "";
       String username = "";
       String password = "";
       String sql = null;
 
       try {
          String maxSizeStr =
             props.getProperty(MAX_SIZE_KEY, DEFAULT_MAX_SIZE);
          maxSize = Integer.parseInt(maxSizeStr);
          String maxWaitStr =
             props.getProperty(MAX_WAIT_KEY, DEFAULT_MAX_WAIT);
          maxWait = Integer.parseInt(maxWaitStr);
          // default maxIdle to maxSize
          // having maxIdle less than maxSize could potentially
          // cause the driver to exceed max connections in database.
          maxIdle = maxSize;
          String initSizeStr =
             props.getProperty(INIT_SIZE_KEY, DEFAULT_INIT_SIZE);
          initSize = Integer.parseInt(initSizeStr);
          String maxStatementsStr =
             props.getProperty(MAX_STMTS_KEY, DEFAULT_MAX_STMTS);
          maxStatements = Integer.parseInt(maxStatementsStr);
 
          db_url = getProperty( props, dsName, DB_URL_KEY );
          driver = getProperty( props, dsName, DRIVER_KEY );
          username = getProperty( props, dsName, USERNAME_KEY );
          password = getProperty( props, dsName, PASSWORD_KEY );
          sql = getProperty( props, dsName, INIT_SQL_KEY );
 
          Class driverClass = Class.forName(driver);
          log.debug("jdbc driver loaded. name = [" + driverClass.getName() + "]");
       }
       catch (NumberFormatException nfe) {
          log.error("NumberFormatException. e = " + nfe);
          throw new ConfigurationException(nfe.toString());
       }
       catch (ClassNotFoundException cnfe) {
          log.error(cnfe.toString());
          throw new ConfigurationException(cnfe.toString());
       }
 
       DataSource dataSource =
          buildDataSource(
             maxSize,
             maxWait,
             maxIdle,
             initSize,
             maxStatements,
             db_url,
             username,
             password,
             sql);
       return dataSource;
    }
 
    /***
     * helper method for retrieving a property for the specific data source. 
     * 
     * @param p - the configuration information.
     * @param ds - the datasource name.
     * @param attribute - the attribute name which is being requested. 
     * @return String - the value of the request attribute. 
     */
    private String getProperty( Properties p, String ds, String attribute )
    {
       return p.getProperty( DATA_SOURCE_NAME_KEY + ds + "." + attribute );
    }
 
    /***
     * build data source.
     * @param maxSize
     * @param maxWait
     * @param maxIdle
     * @param initSize
     * @param maxStatements
     * @param db_url
     * @param username
     * @param password
     * @param sql
     * @return
     * @throws ConfigurationException
     */
    private DataSource buildDataSource(
       int maxSize,
       long maxWait,
       int maxIdle,
       int initSize,
       int maxStatements,
       String db_url,
       String username,
       String password,
       String sql)
       throws ConfigurationException {
       // Pool for storing Connection objects.
       GenericObjectPool pool = new GenericObjectPool(null);
       pool.setMaxActive(maxSize);
       pool.setMaxIdle(maxIdle);
       pool.setMaxWait(maxWait);
       pool.setWhenExhaustedAction(action);
       // no initSize available for GenericObjectPools.
 
       // Factory to create Connections.
       ConnectionFactory conFactory =
          new DriverManagerConnectionFactory(db_url, username, password);
       // Wrapper factory that allows execution of initialization SQL
       ConnectionFactory initFactory =
          new InitializingConnectionFactory(conFactory, sql);
 
       // Pool for prepared statements.
       KeyedObjectPoolFactory kopf =
          new StackKeyedObjectPoolFactory(null, maxStatements, 0);
 
       // PoolableConnectionFactory
       try {
          PoolableConnectionFactory poolFactory =
             new PoolableConnectionFactory(
                initFactory,
                pool,
                kopf,
                null,
          /* validation query */
          false, /* default read only */
          true /* default auto-commit */
          );
          log.debug("poolableConnectionFactory built = " + 
                  poolFactory.getClass().getName());
       }
       // I consider this really bad form for a number of reasons.
       // 1) It's catching a java.lang.Exception --- the most
       // general possible class. That leaves the developer using the
       // package will little choice but to fail absolutely when it's
       // thrown.
       // 2) The factory constructor is the method that throws
       // it. You really should not do things in your constructor
       // that require throwing an exception.
       // 3) there is no reason that it can't throw a
       // IllegalStateException, which is the only concrete exception
       // possible. But it chooses to throw a higher level class
       // limiting the visibility of the developer to the details of
       // the problem
       // Note: I can't really fix this because i would never be able
       // to use the apache project out of the box again. So i just
       // follow principle #2. Fail drastically & immediately.
       catch (Exception e) {
          log.error(
             "Configuration error. PoolableConnectionFactory"
                + "could not be created successfully.");
          throw new ConfigurationException(e.toString());
       }
 
       // Finally, the actual DataSource. (our own version w/ a get
       // method for pool retrieval)
       PoolingDataSource dataSource =
          new com.rhi.architecture.db.PoolingDataSource(pool);
 
       return dataSource;
    }
 
    /***
     * retrieve a datsource by name. 
     * @param dsName
     * @return DataSource
     */
    public DataSource getDataSource( String dsName ) {
       return ( DataSource )sources.get( dsName );
    }
 
    /***
     * Retrieve the default datasource. This is for backward compatibility, but 
     * the getDataSource(String name) version is preferred. 
     * 
     * @return DataSource.
     */
    public DataSource getDataSource() {
       return getDataSource( DEFAULT_DATA_SOURCE_NAME );
    }
 
    /***
     * Cleanup the object pool that provides the connections.
     *
     * @since 1.0
     */
    public void close() {
       try {
          synchronized (lock) {
             Collection dataSourceCollection = sources.values();
             Iterator iter = dataSourceCollection.iterator();
             while (iter.hasNext()) {
                com.rhi.architecture.db.PoolingDataSource ds =
                   (com.rhi.architecture.db.PoolingDataSource) iter
                      .next();
                ds.getPool().close();
             }
             sources.clear();
          }
       }
       catch (Exception e) {
          log.error("exception caught = " + e);
       }
    }
 
    /***
     * Sets the action to be used when the pool is exhausted. This method is
     * mostly useful for testing where you may want to fail immediately if
     * the pool is exhausted
     *
     * @param action
     */
    public void setAction(byte action) {
       this.action = action;
    }
 
 }