Debian Codegraph @

src/java/org/apache/commons/dbcp/datasources/package.html

raw
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 &lt;Context&gt; for your
36 webapp:
37 </p>
38
39 <code><pre>
40
41 &lt;Resource name="jdbc/bookstore" auth="Container"
42 type="org.apache.commons.dbcp.datasources.PerUserPoolPoolDataSource"/&gt;
43 &lt;ResourceParams name="jdbc/bookstore"&gt;
44 &lt;parameter&gt;
45 &lt;name&gt;factory&lt;/name&gt;
46 &lt;value&gt;org.apache.commons.dbcp.datasources.PerUserPoolDataSourceFactory&lt;/value&gt;
47 &lt;/parameter&gt;
48 &lt;parameter&gt;
49 &lt;name&gt;dataSourceName&lt;/name&gt;&lt;value&gt;java:comp/env/jdbc/bookstoreCPDS&lt;/value&gt;
50 &lt;/parameter&gt;
51 &lt;parameter&gt;
52 &lt;name&gt;defaultMaxActive&lt;/name&gt;&lt;value&gt;30&lt;/value&gt;
53 &lt;/parameter&gt;
54
55 &lt;/ResourceParams&gt;
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 &lt;resource-ref&gt;
66 &lt;description&gt;
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 &lt;/description&gt;
71 &lt;res-ref-name&gt;
72 jdbc/bookstore
73 &lt;/res-ref-name&gt;
74 &lt;res-type&gt;
75 org.apache.commons.dbcp.datasources.PerUserPoolDataSource
76 &lt;/res-type&gt;
77 &lt;res-auth&gt;
78 Container
79 &lt;/res-auth&gt;
80 &lt;/resource-ref&gt;
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>