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>
 *    Database Connection Pool API.
 * </p>
 *
 * <b>Overview in Dialog Form</b>
 * <p>
 *    Q: How do I use the DBCP package?
 * </p><p>
 *    A: There are two primary ways to access the DBCP pool, as a
 *    {@link java.sql.Driver Driver}, or as a {@link javax.sql.DataSource DataSource}.
 *    You'll want to create an instance of {@link org.apache.tomcat.dbcp.dbcp2.PoolingDriver} or
 *    {@link org.apache.tomcat.dbcp.dbcp2.PoolingDataSource}.  When using one of these
 *    interfaces, you can just use your JDBC objects the way you normally would.
 *    Closing a {@link java.sql.Connection} will simply return it to its pool.
 * </p>
 * <p>
 *    Q: But {@link org.apache.tomcat.dbcp.dbcp2.PoolingDriver PoolingDriver} and
 *    {@link org.apache.tomcat.dbcp.dbcp2.PoolingDataSource PoolingDataSource} both expect an
 *    {@link org.apache.tomcat.dbcp.pool2.ObjectPool ObjectPool} as an input.  Where do I
 *    get one of those?
 * </p><p>
 *    A: The {@link org.apache.tomcat.dbcp.pool2.ObjectPool ObjectPool} interface is defined
 *    in Commons Pool. You can use one of the provided implementations such as
 *    {@link org.apache.tomcat.dbcp.pool2.impl.GenericObjectPool GenericObjectPool} or
 *    {@link org.apache.tomcat.dbcp.pool2.impl.SoftReferenceObjectPool SoftReferenceObjectPool}
 *    or you can create your own.
 * </p>
 * <p>
 *    Q: Ok, I've found an {@link org.apache.tomcat.dbcp.pool2.ObjectPool ObjectPool}
 *    implementation that I think suits my connection pooling needs.  But it wants
 *    a {@link org.apache.tomcat.dbcp.pool2.PooledObjectFactory PooledObjectFactory}.
 *    What should I use for that?
 * </p><p>
 *    A: The DBCP package provides a class for this purpose. It's called
 *    {@link org.apache.tomcat.dbcp.dbcp2.PoolableConnectionFactory}.
 *    It implements the factory and lifecycle methods of
 *    {@link org.apache.tomcat.dbcp.pool2.PooledObjectFactory}
 *    for {@link java.sql.Connection}s.  But it doesn't create the actual database
 *    {@link java.sql.Connection}s itself, it uses a
 *    {@link org.apache.tomcat.dbcp.dbcp2.ConnectionFactory} for that.
 *    The {@link org.apache.tomcat.dbcp.dbcp2.PoolableConnectionFactory} will take
 *    {@link java.sql.Connection}s created by the {@link org.apache.tomcat.dbcp.dbcp2.ConnectionFactory}
 *    and wrap them with classes that implement the pooling behaviour.
 * </p><p>
 *    Several implementations of {@link org.apache.tomcat.dbcp.dbcp2.ConnectionFactory} are
 *    provided--one that uses {@link java.sql.DriverManager} to create connections
 *    ({@link org.apache.tomcat.dbcp.dbcp2.DriverManagerConnectionFactory}),
 *    one that uses a {@link java.sql.Driver} to create connections
 *    ({@link org.apache.tomcat.dbcp.dbcp2.DriverConnectionFactory}),
 *    one that uses a {@link javax.sql.DataSource} to create connections
 *    ({@link org.apache.tomcat.dbcp.dbcp2.DataSourceConnectionFactory}).
 * </p>
 * <p>
 *    Q: I think I'm starting to get it, but can you walk me though it again?
 * </p><p>
 *    A: Sure.  Let's assume you want to create a {@link javax.sql.DataSource}
 *    that pools {@link java.sql.Connection}s.  Let's also assume that
 *    those pooled {@link java.sql.Connection}s should be obtained from
 *    the {@link java.sql.DriverManager}.
 *    You'll want to create a {@link org.apache.tomcat.dbcp.dbcp2.PoolingDataSource}.
 * </p><p>
 *    The {@link org.apache.tomcat.dbcp.dbcp2.PoolingDataSource} uses an underlying
 *    {@link org.apache.tomcat.dbcp.pool2.ObjectPool} to create and store its
 *    {@link java.sql.Connection}.
 * </p><p>
 *    To create a {@link org.apache.tomcat.dbcp.pool2.ObjectPool}, you'll need
 *    a {@link org.apache.tomcat.dbcp.pool2.PooledObjectFactory} that creates
 *    the actual {@link java.sql.Connection}s.  That's what
 *    {@link org.apache.tomcat.dbcp.dbcp2.PoolableConnectionFactory} is for.
 * </p><p>
 *    To create the {@link org.apache.tomcat.dbcp.dbcp2.PoolableConnectionFactory},
 *    you'll need at least two things:</p>
 *    <ol>
 *     <li>
 * A {@link org.apache.tomcat.dbcp.dbcp2.ConnectionFactory} from which
 * the actual database {@link java.sql.Connection}s will be obtained.
 *     </li>
 *     <li>
 * An empty and factory-less {@link org.apache.tomcat.dbcp.pool2.ObjectPool}
 * in which the {@link java.sql.Connection}s will be stored.
 * <br>
 * When you pass an {@link org.apache.tomcat.dbcp.pool2.ObjectPool} into the
 * {@link org.apache.tomcat.dbcp.dbcp2.PoolableConnectionFactory}, it will
 * automatically register itself as the {@link org.apache.tomcat.dbcp.pool2.PooledObjectFactory}
 * for that pool.
 *     </li>
 *    </ol>
 * <p>
 *    In code, that might look like this:
 * </p>
 * <pre>GenericObjectPool connectionPool = new GenericObjectPool(null);
 * ConnectionFactory connectionFactory = new DriverManagerConnectionFactory("jdbc:some:connect:string", "username", "password");
 * PoolableConnectionFactory poolableConnectionFactory = new PoolableConnectionFactory(connectionFactory,connectionPool,null,null,false,true);
 * PoolingDataSource dataSource = new PoolingDataSource(connectionPool);</pre>
 * <p>
 *    To create a {@link org.apache.tomcat.dbcp.dbcp2.PoolingDriver}, we do the same thing,
 *    except that instead of creating a {@link javax.sql.DataSource} on the last line,
 *    we create a {@link org.apache.tomcat.dbcp.dbcp2.PoolingDriver}, and register the
 *    {@code connectionPool} with it.  E.g.,:</p>
 * <pre>GenericObjectPool connectionPool = new GenericObjectPool(null);
 * ConnectionFactory connectionFactory = new DriverManagerConnectionFactory("jdbc:some:connect:string", "username", "password");
 * PoolableConnectionFactory poolableConnectionFactory = new PoolableConnectionFactory(connectionFactory,connectionPool,null,null,false,true);
 * PoolingDriver driver = new PoolingDriver();
 * driver.registerPool("example",connectionPool);</pre>
 * <p>
 *    Since the {@link org.apache.tomcat.dbcp.dbcp2.PoolingDriver} registers itself
 *    with the {@link java.sql.DriverManager} when it is created, now you can just
 *    go to the {@link java.sql.DriverManager} to create your {@link java.sql.Connection}s,
 *    like you normally would:</p>
 * <pre>Connection conn = DriverManager.getConnection("jdbc:apache:commons:dbcp:example");</pre>
 */
package org.apache.tomcat.dbcp.dbcp2;