| 1 |
<!-- |
| 2 |
Licensed to the Apache Software Foundation (ASF) under one or more |
| 3 |
contributor license agreements. See the NOTICE file distributed with |
| 4 |
this work for additional information regarding copyright ownership. |
| 5 |
The ASF licenses this file to You under the Apache License, Version 2.0 |
| 6 |
(the "License"); you may not use this file except in compliance with |
| 7 |
the License. You may obtain a copy of the License at |
| 8 |
|
| 9 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 10 |
|
| 11 |
Unless required by applicable law or agreed to in writing, software |
| 12 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 13 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 14 |
See the License for the specific language governing permissions and |
| 15 |
limitations under the License. |
| 16 |
--> |
| 17 |
<html> |
| 18 |
<body> |
| 19 |
<p> |
| 20 |
This package contains two DataSources: <code>PerUserPoolDataSource</code> and |
| 21 |
<code>SharedPoolDataSource</code> which provide a database connection pool. |
| 22 |
Below are a couple of usage examples. One shows deployment into a JNDI system. |
| 23 |
The other is a simple example initializing the pool using standard java code. |
| 24 |
</p> |
| 25 |
|
| 26 |
<h2>JNDI</h2> |
| 27 |
|
| 28 |
<p> |
| 29 |
Most |
| 30 |
J2EE containers will provide some way of deploying resources into JNDI. The |
| 31 |
method will vary among containers, but once the resource is available via |
| 32 |
JNDI, the application can access the resource in a container independent |
| 33 |
manner. The following example shows deployment into tomcat (catalina). |
| 34 |
</p> |
| 35 |
<p>In server.xml, the following would be added to the <Context> for your |
| 36 |
webapp: |
| 37 |
</p> |
| 38 |
|
| 39 |
<code><pre> |
| 40 |
|
| 41 |
<Resource name="jdbc/bookstore" auth="Container" |
| 42 |
type="org.apache.commons.dbcp.datasources.PerUserPoolPoolDataSource"/> |
| 43 |
<ResourceParams name="jdbc/bookstore"> |
| 44 |
<parameter> |
| 45 |
<name>factory</name> |
| 46 |
<value>org.apache.commons.dbcp.datasources.PerUserPoolDataSourceFactory</value> |
| 47 |
</parameter> |
| 48 |
<parameter> |
| 49 |
<name>dataSourceName</name><value>java:comp/env/jdbc/bookstoreCPDS</value> |
| 50 |
</parameter> |
| 51 |
<parameter> |
| 52 |
<name>defaultMaxActive</name><value>30</value> |
| 53 |
</parameter> |
| 54 |
|
| 55 |
</ResourceParams> |
| 56 |
|
| 57 |
</pre></code> |
| 58 |
|
| 59 |
<p> |
| 60 |
In web.xml. Note that elements must be given in the order of the dtd |
| 61 |
described in the servlet specification: |
| 62 |
</p> |
| 63 |
|
| 64 |
<code><pre> |
| 65 |
<resource-ref> |
| 66 |
<description> |
| 67 |
Resource reference to a factory for java.sql.Connection |
| 68 |
instances that may be used for talking to a particular |
| 69 |
database that is configured in the server.xml file. |
| 70 |
</description> |
| 71 |
<res-ref-name> |
| 72 |
jdbc/bookstore |
| 73 |
</res-ref-name> |
| 74 |
<res-type> |
| 75 |
org.apache.commons.dbcp.datasources.PerUserPoolDataSource |
| 76 |
</res-type> |
| 77 |
<res-auth> |
| 78 |
Container |
| 79 |
</res-auth> |
| 80 |
</resource-ref> |
| 81 |
</pre></code> |
| 82 |
|
| 83 |
|
| 84 |
<p> |
| 85 |
Apache Tomcat deploys all objects configured similarly to above within the |
| 86 |
<strong>java:comp/env</strong> namespace. So the JNDI path given for |
| 87 |
the dataSourceName parameter is valid for a |
| 88 |
<code>ConnectionPoolDataSource</code> that is deployed as given in the |
| 89 |
<a href="../cpdsadapter/package.html">cpdsadapter example</a> |
| 90 |
</p> |
| 91 |
|
| 92 |
<p> |
| 93 |
The <code>DataSource</code> is now available to the application as shown |
| 94 |
below: |
| 95 |
</p> |
| 96 |
|
| 97 |
<code><pre> |
| 98 |
|
| 99 |
Context ctx = new InitialContext(); |
| 100 |
DataSource ds = (DataSource) |
| 101 |
ctx.lookup("java:comp/env/jdbc/bookstore"); |
| 102 |
Connection con = null; |
| 103 |
try |
| 104 |
{ |
| 105 |
con = ds.getConnection(); |
| 106 |
... |
| 107 |
use the connection |
| 108 |
... |
| 109 |
} |
| 110 |
finally |
| 111 |
{ |
| 112 |
if (con != null) |
| 113 |
con.close(); |
| 114 |
} |
| 115 |
|
| 116 |
</pre></code> |
| 117 |
|
| 118 |
<p> |
| 119 |
The reference to the <code>DataSource</code> could be maintained, for |
| 120 |
multiple getConnection() requests. Or the <code>DataSource</code> can be |
| 121 |
looked up in different parts of the application code. |
| 122 |
<code>PerUserPoolDataSourceFactory</code> and |
| 123 |
<code>SharedPoolDataSourceFactory</code> will maintain the state of the pool |
| 124 |
between different lookups. This behavior may be different in other |
| 125 |
implementations. |
| 126 |
</p> |
| 127 |
|
| 128 |
<h2>Without JNDI</h2> |
| 129 |
|
| 130 |
<p> |
| 131 |
Connection pooling is useful in applications regardless of whether they run |
| 132 |
in a J2EE environment and a <code>DataSource</code> can be used within a |
| 133 |
simpler environment. The example below shows SharedPoolDataSource using |
| 134 |
DriverAdapterCPDS as the backend source, though any CPDS is applicable. |
| 135 |
</p> |
| 136 |
|
| 137 |
<code><pre> |
| 138 |
|
| 139 |
public class Pool |
| 140 |
{ |
| 141 |
private static DataSource ds; |
| 142 |
|
| 143 |
static |
| 144 |
{ |
| 145 |
DriverAdapterCPDS cpds = new DriverAdapterCPDS(); |
| 146 |
cpds.setDriver("org.gjt.mm.mysql.Driver"); |
| 147 |
cpds.setUrl("jdbc:mysql://localhost:3306/bookstore"); |
| 148 |
cpds.setUser("foo"); |
| 149 |
cpds.setPassword(null); |
| 150 |
|
| 151 |
SharedPoolDataSource tds = new SharedPoolDataSource(); |
| 152 |
tds.setConnectionPoolDataSource(cpds); |
| 153 |
tds.setMaxActive(10); |
| 154 |
tds.setMaxWait(50); |
| 155 |
|
| 156 |
ds = tds; |
| 157 |
} |
| 158 |
|
| 159 |
public static getConnection() |
| 160 |
{ |
| 161 |
return ds.getConnection(); |
| 162 |
} |
| 163 |
} |
| 164 |
|
| 165 |
</pre></code> |
| 166 |
|
| 167 |
<p> |
| 168 |
This class can then be used wherever a connection is needed: |
| 169 |
</p> |
| 170 |
|
| 171 |
<code><pre> |
| 172 |
Connection con = null; |
| 173 |
try |
| 174 |
{ |
| 175 |
con = Pool.getConnection(); |
| 176 |
... |
| 177 |
use the connection |
| 178 |
... |
| 179 |
} |
| 180 |
finally |
| 181 |
{ |
| 182 |
if (con != null) |
| 183 |
con.close(); |
| 184 |
} |
| 185 |
</pre></code> |
| 186 |
|
| 187 |
</body> |
| 188 |
</html> |