package-info.java

/*
 * 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.
 */

/**
 * <p>
 * This package contains two DataSources: <code>PerUserPoolDataSource</code> and
 * <code>SharedPoolDataSource</code> which provide a database connection pool.
 * Below are a couple of usage examples.  One shows deployment into a JNDI system.
 * The other is a simple example initializing the pool using standard java code.
 * </p>
 *
 * <h2>JNDI</h2>
 *
 * <p>
 * Most
 * J2EE containers will provide some way of deploying resources into JNDI.  The
 * method will vary among containers, but once the resource is available via
 * JNDI, the application can access the resource in a container independent
 * manner.  The following example shows deployment into tomcat (catalina).
 * </p>
 * <p>In server.xml, the following would be added to the <Context> for your
 * webapp:
 * </p>
 *
 * <code>
 *  <Resource name="jdbc/bookstore" auth="Container"
 *             type="com.frameworkset.commons.dbcp2.datasources.PerUserPoolPoolDataSource"/>
 *   <ResourceParams name="jdbc/bookstore">
 *     <parameter>
 *       <name>factory</name>
 *       <value>com.frameworkset.commons.dbcp2.datasources.PerUserPoolDataSourceFactory</value>
 *     </parameter>
 *     <parameter>
 *       <name>dataSourceName</name><value>java:comp/env/jdbc/bookstoreCPDS</value>
 *     </parameter>
 *     <parameter>
 *       <name>defaultMaxTotal</name><value>30</value>
 *     </parameter>
 *   </ResourceParams>
 * </code>
 *
 * <p>
 * In web.xml.  Note that elements must be given in the order of the dtd
 * described in the servlet specification:
 * </p>
 *
 * <code>
 * <resource-ref>
 *   <description>
 *     Resource reference to a factory for java.sql.Connection
 *     instances that may be used for talking to a particular
 *     database that is configured in the server.xml file.
 *   </description>
 *   <res-ref-name>
 *     jdbc/bookstore
 *   </res-ref-name>
 *   <res-type>
 *     com.frameworkset.commons.dbcp2.datasources.PerUserPoolDataSource
 *   </res-type>
 *   <res-auth>
 *     Container
 *   </res-auth>
 * </resource-ref>
 * </code>
 *
 * <p>
 * Apache Tomcat deploys all objects configured similarly to above within the
 * <strong>java:comp/env</strong> namespace.  So the JNDI path given for
 * the dataSourceName parameter is valid for a
 * <code>ConnectionPoolDataSource</code> that is deployed as given in the
 * <a href="../cpdsadapter/package.html">cpdsadapter example</a>
 * </p>
 *
 * <p>
 * The <code>DataSource</code> is now available to the application as shown
 * below:
 * </p>
 *
 * <code>
 *
 *     Context ctx = new InitialContext();
 *     DataSource ds = (DataSource)
 *         ctx.lookup("java:comp/env/jdbc/bookstore");
 *     Connection con = null;
 *     try
 *     {
 *         con = ds.getConnection();
 *         ...
 *         use the connection
 *         ...
 *     }
 *     finally
 *     {
 *         if (con != null)
 *             con.close();
 *     }
 *
 * </code>
 *
 * <p>
 * The reference to the <code>DataSource</code> could be maintained, for
 * multiple getConnection() requests.  Or the <code>DataSource</code> can be
 * looked up in different parts of the application code.
 * <code>PerUserPoolDataSourceFactory</code> and
 * <code>SharedPoolDataSourceFactory</code> will maintain the state of the pool
 * between different lookups.  This behavior may be different in other
 * implementations.
 * </p>
 *
 * <h2>Without JNDI</h2>
 *
 * <p>
 * Connection pooling is useful in applications regardless of whether they run
 * in a J2EE environment and a <code>DataSource</code> can be used within a
 * simpler environment.  The example below shows SharedPoolDataSource using
 * DriverAdapterCPDS as the backend source, though any CPDS is applicable.
 * </p>
 *
 * <code>
 *
 * public class Pool
 * {
 *     private static DataSource ds;
 *
 *     static
 *     {
 *         DriverAdapterCPDS cpds = new DriverAdapterCPDS();
 *         cpds.setDriver("org.gjt.mm.mysql.Driver");
 *         cpds.setUrl("jdbc:mysql://localhost:3306/bookstore");
 *         cpds.setUser("foo");
 *         cpds.setPassword(null);
 *
 *         SharedPoolDataSource tds = new SharedPoolDataSource();
 *         tds.setConnectionPoolDataSource(cpds);
 *         tds.setMaxTotal(10);
 *         tds.setMaxWaitMillis(50);
 *
 *         ds = tds;
 *     }
 *
 *     public static getConnection()
 *     {
 *         return ds.getConnection();
 *     }
 * }
 *
 * </code>
 *
 * <p>
 * This class can then be used wherever a connection is needed:
 * </p>
 *
 * <code>
 *     Connection con = null;
 *     try
 *     {
 *         con = Pool.getConnection();
 *         ...
 *         use the connection
 *         ...
 *     }
 *     finally
 *     {
 *         if (con != null)
 *             con.close();
 *     }
 * </code>
 */
package com.frameworkset.commons.dbcp2.datasources;