1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
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.
-->
<document>
<properties>
<title>Configuration</title>
<author email="dev@commons.apache.org">Commons Documentation Team</author>
</properties>
<body>
<!--
<section name="Introduction">
<p>TODO: add section about tomcat configuration and avoiding the resource leak when reloading tomcat webapps.</p>
</section>
-->
<!--
<section name="Dynamic Properties">
maxActive
maxIdle
minIdle
maxWait
testOnBorrow
testOnReturn
timeBetweenEvictionRunsMillis
numTestsPerEvictionRun
minEvictableIdleTimeMillis
testWhileIdle
</section>
-->
<section name="Parameters">
<table>
<hr><th>Parameter</th><th>Description</th></hr>
<tr>
<td>username</td>
<td>The connection username to be passed to our JDBC driver to establish a connection.</td>
</tr>
<tr>
<td>password</td>
<td>The connection password to be passed to our JDBC driver to establish a connection.</td>
</tr>
<tr>
<td>url</td>
<td>The connection URL to be passed to our JDBC driver to establish a connection.</td>
</tr>
<tr>
<td>driverClassName</td>
<td>The fully qualified Java class name of the JDBC driver to be used.</td>
</tr>
<tr>
<td>connectionProperties</td>
<td>The connection properties that will be sent to our JDBC driver when establishing new connections.
<br/>Format of the string must be [propertyName=property;]*
<br/><strong>NOTE</strong> - The "user" and "password" properties will be passed explicitly,
so they do not need to be included here.
</td>
</tr>
</table>
<table>
<hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
<tr>
<td>defaultAutoCommit</td>
<td>true</td>
<td>The default auto-commit state of connections created by this pool.</td>
</tr>
<tr>
<td>defaultReadOnly</td>
<td>driver default</td>
<td>The default read-only state of connections created by this pool.
If not set then the setReadOnly method will not be called.
(Some drivers don't support read only mode, ex: Informix)
</td>
</tr>
<tr>
<td>defaultTransactionIsolation</td>
<td>driver default</td>
<td>The default TransactionIsolation state of connections created by this pool.
One of the following: (see
<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/Connection.html#field_summary">javadoc</a>)
<ul>
<li>NONE</li>
<li>READ_COMMITTED</li>
<li>READ_UNCOMMITTED</li>
<li>REPEATABLE_READ</li>
<li>SERIALIZABLE</li>
</ul>
</td>
</tr>
<tr>
<td>defaultCatalog</td>
<td></td>
<td>The default catalog of connections created by this pool.</td>
</tr>
</table>
<table>
<hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
<tr>
<td>initialSize</td>
<td>0</td>
<td>
The initial number of connections that are created when the pool
is started.
<br/>Since: 1.2
</td>
</tr>
<tr>
<td>maxActive</td>
<td>8</td>
<td>
The maximum number of active connections that can be allocated from
this pool at the same time, or negative for no limit.
</td>
</tr>
<tr>
<td>maxIdle</td>
<td>8</td>
<td>
The maximum number of connections that can remain idle in the
pool, without extra ones being released, or negative for no limit.
</td>
</tr>
<tr>
<td>minIdle</td>
<td>0</td>
<td>
The minimum number of connections that can remain idle in the
pool, without extra ones being created, or zero to create none.
</td>
</tr>
<tr>
<td>maxWait</td>
<td>indefinitely</td>
<td>
The maximum number of milliseconds that the pool will wait (when there
are no available connections) for a connection to be returned before
throwing an exception, or -1 to wait indefinitely.
</td>
</tr>
</table>
<p>
<img src="images/icon_warning_sml.gif"/>
<strong>NOTE</strong>: If maxIdle is set too low on heavily loaded systems it is
possible you will see connections being closed and almost immediately new
connections being opened. This is a result of the active threads momentarily
closing connections faster than they are opening them, causing the number of
idle connections to rise above maxIdle. The best value for maxIdle for heavily
loaded system will vary but the default is a good starting point.
</p>
<table>
<hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
<tr>
<td>validationQuery</td>
<td></td>
<td>
The SQL query that will be used to validate connections from this pool
before returning them to the caller. If specified, this query
<strong>MUST</strong> be an SQL SELECT statement that returns at least
one row.
</td>
</tr>
<tr>
<td>testOnBorrow</td>
<td>true</td>
<td>
The indication of whether objects will be validated before being
borrowed from the pool. If the object fails to validate, it will be
dropped from the pool, and we will attempt to borrow another.<br/>
<strong>NOTE</strong> - for a <code>true</code> value to have any effect,
the <code>validationQuery</code> parameter must be set to a non-null
string.
</td>
</tr>
<tr>
<td>testOnReturn</td>
<td>false</td>
<td>
The indication of whether objects will be validated before being
returned to the pool. <br/> <strong>NOTE</strong> - for a
<code>true</code> value to have any effect, the
<code>validationQuery</code> parameter must be set to a non-null string.
</td>
</tr>
<tr>
<td>testWhileIdle</td>
<td>false</td>
<td>
The indication of whether objects will be validated by the idle object
evictor (if any). If an object fails to validate, it will be dropped
from the pool. <br/> <strong>NOTE</strong> - for a <code>true</code>
value to have any effect, the <code>validationQuery</code> parameter
must be set to a non-null string.
</td>
</tr>
<tr>
<td>timeBetweenEvictionRunsMillis</td>
<td>-1</td>
<td>
The number of milliseconds to sleep between runs of the idle object
evictor thread. When non-positive, no idle object evictor thread will
be run.
</td>
</tr>
<tr>
<td>numTestsPerEvictionRun</td>
<td>3</td>
<td>
The number of objects to examine during each run of the idle object
evictor thread (if any).
</td>
</tr>
<tr>
<td>minEvictableIdleTimeMillis</td>
<td>1000 * 60 * 30</td>
<td>
The minimum amount of time an object may sit idle in the pool before it
is eligable for eviction by the idle object evictor (if any).
</td>
</tr>
<tr>
<td>connectionInitSqls</td>
<td>null</td>
<td>
A Collection of SQL statements that will be used to initialize physical
connections when they are first created. These statements are executed
only once - when the configured connection factory creates the connection.
</td>
</tr>
</table>
<table>
<hr><th>Parameter</th><th>Default</th><th>Description</th></hr><tr>
<td>poolPreparedStatements</td>
<td>false</td>
<td>Enable prepared statement pooling for this pool.</td>
</tr>
<tr>
<td>maxOpenPreparedStatements</td>
<td>unlimited</td>
<td>
The maximum number of open statements that can be allocated from
the statement pool at the same time, or zero for no limit.
</td>
</tr>
</table>
<p>
<img src="images/icon_info_sml.gif"/>
This component has also the ability to pool PreparedStatements.
When enabled a statement pool will be created for each Connection
and PreparedStatements created by one of the following methods will be pooled:
<ul>
<li>public PreparedStatement prepareStatement(String sql)</li>
<li>public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency)</li>
</ul>
</p>
<p>
<img src="images/icon_warning_sml.gif"/>
<strong>NOTE</strong> - Make sure your connection has some resources left for the other statements.
Pooling PreparedStatements may keep their cursors open in the database, causing a connection to run out of cursors,
especially if maxOpenPreparedStatements is left at the default (unlimited) and an application opens a large number
of different PreparedStatements per connection. To avoid this problem, maxOpenPreparedStatements should be set to a
value less than the maximum number of cursors that can be open on a Connection.
</p>
<table>
<hr><th>Parameter</th><th>Default</th><th>Description</th></hr><tr>
<td>accessToUnderlyingConnectionAllowed</td>
<td>false</td>
<td>Controls if the PoolGuard allows access to the underlying connection.</td>
</tr>
</table>
<p>When allowed you can access the underlying connection using the following construct:</p>
<source>
Connection conn = ds.getConnection();
Connection dconn = ((DelegatingConnection) conn).getInnermostDelegate();
...
conn.close()
</source>
<p>
<img src="images/icon_info_sml.gif"/>
Default is false, it is a potential dangerous operation and misbehaving programs can do harmfull things. (closing the underlying or continue using it when the guarded connection is already closed)
Be carefull and only use when you need direct access to driver specific extentions.
</p>
<p>
<img src="images/icon_warning_sml.gif"/>
<b>NOTE:</b> Do not close the underlying connection, only the original one.
</p>
<table>
<hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
<tr>
<td>removeAbandoned</td>
<td>false</td>
<td>
Flag to remove abandoned connections if they exceed the
removeAbandonedTimout.<br/>
If set to true a connection is considered abandoned and eligible
for removal if it has been idle longer than the removeAbandonedTimeout.
Setting this to true can recover db connections from poorly written
applications which fail to close a connection.
</td>
</tr>
<tr>
<td>removeAbandonedTimeout</td>
<td>300</td>
<td>Timeout in seconds before an abandoned connection can be removed.</td>
</tr>
<tr>
<td>logAbandoned</td>
<td>false</td>
<td>
Flag to log stack traces for application code which abandoned
a Statement or Connection.<br/>
Logging of abandoned Statements and Connections adds overhead
for every Connection open or new Statement because a stack
trace has to be generated.
</td>
</tr>
</table>
<p>
<img src="images/icon_info_sml.gif"/>
If you have enabled "removeAbandoned" then it is possible that a connection is reclaimed by the pool because it is considered to be abandoned.
This mechanism is triggered when (getNumIdle() < 2) and (getNumActive() > getMaxActive() - 3)
</p>
<p>
<img src="images/icon_info_sml.gif"/>
For example maxActive=20 and 18 active connections and 1 idle connection would trigger the "removeAbandoned".
But only the active connections that aren't used for more then "removeAbandonedTimeout" seconds are removed,
default (300 sec). Traversing a resultset doesn't count as being used.
</p>
</section>
</body>
</document>
|
