DataSources (c3p0-0.9.5.5 API Documentation)
Date: 2019-12-11

com.mchange.v2.c3p0

## Class DataSources

- java.lang.Object
- - com.mchange.v2.c3p0.DataSources

-     public final class DataSources
      extends java.lang.Object

  A simple factory class for creating DataSources. Generally, users will call `DataSources.unpooledDataSource()` to get a basic DataSource, and then get a pooled version by calling `DataSources.pooledDataSource()`.

  Most users will not need to worry about configuration details. If you want to use a PreparedStatement cache, be sure to call the version of `DataSources.pooledDataSource()` that accepts a `statement_cache_size` parameter, and set that to be a number (much) greater than zero. (For maximum performance, you would set this to be several times the number kinds of PreparedStatements you expect your application to use.)

  For those interested in detailed configuration, note that c3p0 pools can be configured by explicit method calls on PoolConfig objects, by defining System properties, or by defining a `c3p0.properties` file in your resource path. See `PoolConfig` for details.

- - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `destroy(javax.sql.DataSource pooledDataSource)` Immediately releases resources (Threads and database Connections) that are held by a C3P0 DataSource.
    `static void` | `forceDestroy(javax.sql.DataSource pooledDataSource)` Deprecated. forceDestroy() is no longer meaningful, as a set of pools is now directly associated with a DataSource, and not potentially shared. (This simplification was made possible by canonicalization of JNDI-looked-up DataSources within a virtual machine.) Just use DataSources.destroy().
    `static javax.sql.DataSource` | `pooledDataSource(javax.sql.DataSource unpooledDataSource)` Creates a pooled version of an unpooled DataSource using default configuration information.
    `static javax.sql.DataSource` | `pooledDataSource(javax.sql.DataSource unpooledDataSource, int statement_cache_size)` Creates a pooled version of an unpooled DataSource using default configuration information and the specified startement cache size.
    `static javax.sql.DataSource` | `pooledDataSource(javax.sql.DataSource unpooledDataSource, java.util.Map overrideProps)`
    `static javax.sql.DataSource` | `pooledDataSource(javax.sql.DataSource unpooledDataSource, PoolConfig pcfg)` Deprecated. if you want to set properties programmatically, please construct a ComboPooledDataSource and set its properties rather than using PoolConfig
    `static javax.sql.DataSource` | `pooledDataSource(javax.sql.DataSource unpooledDataSource, java.util.Properties props)` Creates a pooled version of an unpooled DataSource using configuration information supplied explicitly by a Java Properties object.
    `static javax.sql.DataSource` | `pooledDataSource(javax.sql.DataSource unpooledDataSource, java.lang.String configName)`
    `static javax.sql.DataSource` | `pooledDataSource(javax.sql.DataSource unpooledDataSource, java.lang.String configName, java.util.Map overrideProps)`
    `static javax.sql.DataSource` | `unpooledDataSource()` Defines an unpooled DataSource all of whose paramateres (especially jdbcUrl) should be set in config files.
    `static javax.sql.DataSource` | `unpooledDataSource(java.lang.String jdbcUrl)`
    `static javax.sql.DataSource` | `unpooledDataSource(java.lang.String jdbcUrl, java.util.Properties driverProps)` Defines an unpooled DataSource on the specified JDBC URL.
    `static javax.sql.DataSource` | `unpooledDataSource(java.lang.String jdbcUrl, java.lang.String user, java.lang.String password)` Defines an unpooled DataSource on the specified JDBC URL, authenticating with a username and password.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### unpooledDataSource

          public static javax.sql.DataSource unpooledDataSource()
                                                         throws java.sql.SQLException

      Defines an unpooled DataSource all of whose paramateres (especially jdbcUrl) should be set in config files.
      Throws:
        `java.sql.SQLException`

    - #### unpooledDataSource

          public static javax.sql.DataSource unpooledDataSource(java.lang.String jdbcUrl)
                                                         throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### unpooledDataSource

          public static javax.sql.DataSource unpooledDataSource(java.lang.String jdbcUrl,
                                                                java.lang.String user,
                                                                java.lang.String password)
                                                         throws java.sql.SQLException

      Defines an unpooled DataSource on the specified JDBC URL, authenticating with a username and password.
      Throws:
        `java.sql.SQLException`

    - #### unpooledDataSource

          public static javax.sql.DataSource unpooledDataSource(java.lang.String jdbcUrl,
                                                                java.util.Properties driverProps)
                                                         throws java.sql.SQLException

      Defines an unpooled DataSource on the specified JDBC URL.
      Parameters:
        `driverProps` - the usual DriverManager properties for your JDBC driver (e.g. "user" and "password" for all drivers that support authentication)
      Throws:
        `java.sql.SQLException`
      See Also:
        `DriverManager`

    - #### pooledDataSource

          public static javax.sql.DataSource pooledDataSource(javax.sql.DataSource unpooledDataSource)
                                                       throws java.sql.SQLException

      Creates a pooled version of an unpooled DataSource using default configuration information.

      NOTE: By default, statement pooling is turned off, because for simple databases that do not pre-parse and optimize PreparedStatements, statement caching is a net performance loss. But if your database does optimize PreparedStatements you'll want to turn StatementCaching on via `pooledDataSource(javax.sql.DataSource, int)`.

      Returns:
        a DataSource that can be cast to a `PooledDataSource` if you are interested in pool statistics
      Throws:
        `java.sql.SQLException`

    - #### pooledDataSource

          public static javax.sql.DataSource pooledDataSource(javax.sql.DataSource unpooledDataSource,
                                                              int statement_cache_size)
                                                       throws java.sql.SQLException

      Creates a pooled version of an unpooled DataSource using default configuration information and the specified startement cache size. Use a value greater than zero to turn statement caching on.

      Returns:
        a DataSource that can be cast to a `PooledDataSource` if you are interested in pool statistics
      Throws:
        `java.sql.SQLException`

    - #### pooledDataSource

          public static javax.sql.DataSource pooledDataSource(javax.sql.DataSource unpooledDataSource,
                                                              PoolConfig pcfg)
                                                       throws java.sql.SQLException

      Deprecated. if you want to set properties programmatically, please construct a ComboPooledDataSource and set its properties rather than using PoolConfig

      Creates a pooled version of an unpooled DataSource using configuration information supplied explicitly by a `PoolConfig`.

      Returns:
        a DataSource that can be cast to a `PooledDataSource` if you are interested in pool statistics
      Throws:
        `java.sql.SQLException`

    - #### pooledDataSource

          public static javax.sql.DataSource pooledDataSource(javax.sql.DataSource unpooledDataSource,
                                                              java.lang.String configName)
                                                       throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### pooledDataSource

          public static javax.sql.DataSource pooledDataSource(javax.sql.DataSource unpooledDataSource,
                                                              java.util.Map overrideProps)
                                                       throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### pooledDataSource

          public static javax.sql.DataSource pooledDataSource(javax.sql.DataSource unpooledDataSource,
                                                              java.lang.String configName,
                                                              java.util.Map overrideProps)
                                                       throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### pooledDataSource

          public static javax.sql.DataSource pooledDataSource(javax.sql.DataSource unpooledDataSource,
                                                              java.util.Properties props)
                                                       throws java.sql.SQLException

      Creates a pooled version of an unpooled DataSource using configuration information supplied explicitly by a Java Properties object.

      Returns:
        a DataSource that can be cast to a `PooledDataSource` if you are interested in pool statistics
      Throws:
        `java.sql.SQLException`
      See Also:
        `PoolConfig`

    - #### destroy

          public static void destroy(javax.sql.DataSource pooledDataSource)
                              throws java.sql.SQLException

      Immediately releases resources (Threads and database Connections) that are held by a C3P0 DataSource.

      Only DataSources created by the poolingDataSource() method hold any non-memory resources. Calling this method on unpooled DataSources is effectively a no-op.

      You can safely presume that destroying a pooled DataSource that is wrapped around another DataSource created by this library destroys both the outer and the wrapped DataSource. There is no reason to hold a reference to a nested DataSource in order to explicitly destroy it.

      Throws:
        `java.sql.SQLException`
      See Also:
        `PoolConfig`

    - #### forceDestroy

          public static void forceDestroy(javax.sql.DataSource pooledDataSource)
                                   throws java.sql.SQLException

      Deprecated. forceDestroy() is no longer meaningful, as a set of pools is now directly associated with a DataSource, and not potentially shared. (This simplification was made possible by canonicalization of JNDI-looked-up DataSources within a virtual machine.) Just use DataSources.destroy().
      Throws:
        `java.sql.SQLException`
      See Also:
        `destroy(javax.sql.DataSource)`