org.apache.commons.dbcp2.datasources.package-info Maven / Gradle / Ivy
Show all versions of commons-dbcp2 Show documentation
/*
* 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.
*/
/**
*
* This package contains two DataSources: PerUserPoolDataSource and
* 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.
*
*
* JNDI
*
*
* 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).
*
* In server.xml, the following would be added to the <Context> for your
* webapp:
*
*
*
* <Resource name="jdbc/bookstore" auth="Container"
* type="org.apache.commons.dbcp2.datasources.PerUserPoolPoolDataSource"/>
* <ResourceParams name="jdbc/bookstore">
* <parameter>
* <name>factory</name>
* <value>org.apache.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>
*
* In web.xml. Note that elements must be given in the order of the dtd
* described in the servlet specification:
*
*
*
* <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.commons.dbcp2.datasources.PerUserPoolDataSource
* </res-type>
* <res-auth>
* Container
* </res-auth>
* </resource-ref>
*
* Apache Tomcat deploys all objects configured similarly to above within the
* java:comp/env namespace. So the JNDI path given for
* the dataSourceName parameter is valid for a
* ConnectionPoolDataSource that is deployed as given in the
* cpdsadapter example
*
*
*
* The DataSource is now available to the application as shown
* below:
*
*
*
*
* 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();
* }
*
*
* The reference to the DataSource could be maintained, for
* multiple getConnection() requests. Or the DataSource can be
* looked up in different parts of the application code.
* PerUserPoolDataSourceFactory and
* SharedPoolDataSourceFactory will maintain the state of the pool
* between different lookups. This behavior may be different in other
* implementations.
*
*
* Without JNDI
*
*
* Connection pooling is useful in applications regardless of whether they run
* in a J2EE environment and a DataSource can be used within a
* simpler environment. The example below shows SharedPoolDataSource using
* DriverAdapterCPDS as the backend source, though any CPDS is applicable.
*
*
*
*
* 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();
* }
* }
*
*
* This class can then be used wherever a connection is needed:
*
*
*
* Connection con = null;
* try
* {
* con = Pool.getConnection();
* ...
* use the connection
* ...
* }
* finally
* {
* if (con != null)
* con.close();
* }
*