/*
* 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
*
* https://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} and
* {@code SharedPoolDataSource} 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>
* <pre>
* <Resource name="jdbc/bookstore" auth="Container"
* type="org.apache.tomcat.dbcp.dbcp2.datasources.PerUserPoolPoolDataSource"/>
* <ResourceParams name="jdbc/bookstore">
* <parameter>
* <name>factory</name>
* <value>org.apache.tomcat.dbcp.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>
* </pre>
* <p>
* In web.xml. Note that elements must be given in the order of the dtd
* described in the servlet specification:
* </p>
* <pre>
* <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>
* org.apache.tomcat.dbcp.dbcp2.datasources.PerUserPoolDataSource
* </res-type>
* <res-auth>
* Container
* </res-auth>
* </resource-ref>
* </pre>
* <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} that is deployed as given in the
* <a href="../cpdsadapter/package-summary.html">cpdsadapter example</a>
* </p>
* <p>
* The {@code DataSource} is now available to the application as shown
* below:
* </p>
* <pre>
* 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();
* }
* </pre>
* <p>
* The reference to the {@code DataSource} could be maintained, for
* multiple getConnection() requests. Or the {@code DataSource} can be
* looked up in different parts of the application code.
* {@code PerUserPoolDataSourceFactory} and
* {@code SharedPoolDataSourceFactory} 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} can be used within a
* simpler environment. The example below shows SharedPoolDataSource using
* DriverAdapterCPDS as the back end source, though any CPDS is applicable.
* </p>
* <pre>
* 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();
* }
* }
* </pre>
* <p>
* This class can then be used wherever a connection is needed:
* </p>
* <pre>
* Connection con = null;
* try {
* con = Pool.getConnection();
* ...
* use the connection
* ...
* } finally {
* if (con != null) {
* con.close();
* }
* }
* </pre>
*/
package org.apache.tomcat.dbcp.dbcp2.datasources;