com.mchange.v2.c3p0
Class PoolConfig

java.lang.Object
  extended bycom.mchange.v2.c3p0.PoolConfig

public final class PoolConfig
extends java.lang.Object

Encapsulates all the configuration information required by a c3p0 pooled DataSource.

Newly constructed PoolConfig objects are preset with default values, which you can define yourself (see below), or you can rely on c3p0's built-in defaults. Just create a PoolConfig object, and change only the properties you care about. Then pass it to the DataSources.pooledDataSource(javax.sql.DataSource, com.mchange.v2.c3p0.PoolConfig) method, and you're off!

For those interested in the details, configuration properties can be specified in several ways:

  1. Any property can be set explicitly by calling the corresponding method on a PoolConfig object.
  2. Any property will default to a value defined by a System Property, using the property name shown the table below.
  3. Any property not set in either of the above ways will default to a value found in a user-supplied Java properties file, which may be placed in the resource path of the ClassLoader that loaded the c3p0 libraries under the name /c3p0.properties.
  4. Any property not set in any of the above ways will be defined according c3p0's built-in defaults.
Property NameBuilt-In DefaultComments
c3p0.initialPoolSize3 
c3p0.minPoolSize3 
c3p0.maxPoolSize15 
c3p0.idleConnectionTestPeriod 0 If this is a number greater than 0, c3p0 will test all idle, pooled but unchecked-out connections, every this number of seconds.
c3p0.maxIdleTime 0 Seconds a Connection can remain pooled but unused before being discarded. Zero means idle connections never expire.
c3p0.maxStatements 0 The size of c3p0's PreparedStatement cache. Zero means statement cahing is turned off.
c3p0.propertyCycle 300 Maximum time in seconds before user configuration constraints are enforced. c3p0 enforces configuration constraints continually, and ignores this parameter. It is included for JDBC 3 completeness.
c3p0.acquireIncrement 3 Determines how many connections at a time c3p0 will try to acquire when the pool is exhausted.
c3p0.testConnectionOnCheckout false Don't use. Very expensive. If true, an operation will be performed at every connection checkout to verify that the connection is valid. Better choice: verify connections periodically using c3p0.idleConnectionTestPeriod
c3p0.autoCommitOnClose 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.]
c3p0.forceIgnoreUnresolvedTransactions 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.
c3p0.connectionTesterClassName com.mchange. v2.c3p0.impl. DefaultConnectionTester See ConnectionTester
c3p0.numHelperThreads 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.
c3p0.factoryClassLocation 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.


Field Summary
static java.lang.String ACQUIRE_INCREMENT
           
static java.lang.String AUTO_COMMIT_ON_CLOSE
           
static java.lang.String CONNECTION_TESTER_CLASS_NAME
           
static java.lang.String DEFAULT_CONFIG_RSRC_PATH
           
static java.lang.String FACTORY_CLASS_LOCATION
           
static java.lang.String FORCE_IGNORE_UNRESOLVED_TRANSACTIONS
           
static java.lang.String IDLE_CONNECTION_TEST_PERIOD
           
static java.lang.String INITIAL_POOL_SIZE
           
static java.lang.String MAX_IDLE_TIME
           
static java.lang.String MAX_POOL_SIZE
           
static java.lang.String MAX_STATEMENTS
           
static java.lang.String MIN_POOL_SIZE
           
static java.lang.String NUM_HELPER_THREADS
           
static java.lang.String PROPERTY_CYCLE
           
static java.lang.String TEST_CONNECTION_ON_CHECKOUT
           
 
Constructor Summary
PoolConfig()
           
PoolConfig(java.util.Properties props)
           
 
Method Summary
static int defaultAcquireIncrement()
           
static boolean defaultAutoCommitOnClose()
           
static java.lang.String defaultConnectionTesterClassName()
           
static java.lang.String defaultFactoryClassLocation()
           
static boolean defaultForceIgnoreUnresolvedTransactions()
           
static int defaultIdleConnectionTestPeriod()
           
static int defaultInitialPoolSize()
           
static int defaultMaxIdleTime()
           
static int defaultMaxPoolSize()
           
static int defaultMaxStatements()
           
static int defaultMinPoolSize()
           
static int defaultNumHelperThreads()
           
static int defaultPropertyCycle()
           
static boolean defaultTestConnectionOnCheckout()
           
 int getAcquireIncrement()
           
 java.lang.String getConnectionTesterClassName()
           
 java.lang.String getFactoryClassLocation()
           
 int getIdleConnectionTestPeriod()
           
 int getInitialPoolSize()
           
 int getMaxIdleTime()
           
 int getMaxPoolSize()
           
 int getMaxStatements()
           
 int getMinPoolSize()
           
 int getNumHelperThreads()
           
 int getPropertyCycle()
           
 boolean getTestConnectionOnCheckout()
          Deprecated. use isTestConnectionOnCheckout
 boolean isAutoCommitOnClose()
           
 boolean isForceIgnoreUnresolvedTransactions()
           
 boolean isTestConnectionOnCheckout()
           
 void setAcquireIncrement(int acquireIncrement)
           
 void setAutoCommitOnClose(boolean autoCommitOnClose)
           
 void setConnectionTesterClassName(java.lang.String connectionTesterClassName)
           
 void setFactoryClassLocation(java.lang.String factoryClassLocation)
           
 void setForceIgnoreUnresolvedTransactions(boolean forceIgnoreUnresolvedTransactions)
           
 void setIdleConnectionTestPeriod(int idleConnectionTestPeriod)
           
 void setInitialPoolSize(int initialPoolSize)
           
 void setMaxIdleTime(int maxIdleTime)
           
 void setMaxPoolSize(int maxPoolSize)
           
 void setMaxStatements(int maxStatements)
           
 void setMinPoolSize(int minPoolSize)
           
 void setNumHelperThreads(int numHelperThreads)
           
 void setPropertyCycle(int propertyCycle)
           
 void setTestConnectionOnCheckout(boolean testConnectionOnCheckout)
          Deprecated. you really shouldn't use testConnectionOnCheckout, it's a performance nightmare. let it default to false, and if you want Connections to be tested, set a reasonable value for idleConnectionTestPeriod.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

INITIAL_POOL_SIZE

public static final java.lang.String INITIAL_POOL_SIZE
See Also:
Constant Field Values

MIN_POOL_SIZE

public static final java.lang.String MIN_POOL_SIZE
See Also:
Constant Field Values

MAX_POOL_SIZE

public static final java.lang.String MAX_POOL_SIZE
See Also:
Constant Field Values

IDLE_CONNECTION_TEST_PERIOD

public static final java.lang.String IDLE_CONNECTION_TEST_PERIOD
See Also:
Constant Field Values

MAX_IDLE_TIME

public static final java.lang.String MAX_IDLE_TIME
See Also:
Constant Field Values

PROPERTY_CYCLE

public static final java.lang.String PROPERTY_CYCLE
See Also:
Constant Field Values

MAX_STATEMENTS

public static final java.lang.String MAX_STATEMENTS
See Also:
Constant Field Values

ACQUIRE_INCREMENT

public static final java.lang.String ACQUIRE_INCREMENT
See Also:
Constant Field Values

TEST_CONNECTION_ON_CHECKOUT

public static final java.lang.String TEST_CONNECTION_ON_CHECKOUT
See Also:
Constant Field Values

CONNECTION_TESTER_CLASS_NAME

public static final java.lang.String CONNECTION_TESTER_CLASS_NAME
See Also:
Constant Field Values

AUTO_COMMIT_ON_CLOSE

public static final java.lang.String AUTO_COMMIT_ON_CLOSE
See Also:
Constant Field Values

FORCE_IGNORE_UNRESOLVED_TRANSACTIONS

public static final java.lang.String FORCE_IGNORE_UNRESOLVED_TRANSACTIONS
See Also:
Constant Field Values

NUM_HELPER_THREADS

public static final java.lang.String NUM_HELPER_THREADS
See Also:
Constant Field Values

FACTORY_CLASS_LOCATION

public static final java.lang.String FACTORY_CLASS_LOCATION
See Also:
Constant Field Values

DEFAULT_CONFIG_RSRC_PATH

public static final java.lang.String DEFAULT_CONFIG_RSRC_PATH
See Also:
Constant Field Values
Constructor Detail

PoolConfig

public PoolConfig(java.util.Properties props)
           throws java.lang.NumberFormatException

PoolConfig

public PoolConfig()
           throws java.lang.NumberFormatException
Method Detail

defaultNumHelperThreads

public static int defaultNumHelperThreads()

defaultFactoryClassLocation

public static java.lang.String defaultFactoryClassLocation()

defaultMaxStatements

public static int defaultMaxStatements()

defaultInitialPoolSize

public static int defaultInitialPoolSize()

defaultMinPoolSize

public static int defaultMinPoolSize()

defaultMaxPoolSize

public static int defaultMaxPoolSize()

defaultIdleConnectionTestPeriod

public static int defaultIdleConnectionTestPeriod()

defaultMaxIdleTime

public static int defaultMaxIdleTime()

defaultPropertyCycle

public static int defaultPropertyCycle()

defaultAcquireIncrement

public static int defaultAcquireIncrement()

defaultConnectionTesterClassName

public static java.lang.String defaultConnectionTesterClassName()

defaultTestConnectionOnCheckout

public static boolean defaultTestConnectionOnCheckout()

defaultAutoCommitOnClose

public static boolean defaultAutoCommitOnClose()

defaultForceIgnoreUnresolvedTransactions

public static boolean defaultForceIgnoreUnresolvedTransactions()

getNumHelperThreads

public int getNumHelperThreads()

getFactoryClassLocation

public java.lang.String getFactoryClassLocation()

getMaxStatements

public int getMaxStatements()

getInitialPoolSize

public int getInitialPoolSize()

getMinPoolSize

public int getMinPoolSize()

getMaxPoolSize

public int getMaxPoolSize()

getIdleConnectionTestPeriod

public int getIdleConnectionTestPeriod()

getMaxIdleTime

public int getMaxIdleTime()

getPropertyCycle

public int getPropertyCycle()

getAcquireIncrement

public int getAcquireIncrement()

getConnectionTesterClassName

public java.lang.String getConnectionTesterClassName()

getTestConnectionOnCheckout

public boolean getTestConnectionOnCheckout()
Deprecated. use isTestConnectionOnCheckout


isTestConnectionOnCheckout

public boolean isTestConnectionOnCheckout()

isAutoCommitOnClose

public boolean isAutoCommitOnClose()

isForceIgnoreUnresolvedTransactions

public boolean isForceIgnoreUnresolvedTransactions()

setNumHelperThreads

public void setNumHelperThreads(int numHelperThreads)

setFactoryClassLocation

public void setFactoryClassLocation(java.lang.String factoryClassLocation)

setMaxStatements

public void setMaxStatements(int maxStatements)

setInitialPoolSize

public void setInitialPoolSize(int initialPoolSize)

setMinPoolSize

public void setMinPoolSize(int minPoolSize)

setMaxPoolSize

public void setMaxPoolSize(int maxPoolSize)

setIdleConnectionTestPeriod

public void setIdleConnectionTestPeriod(int idleConnectionTestPeriod)

setMaxIdleTime

public void setMaxIdleTime(int maxIdleTime)

setPropertyCycle

public void setPropertyCycle(int propertyCycle)

setAcquireIncrement

public void setAcquireIncrement(int acquireIncrement)

setConnectionTesterClassName

public void setConnectionTesterClassName(java.lang.String connectionTesterClassName)

setTestConnectionOnCheckout

public void setTestConnectionOnCheckout(boolean testConnectionOnCheckout)
Deprecated. you really shouldn't use testConnectionOnCheckout, it's a performance nightmare. let it default to false, and if you want Connections to be tested, set a reasonable value for idleConnectionTestPeriod.


setAutoCommitOnClose

public void setAutoCommitOnClose(boolean autoCommitOnClose)

setForceIgnoreUnresolvedTransactions

public void setForceIgnoreUnresolvedTransactions(boolean forceIgnoreUnresolvedTransactions)