c3p0參數詳解

C3P0是一個開源的JDBC連接池。

在Spring中，C3P0的一些配置，介紹如下（只列了一部分，不是全部）

<!-- c3p0連接池配置 -->
     <bean id="dataSource" class="com.mchange.v2.c3p0.ComboPooledDataSource">
          <!-- 用戶名-->
          <property name="user" value="${username}"/>
          <!-- 用戶密碼-->
          <property name="password" value="${password}"/>
          <property name="driverClass" value="${driver_class}"/>
          <property name="jdbcUrl" value="${url}"/>

           <!--連接池中保留的最大連接數。默認值: 15 -->
          <property name="maxPoolSize" value="20"/>
          <!-- 連接池中保留的最小連接數，默認爲：3-->
          <property name="minPoolSize" value="2"/>
          <!-- 初始化連接池中的連接數，取值應在minPoolSize與maxPoolSize之間，默認爲3-->
          <property name="initialPoolSize" value="2"/>

          <!--最大空閒時間，60秒內未使用則連接被丟棄。若爲0則永不丟棄。默認值: 0 -->
          <property name="maxIdleTime">60</property>

          <!-- 當連接池連接耗盡時，客戶端調用getConnection()後等待獲取新連接的時間，超時後將拋出SQLException，如設爲0則無限期等待。單位毫秒。默認: 0 -->
          <property name="checkoutTimeout" value="3000"/>

          <!--當連接池中的連接耗盡的時候c3p0一次同時獲取的連接數。默認值: 3 -->
          <property name="acquireIncrement" value="2"/>

         <!--定義在從數據庫獲取新連接失敗後重復嘗試的次數。默認值: 30 ；小於等於0表示無限次-->
          <property name="acquireRetryAttempts" value="0"/>

          <!--重新嘗試的時間間隔，默認爲：1000毫秒-->
          <property name="acquireRetryDelay" value="1000" />

          <!--關閉連接時，是否提交未提交的事務，默認爲false，即關閉連接，回滾未提交的事務 -->
          <property name="autoCommitOnClose">false</property>

          <!--c3p0將建一張名爲Test的空表，並使用其自帶的查詢語句進行測試。如果定義了這個參數那麼屬性preferredTestQuery將被忽略。你不能在這張Test表上進行任何操作，它將只供c3p0測試使用。默認值: null -->
          <property name="automaticTestTable">Test</property>

          <!--如果爲false，則獲取連接失敗將會引起所有等待連接池來獲取連接的線程拋出異常，但是數據源仍有效保留，並在下次調用getConnection()的時候繼續嘗試獲取連接。如果設爲true，那麼在嘗試獲取連接失敗後該數據源將申明已斷開並永久關閉。默認: false-->
          <property name="breakAfterAcquireFailure">false</property>

          <!--每60秒檢查所有連接池中的空閒連接。默認值: 0，不檢查 -->
          <property name="idleConnectionTestPeriod">60</property>
          <!--c3p0全局的PreparedStatements緩存的大小。如果maxStatements與maxStatementsPerConnection均爲0，則緩存不生效，只要有一個不爲0，則語句的緩存就能生效。如果默認值: 0-->
          <property name="maxStatements">100</property>
          <!--maxStatementsPerConnection定義了連接池內單個連接所擁有的最大緩存statements數。默認值: 0 -->
          <property name="maxStatementsPerConnection"></property>
     </bean>

==============================================================================================================

C3P0更詳細的配置項及其含義，請參考：http://www.mchange.com/projects/c3p0/index.html，部分內容摘錄如下：

acquireIncrement acquireRetryAttempts acquireRetryDelay autoCommitOnClose automaticTestTable breakAfterAcquireFailure checkoutTimeout connectionCustomizerClassName connectionTesterClassName debugUnreturnedConnectionStackTraces factoryClassLocation

forceIgnoreUnresolvedTransactions idleConnectionTestPeriod initialPoolSize maxAdministrativeTaskTime maxConnectionAge maxIdleTime maxIdleTimeExcessConnections maxPoolSize maxStatements maxStatementsPerConnection minPoolSize

numHelperThreads overrideDefaultUser overrideDefaultPassword password preferredTestQuery propertyCycle testConnectionOnCheckin testConnectionOnCheckout unreturnedConnectionTimeout user usesTraditionalReflectiveProxies

acquireIncrement

Default: 3

Determines how many connections at a time c3p0 will try to acquire when the pool is exhausted. [See "Basic Pool Configuration"]

acquireRetryAttempts

Default: 30

Defines how many times c3p0 will try to acquire a new Connection from the database before giving up. If this value is less than or equal to zero, c3p0 will keep trying to fetch a Connection indefinitely. [See "Configuring Recovery From Database Outages"]

acquireRetryDelay

Default: 1000

Milliseconds, time c3p0 will wait between acquire attempts. [See "Configuring Recovery From Database Outages"]

autoCommitOnClose

Default: false

The JDBC spec is unforgivably silent on what should happen to unresolved, pending transactions on Connection close. C3P0's default policy is to rollback any uncommitted, pending work. (I think this is absolutely, undeniably the right policy, but there is no consensus among JDBC driver vendors.) Setting autoCommitOnClose to true causes uncommitted pending work to be committed, rather than rolled back on Connection close. [Note: Since the spec is absurdly unclear on this question, application authors who wish to avoid bugs and inconsistent behavior should ensure that all transactions are explicitly either committed or rolled-back before close is called.] [See "Configuring Unresolved Transaction Handling"]

automaticTestTable

Default: null

If provided, c3p0 will create an empty table of the specified name, and use queries against that table to test the Connection. If automaticTestTable is provided, c3p0 will generate its own test query, therefore any preferredTestQuery set will be ignored. You should not work with the named table after c3p0 creates it; it should be strictly for c3p0's use in testing your Connection. (If you define your own ConnectionTester, it must implement the QueryConnectionTester interface for this parameter to be useful.) [See "Configuring Connection Testing"]

breakAfterAcquireFailure

Default: false

If true, a pooled DataSource will declare itself broken and be permanently closed if a Connection cannot be obtained from the database after making acquireRetryAttempts to acquire one. If false, failure to obtain a Connection will cause all Threads waiting for the pool to acquire a Connection to throw an Exception, but the DataSource will remain valid, and will attempt to acquire again following a call to getConnection(). [See "Configuring Recovery From Database Outages"]

checkoutTimeout

Default: 0

The number of milliseconds a client calling getConnection() will wait for a Connection to be checked-in or acquired when the pool is exhausted. Zero means wait indefinitely. Setting any positive value will cause the getConnection() call to time-out and break with an SQLException after the specified number of milliseconds.

connectionCustomizerClassName

Default: null

The fully qualified class-name of an implememtation of the ConnectionCustomizer interface, which users can implement to set up Connections when they are acquired from the database, or on check-out, and potentially to clean things up on check-in and Connection destruction. If standard Connection properties (holdability, readOnly, or transactionIsolation) are set in the ConnectionCustomizer's onAcquire() method, these will override the Connection default values.

connectionTesterClassName

Default: com.mchange.v2.c3p0.impl.DefaultConnectionTester

The fully qualified class-name of an implememtation of the ConnectionTester interface, or QueryConnectionTester if you would like instances to have access to a user-configured preferredTestQuery. This can be used to customize how c3p0 DataSources test Connections, but with the introduction of automaticTestTable and preferredTestQuery configuration parameters, "rolling your own" should be overkill for most users. [See "Configuring Connection Testing"]

debugUnreturnedConnectionStackTraces

Default: false

If true, and if unreturnedConnectionTimeout is set to a positive value, then the pool will capture the stack trace (via an Exception) of all Connection checkouts, and the stack traces will be printed when unreturned checked-out Connections timeout. This is intended to debug applications with Connection leaks, that is applications that occasionally fail to return Connections, leading to pool growth, and eventually exhaustion (when the pool hits maxPoolSize with all Connections checked-out and lost). This parameter should only be set while debugging, as capturing the stack trace will slow down every Connection check-out.

Does Not Support Per-User Overrides.

factoryClassLocation

Default: null

DataSources that will be bound by JNDI and use that API's Referenceable interface to store themselves may specify a URL from which the class capable of dereferencing a them may be loaded. If (as is usually the case) the c3p0 libraries will be locally available to the JNDI service, leave this set as null.

Does Not Support Per-User Overrides.

forceIgnoreUnresolvedTransactions

Default: false

Strongly disrecommended. Setting this to true may lead to subtle and bizarre bugs. This is a terrible setting, leave it alone unless absolutely necessary. It is here to workaround broken databases / JDBC drivers that do not properly support transactions, but that allow Connections' autoCommit flags to go to false regardless. If you are using a database that supports transactions "partially" (this is oxymoronic, as the whole point of transactions is to perform operations reliably and completely, but nonetheless such databases are out there), if you feel comfortable ignoring the fact that Connections with autoCommit == false may be in the middle of transactions and may hold locks and other resources, you may turn off c3p0's wise default behavior, which is to protect itself, as well as the usability and consistency of the database, by either rolling back (default) or committing (see c3p0.autoCommitOnClose above) unresolved transactions. This should only be set to true when you are sure you are using a database that allows Connections' autoCommit flag to go to false, but offers no other meaningful support of transactions. Otherwise setting this to true is just a bad idea. [See "Configuring Unresolved Transaction Handling"]

idleConnectionTestPeriod

Default: 0

If this is a number greater than 0, c3p0 will test all idle, pooled but unchecked-out connections, every this number of seconds. [See "Configuring Connection Testing"]

initialPoolSize

Default: 3

Number of Connections a pool will try to acquire upon startup. Should be between minPoolSize and maxPoolSize. [See "Basic Pool Configuration"]

maxAdministrativeTaskTime

Default: 0

Seconds before c3p0's thread pool will try to interrupt an apparently hung task. Rarely useful. Many of c3p0's functions are not performed by client threads, but asynchronously by an internal thread pool. c3p0's asynchrony enhances client performance directly, and minimizes the length of time that critical locks are held by ensuring that slow jdbc operations are performed in non-lock-holding threads. If, however, some of these tasks "hang", that is they neither succeed nor fail with an Exception for a prolonged period of time, c3p0's thread pool can become exhausted and administrative tasks backed up. If the tasks are simply slow, the best way to resolve the problem is to increase the number of threads, via numHelperThreads. But if tasks sometimes hang indefinitely, you can use this parameter to force a call to the task thread's interrupt() method if a task exceeds a set time limit. [c3p0 will eventually recover from hung tasks anyway by signalling an "APPARENT DEADLOCK" (you'll see it as a warning in the logs), replacing the thread pool task threads, and interrupt()ing the original threads. But letting the pool go into APPARENT DEADLOCK and then recover means that for some periods, c3p0's performance will be impaired. So if you're seeing these messages, increasing numHelperThreads and setting maxAdministrativeTaskTime might help.maxAdministrativeTaskTime should be large enough that any resonable attempt to acquire a Connection from the database, to test a Connection, or two destroy a Connection, would be expected to succeed or fail within the time set. Zero (the default) means tasks are never interrupted, which is the best and safest policy under most circumstances. If tasks are just slow, allocate more threads. If tasks are hanging forever, try to figure out why, and maybe setting maxAdministrativeTaskTime can help in the meantime.

Does Not Support Per-User Overrides.

maxConnectionAge

Default: 0

Seconds, effectively a time to live. A Connection older than maxConnectionAge will be destroyed and purged from the pool. This differs from maxIdleTime in that it refers to absolute age. Even a Connection which has not been much idle will be purged from the pool if it exceeds maxConnectionAge. Zero means no maximum absolute age is enforced.

maxIdleTime

Default: 0

Seconds a Connection can remain pooled but unused before being discarded. Zero means idle connections never expire. [See "Basic Pool Configuration"]

maxIdleTimeExcessConnections

Default: 0

Number of seconds that Connections in excess of minPoolSize should be permitted to remain idle in the pool before being culled. Intended for applications that wish to aggressively minimize the number of open Connections, shrinking the pool back towards minPoolSize if, following a spike, the load level diminishes and Connections acquired are no longer needed. If maxIdleTime is set,maxIdleTimeExcessConnections should be smaller if the parameter is to have any effect. Zero means no enforcement, excess Connections are not idled out.

maxPoolSize

Default: 15

Maximum number of Connections a pool will maintain at any given time. [See "Basic Pool Configuration"]

maxStatements

Default: 0

The size of c3p0's global PreparedStatement cache. If both maxStatements and maxStatementsPerConnection are zero, statement caching will not be enabled. If maxStatements is zero butmaxStatementsPerConnection is a non-zero value, statement caching will be enabled, but no global limit will be enforced, only the per-connection maximum. maxStatements controls the total number of Statements cached, for all Connections. If set, it should be a fairly large number, as each pooled Connection requires its own, distinct flock of cached statements. As a guide, consider how many distinct PreparedStatements are used frequently in your application, and multiply that number by maxPoolSize to arrive at an appropriate value. Though maxStatements is the JDBC standard parameter for controlling statement caching, users may find c3p0's alternative maxStatementsPerConnection more intuitive to use. [See "Configuring Statement Pooling"]

maxStatementsPerConnection

Default: 0

The number of PreparedStatements c3p0 will cache for a single pooled Connection. If both maxStatements and maxStatementsPerConnection are zero, statement caching will not be enabled. IfmaxStatementsPerConnection is zero but maxStatements is a non-zero value, statement caching will be enabled, and a global limit enforced, but otherwise no limit will be set on the number of cached statements for a single Connection. If set, maxStatementsPerConnection should be set to about the number distinct PreparedStatements that are used frequently in your application, plus two or three extra so infrequently statements don't force the more common cached statements to be culled. Though maxStatements is the JDBC standard parameter for controlling statement caching, users may find maxStatementsPerConnection more intuitive to use. [See "Configuring Statement Pooling"]

minPoolSize

Default: 3

Minimum number of Connections a pool will maintain at any given time. [See "Basic Pool Configuration"]

numHelperThreads

Default: 3

c3p0 is very asynchronous. Slow JDBC operations are generally performed by helper threads that don't hold contended locks. Spreading these operations over multiple threads can significantly improve performance by allowing multiple operations to be performed simultaneously.

Does Not Support Per-User Overrides.

overrideDefaultUser

Default: null

Forces the username that should by PooledDataSources when a user calls the default getConnection() method. This is primarily useful when applications are pooling Connections from a non-c3p0 unpooled DataSource. Applications that use ComboPooledDataSource, or that wrap any c3p0-implemented unpooled DataSource can use the simple user property.

Does Not Support Per-User Overrides.

overrideDefaultPassword

Default: null

Forces the password that should by PooledDataSources when a user calls the default getConnection() method. This is primarily useful when applications are pooling Connections from a non-c3p0 unpooled DataSource. Applications that use ComboPooledDataSource, or that wrap any c3p0-implemented unpooled DataSource can use the simple password property.

Does Not Support Per-User Overrides.

password

Default: null

For applications using ComboPooledDataSource or any c3p0-implemented unpooled DataSources — DriverManagerDataSource or the DataSource returned by DataSources.unpooledDataSource( ... ) — defines the password that will be used for the DataSource's default getConnection() method. (See also user.)

Does Not Support Per-User Overrides.

preferredTestQuery

Default: null

Defines the query that will be executed for all connection tests, if the default ConnectionTester (or some other implementation of QueryConnectionTester, or better yet FullQueryConnectionTester) is being used. Defining a preferredTestQuery that will execute quickly in your database may dramatically speed up Connection tests. (If no preferredTestQuery is set, the default ConnectionTester executes a getTables() call on the Connection's DatabaseMetaData. Depending on your database, this may execute more slowly than a "normal" database query.) NOTE: The table against which your preferredTestQuery will be run must exist in the database schema prior to your initialization of your DataSource. If your application defines its own schema, tryautomaticTestTable instead. [See "Configuring Connection Testing"]

propertyCycle

Default: 0

Maximum time in seconds before user configuration constraints are enforced. Determines how frequently maxConnectionAge, maxIdleTime, maxIdleTimeExcessConnections, unreturnedConnectionTimeoutare enforced. c3p0 periodically checks the age of Connections to see whether they've timed out. This parameter determines the period. Zero means automatic: A suitable period will be determined by c3p0. [You can call getEffectivePropertyCycle...() methods on a c3p0 PooledDataSource to find the period automatically chosen.]

testConnectionOnCheckin

Default: false

If true, an operation will be performed asynchronously at every connection checkin to verify that the connection is valid. Use in combination with idleConnectionTestPeriod for quite reliable, always asynchronous Connection testing. Also, setting an automaticTestTable or preferredTestQuery will usually speed up all connection tests. [See "Configuring Connection Testing"]

testConnectionOnCheckout

Default: false

Use only if necessary. Expensive. If true, an operation will be performed at every connection checkout to verify that the connection is valid. Better choice: verify connections periodically usingidleConnectionTestPeriod. Also, setting an automaticTestTable or preferredTestQuery will usually speed up all connection tests. [See "Configuring Connection Testing"]

unreturnedConnectionTimeout

Default: 0

Seconds. If set, if an application checks out but then fails to check-in [i.e. close()] a Connection within the specified period of time, the pool will unceremoniously destroy() the Connection. This permits applications with occasional Connection leaks to survive, rather than eventually exhausting the Connection pool. And that's a shame. Zero means no timeout, applications are expected to close() their own Connections. Obviously, if a non-zero value is set, it should be to a value longer than any Connection should reasonably be checked-out. Otherwise, the pool will occasionally kill Connections in active use, which is bad. This is basically a bad idea, but it's a commonly requested feature. Fix your $%!@% applications so they don't leak Connections! Use this temporarily in combination with debugUnreturnedConnectionStackTraces to figure out where Connections are being checked-out that don't make it back into the pool!

user

Default: null

For applications using ComboPooledDataSource or any c3p0-implemented unpooled DataSources — DriverManagerDataSource or the DataSource returned by DataSources.unpooledDataSource() — defines the username that will be used for the DataSource's default getConnection() method. (See also password.)

Does Not Support Per-User Overrides.

usesTraditionalReflectiveProxies

Default: false

c3p0 originally used reflective dynamic proxies for implementations of Connections and other JDBC interfaces. As of c3p0-0.8.5, non-reflective, code-generated implementations are used instead. As this was a major change, and the old codebase had been extensively used and tested, this parameter was added to allow users to revert of they had problems. The new, non-reflexive implementation is faster, and has now been widely deployed and tested, so it is unlikely that this parameter will be useful. Both the old reflective and newer non-reflective codebases are being maintained, but support for the older codebase may (or may not) be dropped in the future.

=======================================================================================================================

一個task應用數據庫連接配置的例子：

<bean id="dataSource" class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
          <property name="staticMethod">
              <value>com.mchange.v2.c3p0.DataSources.pooledDataSource</value>
          </property>
          <property name="arguments">
              <list>
                <ref local="olpsUnpooledDataSource"/>
                    <props>
                        <prop key="acquireIncrement">1</prop>
                        <prop key="initialPoolSize">1</prop>
                        <prop key="minPoolSize">1</prop>
                        <prop key="maxPoolSize">5</prop>
                        <prop key="maxIdleTime">1800</prop>
                        <prop key="maxIdleTimeExcessConnections">1000</prop> <!-- 自動收縮連接用的,單位秒-->
                        <!-- 自動重連需要的三個參數  -->
                        <prop key="acquireRetryAttempts">30</prop>
                        <prop key="acquireRetryDelay">1000</prop>
                        <prop key="breakAfterAcquireFailure">false</prop>
                        <!-- 獲取一個connection需要的時間，單位毫秒 -->
                        <prop key="checkoutTimeout">500</prop>
                    </props>
            </list>
        </property>
    </bean>

    <bean id="olpsUnpooledDataSource" class="com.mchange.v2.c3p0.DriverManagerDataSource">
        <property name="driverClass">
            <value>com.alibaba.china.jdbc.SimpleDriver</value>
        </property>
        <property name="jdbcUrl">
            <value>${database.driver.url}</value>
        </property>
        <property name="properties">
            <bean class="com.alibaba.china.biz.common.security.SecureIdentityLoginModule">
                <property name="user"><value>${username}</value></property>
                <property name="password"><value>${password}</value></property>
                <property name="bigStringTryClob"><value>true</value></property>
                <property name="clientEncoding"><value>GBK</value></property>
                <property name="serverEncoding"><value>ISO-8859-1</value></property>
            </bean>
        </property>
    </bean>