-
Notifications
You must be signed in to change notification settings - Fork 335
/
index.html
3442 lines (3359 loc) · 182 KB
/
index.html
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
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html>
<head>
<title>c3p0-v@c3p0.version@ - JDBC3 Connection and Statement Pooling - Documentation</title>
<script type="text/javascript">
function toggleDisplay( id1, id2 )
{
if (document.getElementById( id1 ).style.display == 'block')
{
document.getElementById( id1 ).style.display = 'none';
document.getElementById( id2 ).style.display = 'block';
}
else
{
document.getElementById( id2 ).style.display = 'none';
document.getElementById( id1 ).style.display = 'block';
}
return false;
}
</script>
<style type="text/css">
a.cfg_param {
font-family: monospace;
}
a.small {
font-size: smaller;
}
body {
font-family: optima, helvetica, arial, sans-serif;
line-height: 1.25;
}
dl.properties {
padding: 0em 3em 0em 3em;
}
dl.properties dd {
padding-bottom: 0.5em;
font-size: smaller;
}
dl.properties dt {
padding-top: 1em;
border-top-width: 1;
border-top-style: dashed;
border-top-color: black;
font-family: monospace;
color: red;
}
dl.properties div.default {
padding-top: 0.5em;
text-decoration: underline;
padding-bottom: 0.5em;
}
dl.properties div.per-user {
text-align: center;
margin-top: 0.5em;
font-weight: bold;
border-width: 1;
border-style: solid;
border-color: black;
background-color: #FFCCCC;
}
dl.log_properties {
border-width: 2;
border-style: solid;
border-color: black;
padding: 0.5em 0.5em 0.5em 0.5em;
font-size: smaller;
background-color: #DDDDDD;
}
dl.log_properties dd {
padding-top: 0.5em;
padding-bottom: 0.5em;
/* font-size: smaller; */
}
dl.log_properties dt {
padding-top: 1em;
font-weight: bold;
font-family: monospace;
color: black;
}
div.boxed {
border-width: 1;
border-style: solid;
border-color: black;
padding: 1em;
font-size: smaller;
background-color: #CCFFCC;
margin-top: 1em;
margin-bottom: 1em;
}
div.boxed h4 {
margin-top: 0;
padding-top: 0;
font-weight: bold;
text-decoration: underline;
}
div.deprecated {
display: none;
padding-top: 0;
padding-left: 1em;
padding-right: 1em;
padding-bottom: 1em;
background-color: #FFAAAA;
border: 2px solid red;
}
div.deprecated h5 {
font-weight: bold;
color: #CC0000;
margin-top: 0em;
padding-top: 1em;
}
div.example {
white-space: pre;
font-family: monospace;
font-size: smaller;
background-color: #CCCCFF;
margin: 3em 3em 3em 3em;
padding: 1em 0em 1em 2em;
border-top-width: 2;
border-top-color: black;
border-top-style: solid;
border-bottom-width: 2;
border-bottom-color: black;
border-bottom-style: solid;
/*
doesn't show under Firefox
border-top: 2 solid black;
border-bottom: 2 solid black;
*/
}
div.example_properties {
white-space: pre;
font-family: monospace;
font-size: smaller;
background-color: #CCCCFF;
margin: 3em 3em 3em 3em;
padding: 1em 0em 1em 0em;
border-top-width: 2;
border-top-color: black;
border-top-style: solid;
border-bottom-width: 2;
border-bottom-color: black;
border-bottom-style: solid;
}
div.example_properties strong {
font-weight: bold;
color: red;
}
div.hibernate_props {
text-align: center;
}
div.indented {
margin-left: 4em;
}
div.other_properties_desc {
padding-top: 2px;
padding-left: 2em;
padding-right: 2em;
padding-bottom: 5px;
margin-bottom: 2em;
text-align: justify;
background: #ddf;
}
div.sectiontext {
margin-left: 2em;
margin-right: 2em;
}
div.subtitle {
font-size: 12pt;
background-color: #FFFFFF;
}
div.top_boilerplate {
margin-left: 8em;
margin-right: 8em;
}
h1 {
text-align: center;
background-color: #FFCCAA;
}
h2 {
background-color: #FFFFAA;
margin-top: 2em;
border-bottom-width: 2;
border-bottom-color: black;
border-bottom-style: solid;
}
h3 {
margin-right: -2em;
}
img {
border: 0;
}
ol.contents ol {
list-style-type: lower-roman;
}
ol.contents ol li {
font-size: smaller;
}
ol.contents > ul.box {
list-style: circle;
}
ol.precedence {
width: 75%;
border-width: 2;
border-color: black;
border-style: solid;
padding-left: 3em;
padding-top: 1em;
padding-bottom: 1em;
padding-right: 1em;
text-align: left;
}
ol.precedence > li {
font-size: smaller;
margin-top: 0.5em;
}
span.deprecated {
color: red;
font-weight: bold;
}
span.hibparam_comment {
font-family: optima, helvetica, arial, sans-serif;
font-style: italic;
text-decoration: underline;
}
span.toplink {
font-size: 12;
font-style: plain;
float: right;
}
table.beanPropSummaryTable {
width: 100%;
border: none;
}
table.beanPropSummaryTable tr td {
width: 33%;
border: none;
background: #ddf;
font-family: monospace;
line-height: 1.5;
padding: 8px;
}
table.beanPropSummaryTable tr td a {
color: black;
}
table.hibernate_props {
border-width: 2;
border-color: black;
border-style: solid;
font-size: smaller;
margin-left: auto;
margin-right: auto;
}
table.hibernate_props th {
background-color: #FFCCAA;
}
table.hibernate_props td {
font-family: monospace;
}
tt {
}
ul.other_props_list {
list-style: none;
font-family: monospace;
color: #A00;
}
ul.pointerlist {
list-style: square;
}
</style>
</head>
<body>
<h1>
<div>c3p0 - JDBC3 Connection and Statement Pooling</div>
<div class="subtitle">version @c3p0.version@</div>
</h1>
<div class="top_boilerplate">
<p>by Steve Waldman <<a href="mailto:swaldman@mchange.com">swaldman@mchange.com</a>></p>
<p>© @c3p0.copyright.year@ Machinery For Change, Inc.</p>
<p><i>
This software is made available for use, modification, and redistribution,
under the terms of the
<a href="http://www.gnu.org/licenses/lgpl-2.1.html">Lesser GNU Public License, v.2.1 (LGPL)</a> or
the <a href="http://www.eclipse.org/legal/epl-v10.html">Eclipse Public License, v.1.0 (EPL)</a>,
at your option. You should have received copies of both licenses with this distribution.
</i></p>
<ul class="pointerlist">
<li>API docs for c3p0 are <a href="apidocs/index.html">here</a>.</li>
<li>Looking for the definition of <a href="#configuration_properties">configuration properties</a>?</li>
<li>Looking for advice in <a href="#hibernate-specific">using c3p0 with hibernate</a>?</li>
</ul>
<ul class="pointerlist">
<li>Download the latest version from <a href="http://sourceforge.net/projects/c3p0/">c3p0's site on SourceForge</a></li>
<li>Follow or fork <a href="https://github.com/swaldman/c3p0">c3p0 on GitHub</a>.</li>
<li>Follow <a href="https://twitter.com/c3p0_jdbc">@c3p0_jdbc</a> on Twitter.</li>
<li>This may not be the most recent version of c3p0. See the current <a href="https://github.com/swaldman/c3p0/blob/master/src/dist-static/CHANGELOG">CHANGELOG</a>.</li>
</ul>
<p><b>Note:</b> Coordinates of this version on the Maven central repository: <tt>[groupId: <b>com.mchange</b>, artifactId: <b>c3p0</b>, version: <b>@c3p0.version@]</b></tt></p>
</div>
<hr/>
<h2><a name="contents">Contents</a></h2>
<ol class="contents">
<li><a href="#contents">Contents</a></li>
<li><a href="#quickstart">Quickstart</a></li>
<li><a href="#what_is">What is c3p0?</a></li>
<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#installation">Installation</a></li>
<li>
<a href="#using_c3p0">Using c3p0</a>
<ol class="contents">
<li><a href="#using_combopooleddatasource">Using ComboPooledDataSource</a></li>
<li><a href="#using_datasources_factory">Using the DataSouces factory class</a></li>
<ul class="box">
<li><a href="#forceOverrideBox">Box: Overriding authentication information (from non-c3p0 DataSources)</a></li>
</ul>
<li><a href="#querying">Querying Pool Status</a></li>
<ul class="box">
<li><a href="#using_c3p0_registry_box">Box: Using C3P0Registry to find a reference to a DataSource</a></li>
</ul>
<li><a href="#cleaning">Cleaning Up Pool Resources</a></li>
<li><a href="#build_your_own">Advanced: Building Your Own PoolBackedDataSource</a></li>
<li><a href="#raw_connection_ops">Advanced: Raw Connection and Statement Operations</a></li>
</ol>
</li>
<li>
<a href="#configuration">Configuration</a>
<ol class="contents">
<li><a href="#configuration_introduction">Introduction</a></li>
<li><a href="#basic_pool_configuration">Basic Pool Configuration</a></li>
<li><a href="#managing_pool_size">Managing Pool Size and Connection Age</a></li>
<li><a href="#configuring_connection_testing">Configuring Connection Testing</a></li>
<ul class="box">
<li><a href="#simple_advice_on_connection_testing">Box: Simple advice on Connection testing </a></li>
</ul>
<li><a href="#configuring_statement_pooling">Configuring Statement Pooling</a></li>
<li><a href="#configuring_recovery">Configuring Recovery From Database Outages</a></li>
<li><a href="#connection_customizers">Managing Connection Lifecycles with Connection Customizers</a></li>
<li><a href="#configuring_unresolved">Configuring Unresolved Transaction Handling</a></li>
<li><a href="#configuring_to_debug_and_workaround_broken_clients">Configuring To Debug and Workaround Broken Client Applications</a></li>
<li><a href="#configuring_to_avoid_memory_leaks_on_redeploy">Configuring To Avoid Memory Leaks On Redeploy</a></li>
<li><a href="#other_ds_configuration">Other DataSource Configuration</a></li>
<li><a href="#jmx_configuration_and_management">Configuring and Managing c3p0 via JMX</a></li>
<li><a href="#configuring_logging">Configuring Logging</a></li>
<li><a href="#named_configurations">Named configurations</a></li>
<li><a href="#per-user_configurations">Per-user configurations</a></li>
<li><a href="#user_extensions_to_configurations">User extensions to configuration</a></li>
<li><a href="#mixing_named_per-user_extensions">Mixing named, per-user, and user-defined configuration extensions</a></li>
</ol>
</li>
<li><a href="#performance">Performance</a></li>
<li><a href="#known_shortcomings">Known shortcomings</a></li>
<li><a href="#feedback_and_support">Feedback and support</a></li>
<li><a href="#configuration_properties">Appendix A: Configuration Properties</a></li>
<li><a href="#configuration_files">Appendix B: Configuation Files, etc.</a></li>
<ol class="contents">
<li><a href="#c3p0_properties">Overriding c3p0 defaults with a c3p0.properties file</a></li>
<li><a href="#c3p0_conf">Overriding c3p0 defaults with "HOCON" (typesafe-config) configuration files</a></li>
<li><a href="#system_properties">Overriding c3p0 defaults with System properties</a></li>
<li><a href="#c3p0-config.xml">Named and Per-User configuration: Overriding c3p0 defaults via c3p0-config.xml</a></li>
<li><a href="#configuration_precedence">Precedence of Configuration Settings</a></li>
</ol>
<li><a href="#hibernate-specific">Appendix C: Hibernate-specific notes</a></li>
<li><a href="#tomcat-specific">Appendix D: Configuring c3p0 pooled DataSources for Apache Tomcat</a></li>
<li><a href="#jboss-specific">Appendix E: JBoss-specific notes</a></li>
<li><a href="#oracle-specific">Appendix F: Oracle-specific API: createTemporaryBLOB() and createTemporaryCLOB()</a></li>
</ol>
(See also the API Documentation <a href="apidocs/index.html">here</a>)
<hr/>
<h2><a name="quickstart">Quickstart</a><span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span></h2>
<div class="sectiontext">
<p>
c3p0 was designed to be butt-simple to use. Just put
the files <tt>lib/c3p0-@c3p0.version@.jar</tt> and <tt>lib/mchange-commons-java-@mchange-commons-java.version@.jar</tt> in your application's
effective <tt>CLASSPATH</tt>, then make a DataSource like this:
</p>
<div class="example">
import com.mchange.v2.c3p0.*;
...
ComboPooledDataSource cpds = new ComboPooledDataSource();
cpds.setDriverClass( "org.postgresql.Driver" ); //loads the jdbc driver
cpds.setJdbcUrl( "jdbc:postgresql://localhost/testdb" );
cpds.setUser("dbuser");
cpds.setPassword("dbpassword");
</div>
<p>
<b>[Optional]</b> If you want to turn on PreparedStatement pooling, you must also set <tt>maxStatements</tt>
and/or <tt>maxStatementsPerConnection</tt> (both default to 0):
</p>
<div class="example">
cpds.setMaxStatements( 180 );
</div>
<p>
Do whatever you want with your DataSource, which will be backed
by a Connection pool set up with default parameters. You
can bind the DataSource to a JNDI name service, or use it
directly, as you prefer.
</p>
<p>
When you are done, you can clean up the DataSource you've created
like this:
</p>
<div class="example">
cpds.close();
</div>
<p>
That's it! The rest is detail.
</p>
</div>
<h2><a name="basics">What is c3p0?</a><span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span></h2>
<div class="sectiontext">
<p>
c3p0 is an easy-to-use library for making traditional JDBC drivers
"enterprise-ready" by augmenting them with functionality defined by
the jdbc3 spec and the optional extensions to jdbc2. As of version 0.9.5,
c3p0 fully supports the jdbc4 spec.
</p>
<p>
In particular,
c3p0 provides several useful services:
</p>
<ul>
<li>
A class whichs adapt traditional DriverManager-based JDBC
drivers to the newer <tt>javax.sql.DataSource</tt> scheme for acquiring
database Connections.
</li>
<li>
Transparent pooling of Connection and PreparedStatements
behind DataSources which can "wrap" around traditional
drivers or arbitrary unpooled DataSources.
</li>
</ul>
<p>
The library tries hard to get the details right:
</p>
<ul>
<li>
c3p0 DataSources are both <tt>Referenceable</tt> and <tt>Serializable</tt>, and are thus
suitable for binding to a wide-variety of JNDI-based naming services.
</li>
<li>
Statement and ResultSets are carefully cleaned up when pooled
Connections and Statements are checked in, to prevent resource-
exhaustion when clients use the lazy but common resource-management
strategy of only cleaning up their Connections. (Don't be naughty.)
</li>
<li>
The library adopts the approach
defined by the JDBC 2 and 3 specification (even where these
conflict with the library author's preferences). DataSources
are written in the JavaBean style, offering all the required and
most of the optional properties (as well as some non-standard ones),
and no-arg constructors. All JDBC-defined internal interfaces are
implemented (ConnectionPoolDataSource, PooledConnection,
ConnectionEvent-generating Connections, etc.)
You can mix c3p0 classes with compliant third-party implementations
(although not all c3p0 features will work with external implementations of <tt>ConnectionPoolDataSource</tt>).
</li>
</ul>
<p>
c3p0 hopes to provide DataSource implementations more than suitable for
use by high-volume "J2EE enterprise applications". Please provide feedback, bug-fixes, etc!
</p>
</div>
<h2><a name="prerequisites">Prerequisites</a><span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span></h2>
<div class="sectiontext">
<p>
c3p0-@c3p0.version@ requires a level 1.6.x or above Java Runtime Environment.
</p>
</div>
<h2><a name="installation">Installation</a><span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span></h2>
<div class="sectiontext">
<p>
Place the files <tt>lib/c3p0-@c3p0.version@.jar</tt> and
<tt>lib/mchange-commons-java-@mchange-commons-java.version@.jar</tt>
somewhere in your CLASSPATH (or any other place where your application's
classloader will find it). That's it!
</p>
</div>
<h2><a name="using_c3p0">Using c3p0</a><span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span></h2>
<div class="sectiontext">
<p>
From a users' perspective, c3p0 simply provides standard jdbc DataSource
objects. When creating these DataSources, users can control pooling-related,
naming-related, and other properties. (See <a href="#configuration_properties">Appendix A</a> for a comprehensive
list of configuration properties.) All pooling is entirely
transparent to users once a DataSource has been created.
</p>
<p>
There are three ways of acquiring c3p0 pool-backed DataSources: 1) directly instantiate and configure a
<a href="apidocs/com/mchange/v2/c3p0/ComboPooledDataSource.html"><tt>ComboPooledDataSource</tt></a> bean;
2) use the <a href="apidocs/com/mchange/v2/c3p0/DataSources.html"><tt>DataSources</tt> factory class</a>; or 3) "build your own" pool-backed
DataSource by directly instantiating <tt>PoolBackedDataSource</tt> and setting its <tt>ConectionPoolDataSource</tt>. Most
users will probably find instantiating <a href="apidocs/com/mchange/v2/c3p0/ComboPooledDataSource.html"><tt>ComboPooledDataSource</tt></a>
to be the most convenient approach. Once instantiated,
c3p0 DataSources can be bound to nearly any JNDI-compliant name service.
</p>
<p>
Regardless of how you create your DataSource, c3p0 will use defaults for any configuration parameters that
you do not specify programmatically. c3p0 has built-in, hard-coded defaults, but you can override these with
configuration files, placed as top-level resources in the same <tt>CLASSPATH</tt> (or ClassLoader)
that loads c3p0's jar file.
</p>
<p>
c3p0 DataSources may be configured via simple <tt>java.util.Properties</tt>
files called <tt>c3p0.properties</tt>, via more advanced
<a href="https://github.com/typesafehub/config/blob/master/HOCON.md">HOCON configuration files</a>
(e.g. <tt>application.conf</tt>, <tt>application.json</tt>), or in an XML format,
<tt>c3p0-config.xml</tt>.
See <a href="#configuration">Configuration</a> below.
</p>
<h3>
<a name="using_combopooleddatasource">Instantiating and Configuring a ComboPooledDataSource</a>
<span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span>
</h3>
<p>
Perhaps the most straightforward way to create a c3p0 pooling DataSource is to instantiate an instance of
<a href="apidocs/com/mchange/v2/c3p0/ComboPooledDataSource.html"><tt>com.mchange.v2.c3p0.ComboPooledDataSource</tt></a>.
This is a JavaBean-style class with a public, no-arg constructor,
but before you use the DataSource, you'll have to be sure to set at least the property <tt>jdbcUrl</tt>. You may also
want to set <tt>user</tt> and <tt>password</tt>, and, if you use an old-style JDBC driver that you will not
externally preload, you should set the <tt>driverClass</tt>.
</p>
<div class="example">
ComboPooledDataSource cpds = new ComboPooledDataSource();
cpds.setDriverClass( "org.postgresql.Driver" ); //loads the jdbc driver
cpds.setJdbcUrl( "jdbc:postgresql://localhost/testdb" );
cpds.setUser("swaldman");
cpds.setPassword("test-password");
// the settings below are optional -- c3p0 can work with defaults
cpds.setMinPoolSize(5);
cpds.setAcquireIncrement(5);
cpds.setMaxPoolSize(20);
// The DataSource cpds is now a fully configured and usable pooled DataSource
...
</div>
<p>
The default values of any c3p0 DataSource property are determined by configuration you supply, or
else revert to hard-coded defaults [see <a href="#configuration_properties">configuration properties</a>].
c3p0 supports <a href="#named_configurations">named configurations</a> so that you can
configure multiple DataSources.
If you wish to use a named configuration, construct your
<a href="apidocs/com/mchange/v2/c3p0/ComboPooledDataSource.html"><tt>com.mchange.v2.c3p0.ComboPooledDataSource</tt></a>
with the configuration name as a constructor agument:
</p>
<div class="example">
ComboPooledDataSource cpds = new ComboPooledDataSource("intergalactoApp");
</div>
<p>
Of course, you can still override any configuration properties programmatically, as above.
</p>
<h3>
<a name="using_datasources_factory">Using the DataSources factory class</a>
<span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span>
</h3>
<p>
Alternatively, you can use the static factory class
<a href="apidocs/com/mchange/v2/c3p0/DataSources.html"><tt>com.mchange.v2.c3p0.DataSources</tt></a> to build unpooled DataSources
from traditional JDBC drivers, and to build pooled DataSources from unpooled DataSources:
</p>
<div class="example">
DataSource ds_unpooled = DataSources.unpooledDataSource("jdbc:postgresql://localhost/testdb",
"swaldman",
"test-password");
DataSource ds_pooled = DataSources.pooledDataSource( ds_unpooled );
// The DataSource ds_pooled is now a fully configured and usable pooled DataSource.
// The DataSource is using a default pool configuration, and Postgres' JDBC driver
// is presumed to have already been loaded via the jdbc.drivers system property or an
// explicit call to Class.forName("org.postgresql.Driver") elsewhere.
...
</div>
<p>
If you use the <a href="apidocs/com/mchange/v2/c3p0/DataSources.html">DataSources</a>
factory class, and you want to programmatically override default configuration
parameters, you can supply a map of override properties:
</p>
<div class="example">
DataSource ds_unpooled = DataSources.unpooledDataSource("jdbc:postgresql://localhost/testdb",
"swaldman",
"test-password");
Map overrides = new HashMap();
overrides.put("maxStatements", "200"); //Stringified property values work
overrides.put("maxPoolSize", new Integer(50)); //"boxed primitives" also work
// create the PooledDataSource using the default configuration and our overrides
ds_pooled = DataSources.pooledDataSource( ds_unpooled, overrides );
// The DataSource ds_pooled is now a fully configured and usable pooled DataSource,
// with Statement caching enabled for a maximum of up to 200 statements and a maximum
// of 50 Connections.
...
</div>
<p>
If you are using <a href="#named_configurations">named configurations</a>, you can specify the configuration
that defines the default configuration for your DataSource:
</p>
<div class="example">
// create the PooledDataSource using the a named configuration and specified overrides
// "intergalactoApp" is a named configuration
ds_pooled = DataSources.pooledDataSource( ds_unpooled, "intergalactoApp", overrides );
</div>
<p><a id="showDataSourcesWithPoolConfig"
style="display: block"
href="#"
onClick="return toggleDisplay('showDataSourcesWithPoolConfig', 'DataSourcesWithPoolConfig');"
>Show deprecated PoolConfig approach...</a></p>
<div class="deprecated" style="display: none" id="DataSourcesWithPoolConfig">
<h5>Deprecated! Programmatic configuration via PoolConfig</h5>
<p>
If you use the <a href="apidocs/com/mchange/v2/c3p0/DataSources.html">DataSources</a>
factory class, and you want to programmatically override default configuration
parameters, make use of the <a href="apidocs/com/mchange/v2/c3p0/PoolConfig.html"><tt>PoolConfig</tt></a> class:
</p>
<div class="example">
DataSource ds_unpooled = DataSources.unpooledDataSource("jdbc:postgresql://localhost/testdb",
"swaldman",
"test-password");
PoolConfig pc = new PoolConfig();
pc.setMaxStatements(200); //turn on Statement pooling
// pass our overriding PoolConfig to the DataSources.pooledDataSource() factory method.
ds_pooled = DataSources.pooledDataSource( ds_unpooled, pc );
// The DataSource ds_pooled is now a fully configured and usable pooled DataSource,
// with Statement caching enabled for a maximum of up to 200 statements.
...
</div>
<a id="hideDataSourcesWithPoolConfig"
href="#"
onClick="return toggleDisplay('showDataSourcesWithPoolConfig', 'DataSourcesWithPoolConfig');"
>Hide deprecated PoolConfig approach</a>
</div>
<div class="boxed">
<a name="forceOverrideBox" />
<h4>RARE: Forcing authentication information, regardless of (mis)configuration of the underlying (unpooled) DataSource</h4>
<p>
You can wrap any DataSouce using <tt>DataSource.pooledDataSource( ... )</tt>, usually with no
problem whatsoever. DataSources are supposed to indicate the username and password associated
by default with Connections via standard properties <tt>user</tt> and <tt>password</tt>.
Some DataSource implementations do not offer these properties. Usually this is not at all
a problem. <tt>c3p0</tt> works around this
by acquiring "default" Connections from the DataSource if it can't find default authentication
information, and a client has not specified the authentification information via
<tt>getConnection( user, password )</tt>.
</p>
<p>
However, in rare circumstances, non-c3p0 unpooled DataSources provide a <tt>user</tt> property,
but not a password property, or you have access to a DataSource that you wish to wrap behind a pool,
but you wish to override its build-in authentification defaults without actually modifying the <tt>user</tt>
or <tt>password</tt> properties.
</p>
<p>
<tt>c3p0</tt> provides configuation properties <tt>overrideDefaultUser</tt> and <tt>overrideDefaultPassword</tt>.
If you set these properties, programmatically as above, or via any of c3p0's <a href="#configuration">configuration mechanisms</a>,
<tt>c3p0</tt> PooledDataSources will ignore the user and password property associated with the underlying DataSource,
and use the specified overrides instead.
</p>
</div>
<h3>
<a name="querying">Querying a PooledDataSource's current status</a>
<span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span>
</h3>
<p>
c3p0 DataSources backed by a pool, which include implementations of
<a href="apidocs/com/mchange/v2/c3p0/ComboPooledDataSource.html"><tt>ComboPooledDataSource</tt></a> and
the objects returned by <tt><a href="apidocs/com/mchange/v2/c3p0/DataSources.html">DataSources</a>.pooledDataSource( ... )</tt>,
all implement the interface
<a href="apidocs/com/mchange/v2/c3p0/PooledDataSource.html"><tt>com.mchange.v2.c3p0.PooledDataSource</tt></a>,
which makes available a number of methods for querying the status of
DataSource Connection pools. Below is sample code that queries a DataSource for its
status:
</p>
<div class="example">
// fetch a JNDI-bound DataSource
InitialContext ictx = new InitialContext();
DataSource ds = (DataSource) ictx.lookup( "java:comp/env/jdbc/myDataSource" );
// make sure it's a c3p0 PooledDataSource
if ( ds instanceof PooledDataSource)
{
PooledDataSource pds = (PooledDataSource) ds;
System.err.println("num_connections: " + pds.getNumConnectionsDefaultUser());
System.err.println("num_busy_connections: " + pds.getNumBusyConnectionsDefaultUser());
System.err.println("num_idle_connections: " + pds.getNumIdleConnectionsDefaultUser());
System.err.println();
}
else
System.err.println("Not a c3p0 PooledDataSource!");
</div>
<p>
The status querying methods all come in three overloaded forms, such as:
</p>
<ul>
<li><tt>public int getNumConnectionsDefaultUser()</tt></li>
<li><tt>public int getNumConnections(String username, String password)</tt></li>
<li><tt>public int getNumConnectionsAllUsers()</tt></li>
</ul>
<p>
c3p0 maintains separate pools for Connections with distinct
authentications. The various methods let you query the status of pools individually,
or aggregate statistics for all authentifications for which your DataSource is maintaining
pools. <i>Note that pool configuration parmeters such as <tt>maxPoolSize</tt> are enforced
on a per-authentification basis!</i> For example, if you have set <tt>maxPoolSize</tt> to
20, and if the DataSource is managing connections under two username-password pairs [the
default, and one other pair established via a call to <tt>getConnection(user, password)</tt>,
you should expect to see as many as 40 Connections from <tt>getNumConnectionsAllUsers()</tt>.
</p>
<p>
<i>
Most applications only acquire default-authenticated Connections from DataSources, and
can typically just use the <tt>getXXXDefaultUser()</tt> to gather Connection statistics.
</i>
</p>
<p>
As well as Connection pool realted statistics, you can retrieve status information about each
DataSource's Thread pool.
Please see <a href="apidocs/com/mchange/v2/c3p0/PooledDataSource.html"><tt>PooledDataSource</tt>
for a complete list of available operations.</a>
</p>
<div class="boxed">
<a name="using_c3p0_registry_box" />
<h4>Using C3P0Registry to get a reference to a DataSource</h4>
<p>
If it's inconvenient or impossible to get a reference to your DataSource via JNDI or some other means,
you can find all live c3p0 DataSources using the
<a href="apidocs/com/mchange/v2/c3p0/C3P0Registry.html"><tt>C3P0Registry</tt></a> class, which includes
three static methods to help you out:
</p>
<ul>
<li><tt>public static Set getPooledDataSources()</tt></li>
<li><tt>public static Set pooledDataSourcesByName( String dataSourceName )</tt></li>
<li><tt>public static <a href="apidocs/com/mchange/v2/c3p0/PooledDataSource.html">PooledDataSource</a>
pooledDataSourceByName( String dataSourceName )</tt></li>
</ul>
<p>
The first method will hand you the Set of all live c3p0
<a href="apidocs/com/mchange/v2/c3p0/PooledDataSource.html">PooledDataSources</a>. If you are sure
your application only makes one <a href="apidocs/com/mchange/v2/c3p0/PooledDataSource.html">PooledDataSources</a>,
or you can distinguish between the DataSources by their configuration properties (inspected via "getters"), the
first method may be sufficient. Because this will not always be the case, c3p0
<a href="apidocs/com/mchange/v2/c3p0/PooledDataSource.html">PooledDataSources</a> have a special property called
<tt>dataSourceName</tt>. You can set the <tt>dataSourceName</tt> property directly when you construct your
DataSource, or dataSourceName can be set like any other property in a named or the default config.
Otherwise, <tt>dataSourceName</tt> will default to either 1) the name of your DataSource's configuration, if
you constructed it with a <a href="#named_configurations">named configuration</a>; or 2) a unique (but unpredicatble)
name if you are using the default configuration.
</p>
<p>
There is no guarantee that a <tt>dataSourceName</tt> will be unique. For example, if two c3p0 DataSources share
the same <a href="#named_configurations">named configuration</a>, and you have not set the <tt>dataSourceName</tt> programmatically, the two
data sources will both share the name of the configuration. To get all of the DataSources with a particular
<tt>dataSourceName</tt>, use <tt>pooledDataSourcesByName( ... )</tt>. If you've ensured that your DataSource's
name is unique (as you will generally want to do, if you intend to use
<a href="apidocs/com/mchange/v2/c3p0/C3P0Registry.html"><tt>C3P0Registry</tt></a> to find your DataSources),
you can use the convenience method <tt>pooledDataSourceByName( ... )</tt>, which will return your DataSource
directly, or <tt>null</tt> if no DataSource with that name is available. If you use <tt>pooledDataSourceByName( ... )</tt>
and more than one DataSource shares the name supplied, which one it will return is undefined.
</p>
</div>
<h3>
<a name="cleaning">Cleaning up after c3p0 PooledDataSources</a>
<span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span>
</h3>
<p>
The easy way to clean up after c3p0-created DataSources is to use the static destroy method
defined by the class <a href="apidocs/com/mchange/v2/c3p0/DataSources.html">DataSources</a>. Only
<a href="apidocs/com/mchange/v2/c3p0/PooledDataSource.html"><tt>PooledDataSource</tt></a>s
need to be cleaned up, but
<a href="apidocs/com/mchange/v2/c3p0/DataSources.html">DataSources</a>.destroy( ... ) does no harm if it is called on an unpooled or non-c3p0
DataSource.
</p>
<div class="example">
DataSource ds_pooled = null;
try
{
DataSource ds_unpooled = DataSources.unpooledDataSource("jdbc:postgresql://localhost/testdb",
"swaldman",
"test-password");
ds_pooled = DataSources.pooledDataSource( ds_unpooled );
// do all kinds of stuff with that sweet pooled DataSource...
}
finally
{
DataSources.destroy( ds_pooled );
}
</div>
<p>
Alternatively, c3p0's <a href="apidocs/com/mchange/v2/c3p0/PooledDataSource.html"><tt>PooledDataSource</tt></a>
interface contains a <tt>close()</tt> method
that you can call when you know you are finished with a DataSource. So, you can cast a c3p0
derived DataSource to a <tt>PooledDataSource</tt> and close it:
</p>
<div class="example">
static void cleanup(DataSource ds) throws SQLException
{
// make sure it's a c3p0 PooledDataSource
if ( ds instanceof PooledDataSource)
{
PooledDataSource pds = (PooledDataSource) ds;
pds.close();
}
else
System.err.println("Not a c3p0 PooledDataSource!");
}
</div>
<p>
<a href="apidocs/com/mchange/v2/c3p0/ComboPooledDataSource.html"><tt>ComboPooledDataSource</tt></a>
is an instance of <a href="apidocs/com/mchange/v2/c3p0/PooledDataSource.html"><tt>PooledDataSource</tt></a>,
and can be closed directly via its <tt>close()</tt> method. <tt>PooledDataSource</tt> implements <tt>java.lang.AutoCloseable</tt>,
so they may be managed by
<a href="http://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html">Java 7+ try-with-resources</a> blocks.
</p>
<p>
Unreferenced instances of <a href="apidocs/com/mchange/v2/c3p0/PooledDataSource.html"><tt>PooledDataSource</tt></a>
that are not <tt>close()</tt>ed by clients
<tt>close()</tt> themselves prior to garbage collection in their <tt>finalize()</tt> methods.
As always, finalization should be considered
a backstop and not a prompt or sure approach to resource cleanup.
</p>
<h3>
<a name="build_your_own">Advanced: Building your own PoolBackedDataSource</a>
<span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span>
</h3>
<p>
There is little reason for most programmers to do this, but you can build a PooledDataSource in a
step-by-step way by instantiating and configuring an unpooled
<a href="apidocs/com/mchange/v2/c3p0/DriverManagerDataSource.html"><tt>DriverManagerDataSource</tt></a>, instantiating a
<a href="apidocs/com/mchange/v2/c3p0/WrapperConnectionPoolDataSource.html"><tt>WrapperConnectionPoolDataSource</tt></a>
and setting the unpooled DataSource as its <tt>nestedDataSource</tt> property,
and then using that to set the <tt>connectionPoolDataSource</tt> property of a new
<a href="apidocs/com/mchange/v2/c3p0/PoolBackedDataSource.html"><tt>PoolBackedDataSource</tt></a>.
</p>
<p>
This sequence of events is primarily interesting if your driver offers an implementation of ConnectionPoolDataSource, and you'd
like c3p0 to use that. Rather than using c3p0's
<a href="apidocs/com/mchange/v2/c3p0/WrapperConnectionPoolDataSource.html"><tt>WrapperConnectionPoolDataSource</tt></a>,
you can create a <a href="apidocs/com/mchange/v2/c3p0/PoolBackedDataSource.html"><tt>PoolBackedDataSource</tt></a>
and set its <tt>connectionPoolDataSource</tt> property. Statement pooling,
<a href="apidocs/com/mchange/v2/c3p0/ConnectionCustomizer.html"><tt>ConnectionCustomizers</tt></a>, and many c3p0-specific properties
are unsupported with third party implementations of <tt>ConnectionPoolDataSource</tt>. (Third-party <tt>DataSource</tt> implementations
can be substituted for c3p0's
<a href="apidocs/com/mchange/v2/c3p0/DriverManagerDataSource.html"><tt>DriverManagerDataSource</tt></a> with no significant loss of
functionality.)
</p>
<h3>
<a name="raw_connection_ops">Advanced: Raw Connection and Statement Operations</a>
<span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span>
</h3>
<div class="boxed">
<b>
Note: As of c3p0-0.9.5, c3p0 supports the standard JDBC4 <tt>unwrap()</tt> methods
for looking through proxies. Note that if you use the <tt>unwrap()</tt> methods, c3p0
can not clean up any <tt>Statement</tt> or <tt>ResultSet</tt> objects you may generate
from raw Connections or Statements. Users must take care to clean up these objects directly.
Further, users should take care not to modify underlying <tt>Connection</tt>s in some manner
that would render them no longer interchangeable with other <tt>Connection</tt>s, as they must
be to remain suitable for pooling.
</b>
</div>
<p>
JDBC drivers sometimes define vendor-specific, non-standard API on Connection and Statement implementations. C3P0 wraps
these Objects behind a proxies, so you cannot cast C3P0-returned Connections or Statements to the vendor-specific implementation
classes. C3P0 does not provide any means of accessing the raw Connections and Statements directly, because C3P0 needs to keep
track of Statements and ResultSets created in order to prevent resource leaks and pool
corruption.
</p>
<p>
C3P0 does provide an API that allows you to invoke non-standard methods reflectively on an underlying
Connection. To use it, first cast the returned Connection to a
<a href="apidocs/com/mchange/v2/c3p0/C3P0ProxyConnection.html"><tt>C3P0ProxyConnection</tt></a>. Then call
the method <tt>rawConnectionOperation</tt>, supplying the <tt>java.lang.reflect.Method</tt> object for
the non-standard method you wish to call as an argument. The <tt>Method</tt> you supply will be invoked
on the target you provide on the second argument (null for static methods), and using the arguments you
supply in the third argument to that function. For the target, and for any of the method arguments, you
can supply the special token <tt>C3P0ProxyConnection.RAW_CONNECTION</tt>, which will be replaced with
the underlying vendor-specific Connection object before the <tt>Method</tt> is invoked.
</p>
<p>
<a href="apidocs/com/mchange/v2/c3p0/C3P0ProxyStatement.html"><tt>C3P0ProxyStatement</tt></a> offers
an exactly analogous API.
</p>
<p>
Any Statements (including Prepared and CallableStatements) and ResultSets returned by raw operations
will be c3p0-managed, and will be properly cleaned-up on <tt>close()</tt> of the parent proxy Connection.
Users must take care to clean up any non-standard resources returned by a vendor-specific method.
</p>
<p>
Here's an example of using Oracle-specific API to call a static method on a raw Connection:
</p>
<div class="example">
C3P0ProxyConnection castCon = (C3P0ProxyConnection) c3p0DataSource.getConnection();
Method m = CLOB.class.getMethod("createTemporary", new Class[]{Connection.class, boolean.class, int.class});
Object[] args = new Object[] {C3P0ProxyConnection.RAW_CONNECTION, Boolean.valueOf( true ), new Integer( 10 )};
CLOB oracleCLOB = (CLOB) castCon.rawConnectionOperation(m, null, args);
</div>
<p>
<i>C3P0 includes special support for some Oracle-specific methods.
See <a href="#oracle-specific">Appendix F</a>.
</i>
</p>
<h2><a name="configuration">Configuration</a><span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span></h2>
<h3>
<a name="programmatic_configuration"></a><a name="configuration_introduction">Introduction</a>
<span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span>
</h3>
<p>
While c3p0 does not <i>require</i> very much configuration, it is very tweakable. Most of the interesting
knobs and dials are represented as JavaBean properties. Following JavaBean conventions, we note that
if an Object has a property of type <tt>T</tt> called <tt>foo</tt>, it will have methods that look
like...
<blockquote><tt>
public T getFoo();<br/>
public void setFoo(T foo);
</tt></blockquote>
...or both, depending upon whether the property is read-only, write-only, or read-writable.
</p>
<p>
There are several ways to modify c3p0 properties:
You can directly alter the property values associated with a particular DataSource in your code,
or you can configure c3p0 externally...<ul>
<li>via a <a href="#c3p0_properties">simple Java properties file</a></li>
<li>via <a href="#c3p0_conf">HOCON (typesafe-config) files</a> (if and only if you bundle the typesafe-config library with your application)</li>
<li>via an <a href="#c3p0-config.xml">XML configuration file</a></li>
<li>via <a href="#system_properties">System properties</a></li></ul> Configuration files
are normally looked up under standard names (<tt>c3p0.properties</tt> or <tt>c3p0-config.xml</tt>)
at the top level of an application's classpath, but the XML configuration can be placed
anywhere in an application's file system or classpath, if the system property <a href="#locating_configuration_information"><tt>com.mchange.v2.c3p0.cfg.xml</tt></a> is set.
</p>
<p>
DataSources are usually configured before they are used, either
during or immediately following their construction. c3p0 does
support property modifications midstream, however.
</p>
<p>
If you obtain a DataSource by instantiating a
<a href="apidocs/com/mchange/v2/c3p0/ComboPooledDataSource.html"><tt>ComboPooledDataSource</tt></a>,
configure it by simply calling appropriate setter methods offered by that class
before attempting a call to <tt>getConnection()</tt>. See the example above.
</p>
<p>
If you obtain a DataSource by using factory methods of
the utility class <a href="apidocs/com/mchange/v2/c3p0/DataSources.html"><tt>com.mchange.v2.c3p0.DataSources</tt></a>,
and wish to use a non-default configuration, you can supply a Map of property names (beginning with lower-case letters)
to property values (either as Strings or "boxed" Java primitives like Integer or Boolean).
</p>
<p>
All tweakable properties are documented for reference
in <a href="#configuration_properties">Appendix A</a>. Most c3p0 configuration
topics are discussed in detail below.
</p>
<h3>
<a name="basic_pool_configuration">Basic Pool Configuration</a>
<span class="toplink"><a href="#contents"><img src="arrow_sm.png" width="20" alt="Go To Top"/></a></span>
</h3>
<p>
c3p0 Connection pools are very easy to configure via the following basic parameters:
</p>
<ul>
<li><a class="cfg_param" href="#acquireIncrement">acquireIncrement</a></li>
<li><a class="cfg_param" href="#initialPoolSize">initialPoolSize</a></li>
<li><a class="cfg_param" href="#maxPoolSize">maxPoolSize</a></li>
<li><a class="cfg_param" href="#maxIdleTime">maxIdleTime</a></li>
<li><a class="cfg_param" href="#minPoolSize">minPoolSize</a></li>
</ul>
<p>
<tt>initialPoolSize</tt>, <tt>minPoolSize</tt>, <tt>maxPoolSize</tt>
define the number of Connections that will be pooled. Please ensure that
<tt>minPoolSize <= maxPoolSize</tt>. Unreasonable values of <tt>initialPoolSize</tt> will
be ignored, and <tt>minPoolSize</tt> will be used instead.
</p>
<p>
Within the range between <tt>minPoolSize</tt> and <tt>maxPoolSize</tt>, the number of Connections in
a pool varies according to usage patterns. The number of Connections increases whenever a Connection
is requested by a user, no Connections are available, and the pool has not yet reached <tt>maxPoolSize</tt>
in the number of Connections managed.
</p>
<p>
Since Connection acquisition is very slow, it is almost always useful to
increase the number of Connections eagerly, in batches, rather than forcing each client to wait for a new
Connection to provoke a single acquisition when the load is increasing. <tt>acquireIncrement</tt> determines
how many Connections a c3p0 pool will attempt to acquire when the pool has run out of Connections. (Regardless
of <tt>acquireIncrement</tt>, the pool will never allow <tt>maxPoolSize</tt> to be exceeded.)