DataSourceFactory (Apache Tomcat 10.1.2 API Documentation)

Package org.apache.tomcat.jdbc.pool

## Class DataSourceFactory

- java.lang.Object
- - org.apache.tomcat.jdbc.pool.DataSourceFactory

- All Implemented Interfaces:
    `ObjectFactory`

      public class DataSourceFactory
      extends Object
      implements ObjectFactory

  JNDI object factory that creates an instance of `BasicDataSource` that has been configured based on the `RefAddr` values of the specified `Reference`, which must match the names and data types of the `BasicDataSource` bean properties.

  Properties available for configuration:
  Commons DBCP properties
  1. initSQL - A query that gets executed once, right after the connection is established.
  2. testOnConnect - run validationQuery after connection has been established.
  3. validationInterval - avoid excess validation, only run validation at most at this frequency - time in milliseconds.
  4. jdbcInterceptors - a semicolon separated list of classnames extending `JdbcInterceptor` class.
  5. jmxEnabled - true of false, whether to register the pool with JMX.
  6. fairQueue - true of false, whether the pool should sacrifice a little bit of performance for true fairness.
  Author:
    Craig R. McClanahan, Dirk Verbeeck

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected static String[]` | `ALL_PROPERTIES` |
    `static String` | `OBJECT_NAME` |
    `protected static String` | `PROP_ABANDONWHENPERCENTAGEFULL` |
    `protected static String` | `PROP_ACCESSTOUNDERLYINGCONNECTIONALLOWED` |
    `protected static String` | `PROP_ALTERNATE_USERNAME_ALLOWED` |
    `protected static String` | `PROP_COMMITONRETURN` |
    `protected static String` | `PROP_CONNECTIONPROPERTIES` |
    `protected static String` | `PROP_DATASOURCE` |
    `protected static String` | `PROP_DATASOURCE_JNDI` |
    `protected static String` | `PROP_DEFAULTAUTOCOMMIT` |
    `protected static String` | `PROP_DEFAULTCATALOG` |
    `protected static String` | `PROP_DEFAULTREADONLY` |
    `protected static String` | `PROP_DEFAULTTRANSACTIONISOLATION` |
    `protected static String` | `PROP_DRIVERCLASSNAME` |
    `protected static String` | `PROP_FAIR_QUEUE` |
    `protected static String` | `PROP_IGNOREEXCEPTIONONPRELOAD` |
    `protected static String` | `PROP_INITIALSIZE` |
    `protected static String` | `PROP_INITSQL` |
    `protected static String` | `PROP_INTERCEPTORS` |
    `protected static String` | `PROP_JMX_ENABLED` |
    `protected static String` | `PROP_LOGABANDONED` |
    `protected static String` | `PROP_LOGVALIDATIONERRORS` |
    `protected static String` | `PROP_MAXACTIVE` |
    `protected static String` | `PROP_MAXAGE` |
    `protected static String` | `PROP_MAXIDLE` |
    `protected static String` | `PROP_MAXOPENPREPAREDSTATEMENTS` |
    `protected static String` | `PROP_MAXWAIT` |
    `protected static String` | `PROP_MINEVICTABLEIDLETIMEMILLIS` |
    `protected static String` | `PROP_MINIDLE` |
    `protected static String` | `PROP_NUMTESTSPEREVICTIONRUN` |
    `protected static String` | `PROP_PASSWORD` |
    `protected static String` | `PROP_POOLPREPAREDSTATEMENTS` |
    `protected static String` | `PROP_PROPAGATEINTERRUPTSTATE` |
    `protected static String` | `PROP_REMOVEABANDONED` |
    `protected static String` | `PROP_REMOVEABANDONEDTIMEOUT` |
    `protected static String` | `PROP_ROLLBACKONRETURN` |
    `protected static String` | `PROP_SUSPECT_TIMEOUT` |
    `protected static String` | `PROP_TESTONBORROW` |
    `protected static String` | `PROP_TESTONCONNECT` |
    `protected static String` | `PROP_TESTONRETURN` |
    `protected static String` | `PROP_TESTWHILEIDLE` |
    `protected static String` | `PROP_TIMEBETWEENEVICTIONRUNSMILLIS` |
    `protected static String` | `PROP_URL` |
    `protected static String` | `PROP_USE_CON_LOCK` |
    `protected static String` | `PROP_USE_EQUALS` |
    `protected static String` | `PROP_USEDISPOSABLECONNECTIONFACADE` |
    `protected static String` | `PROP_USERNAME` |
    `protected static String` | `PROP_USESTATEMENTFACADE` |
    `protected static String` | `PROP_VALIDATIONINTERVAL` |
    `protected static String` | `PROP_VALIDATIONQUERY` |
    `protected static String` | `PROP_VALIDATIONQUERY_TIMEOUT` |
    `protected static String` | `PROP_VALIDATOR_CLASS_NAME` |
    `static int` | `UNKNOWN_TRANSACTIONISOLATION` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DataSourceFactory()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `DataSource` | `createDataSource​(Properties properties)` | Creates and configures a `DataSource` instance based on the given properties.
    `DataSource` | `createDataSource​(Properties properties, Context context, boolean XA)` |
    `Object` | `getObjectInstance​(Object obj, Name name, Context nameCtx, Hashtable<?,​?> environment)` | Create and return a new `BasicDataSource` instance.
    `protected static Properties` | `getProperties​(String propText)` | Parse properties from the string.
    `static PoolConfiguration` | `parsePoolProperties​(Properties properties)` |
    `void` | `performJNDILookup​(Context context, PoolConfiguration poolProperties)` |

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

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

- - ### Field Detail

    - #### PROP_DEFAULTAUTOCOMMIT

          protected static final String PROP_DEFAULTAUTOCOMMIT

      See Also:
        Constant Field Values

    - #### PROP_DEFAULTREADONLY

          protected static final String PROP_DEFAULTREADONLY

      See Also:
        Constant Field Values

    - #### PROP_DEFAULTTRANSACTIONISOLATION

          protected static final String PROP_DEFAULTTRANSACTIONISOLATION

      See Also:
        Constant Field Values

    - #### PROP_DEFAULTCATALOG

          protected static final String PROP_DEFAULTCATALOG

      See Also:
        Constant Field Values

    - #### PROP_DRIVERCLASSNAME

          protected static final String PROP_DRIVERCLASSNAME

      See Also:
        Constant Field Values

    - #### PROP_PASSWORD

          protected static final String PROP_PASSWORD

      See Also:
        Constant Field Values

    - #### PROP_URL

          protected static final String PROP_URL

      See Also:
        Constant Field Values

    - #### PROP_USERNAME

          protected static final String PROP_USERNAME

      See Also:
        Constant Field Values

    - #### PROP_MAXACTIVE

          protected static final String PROP_MAXACTIVE

      See Also:
        Constant Field Values

    - #### PROP_MAXIDLE

          protected static final String PROP_MAXIDLE

      See Also:
        Constant Field Values

    - #### PROP_MINIDLE

          protected static final String PROP_MINIDLE

      See Also:
        Constant Field Values

    - #### PROP_INITIALSIZE

          protected static final String PROP_INITIALSIZE

      See Also:
        Constant Field Values

    - #### PROP_MAXWAIT

          protected static final String PROP_MAXWAIT

      See Also:
        Constant Field Values

    - #### PROP_MAXAGE

          protected static final String PROP_MAXAGE

      See Also:
        Constant Field Values

    - #### PROP_TESTONBORROW

          protected static final String PROP_TESTONBORROW

      See Also:
        Constant Field Values

    - #### PROP_TESTONRETURN

          protected static final String PROP_TESTONRETURN

      See Also:
        Constant Field Values

    - #### PROP_TESTWHILEIDLE

          protected static final String PROP_TESTWHILEIDLE

      See Also:
        Constant Field Values

    - #### PROP_TESTONCONNECT

          protected static final String PROP_TESTONCONNECT

      See Also:
        Constant Field Values

    - #### PROP_VALIDATIONQUERY

          protected static final String PROP_VALIDATIONQUERY

      See Also:
        Constant Field Values

    - #### PROP_VALIDATIONQUERY_TIMEOUT

          protected static final String PROP_VALIDATIONQUERY_TIMEOUT

      See Also:
        Constant Field Values

    - #### PROP_VALIDATOR_CLASS_NAME

          protected static final String PROP_VALIDATOR_CLASS_NAME

      See Also:
        Constant Field Values

    - #### PROP_NUMTESTSPEREVICTIONRUN

          protected static final String PROP_NUMTESTSPEREVICTIONRUN

      See Also:
        Constant Field Values

    - #### PROP_TIMEBETWEENEVICTIONRUNSMILLIS

          protected static final String PROP_TIMEBETWEENEVICTIONRUNSMILLIS

      See Also:
        Constant Field Values

    - #### PROP_MINEVICTABLEIDLETIMEMILLIS

          protected static final String PROP_MINEVICTABLEIDLETIMEMILLIS

      See Also:
        Constant Field Values

    - #### PROP_ACCESSTOUNDERLYINGCONNECTIONALLOWED

          protected static final String PROP_ACCESSTOUNDERLYINGCONNECTIONALLOWED

      See Also:
        Constant Field Values

    - #### PROP_REMOVEABANDONED

          protected static final String PROP_REMOVEABANDONED

      See Also:
        Constant Field Values

    - #### PROP_REMOVEABANDONEDTIMEOUT

          protected static final String PROP_REMOVEABANDONEDTIMEOUT

      See Also:
        Constant Field Values

    - #### PROP_LOGABANDONED

          protected static final String PROP_LOGABANDONED

      See Also:
        Constant Field Values

    - #### PROP_ABANDONWHENPERCENTAGEFULL

          protected static final String PROP_ABANDONWHENPERCENTAGEFULL

      See Also:
        Constant Field Values

    - #### PROP_POOLPREPAREDSTATEMENTS

          protected static final String PROP_POOLPREPAREDSTATEMENTS

      See Also:
        Constant Field Values

    - #### PROP_MAXOPENPREPAREDSTATEMENTS

          protected static final String PROP_MAXOPENPREPAREDSTATEMENTS

      See Also:
        Constant Field Values

    - #### PROP_CONNECTIONPROPERTIES

          protected static final String PROP_CONNECTIONPROPERTIES

      See Also:
        Constant Field Values

    - #### PROP_INITSQL

          protected static final String PROP_INITSQL

      See Also:
        Constant Field Values

    - #### PROP_INTERCEPTORS

          protected static final String PROP_INTERCEPTORS

      See Also:
        Constant Field Values

    - #### PROP_VALIDATIONINTERVAL

          protected static final String PROP_VALIDATIONINTERVAL

      See Also:
        Constant Field Values

    - #### PROP_JMX_ENABLED

          protected static final String PROP_JMX_ENABLED

      See Also:
        Constant Field Values

    - #### PROP_FAIR_QUEUE

          protected static final String PROP_FAIR_QUEUE

      See Also:
        Constant Field Values

    - #### PROP_USE_EQUALS

          protected static final String PROP_USE_EQUALS

      See Also:
        Constant Field Values

    - #### PROP_USE_CON_LOCK

          protected static final String PROP_USE_CON_LOCK

      See Also:
        Constant Field Values

    - #### PROP_DATASOURCE

          protected static final String PROP_DATASOURCE

      See Also:
        Constant Field Values

    - #### PROP_DATASOURCE_JNDI

          protected static final String PROP_DATASOURCE_JNDI

      See Also:
        Constant Field Values

    - #### PROP_SUSPECT_TIMEOUT

          protected static final String PROP_SUSPECT_TIMEOUT

      See Also:
        Constant Field Values

    - #### PROP_ALTERNATE_USERNAME_ALLOWED

          protected static final String PROP_ALTERNATE_USERNAME_ALLOWED

      See Also:
        Constant Field Values

    - #### PROP_COMMITONRETURN

          protected static final String PROP_COMMITONRETURN

      See Also:
        Constant Field Values

    - #### PROP_ROLLBACKONRETURN

          protected static final String PROP_ROLLBACKONRETURN

      See Also:
        Constant Field Values

    - #### PROP_USEDISPOSABLECONNECTIONFACADE

          protected static final String PROP_USEDISPOSABLECONNECTIONFACADE

      See Also:
        Constant Field Values

    - #### PROP_LOGVALIDATIONERRORS

          protected static final String PROP_LOGVALIDATIONERRORS

      See Also:
        Constant Field Values

    - #### PROP_PROPAGATEINTERRUPTSTATE

          protected static final String PROP_PROPAGATEINTERRUPTSTATE

      See Also:
        Constant Field Values

    - #### PROP_IGNOREEXCEPTIONONPRELOAD

          protected static final String PROP_IGNOREEXCEPTIONONPRELOAD

      See Also:
        Constant Field Values

    - #### PROP_USESTATEMENTFACADE

          protected static final String PROP_USESTATEMENTFACADE

      See Also:
        Constant Field Values

    - #### UNKNOWN_TRANSACTIONISOLATION

          public static final int UNKNOWN_TRANSACTIONISOLATION

      See Also:
        Constant Field Values

    - #### OBJECT_NAME

          public static final String OBJECT_NAME

      See Also:
        Constant Field Values

    - #### ALL_PROPERTIES

          protected static final String[] ALL_PROPERTIES

  - ### Constructor Detail

    - #### DataSourceFactory

          public DataSourceFactory()

  - ### Method Detail

    - #### getObjectInstance

          public Object getObjectInstance​(Object obj,
                                          Name name,
                                          Context nameCtx,
                                          Hashtable<?,​?> environment)
                                   throws Exception

      Create and return a new `BasicDataSource` instance. If no instance can be created, return `null` instead.

      Specified by:
        `getObjectInstance` in interface `ObjectFactory`
      Parameters:
        `obj` - The possibly null object containing location or reference information that can be used in creating an object
        `name` - The name of this object relative to `nameCtx`
        `nameCtx` - The context relative to which the `name` parameter is specified, or `null` if `name` is relative to the default initial context
        `environment` - The possibly null environment that is used in creating this object
      Throws:
        `Exception` - if an exception occurs creating the instance

    - #### parsePoolProperties

          public static PoolConfiguration parsePoolProperties​(Properties properties)

    - #### createDataSource

          public DataSource createDataSource​(Properties properties)
                                      throws Exception

      Creates and configures a `DataSource` instance based on the given properties.
      Parameters:
        `properties` - the datasource configuration properties
      Returns:
        the datasource
      Throws:
        `Exception` - if an error occurs creating the data source

    - #### createDataSource

          public DataSource createDataSource​(Properties properties,
                                             Context context,
                                             boolean XA)
                                      throws Exception

      Throws:
        `Exception`

    - #### performJNDILookup

          public void performJNDILookup​(Context context,
                                        PoolConfiguration poolProperties)

    - #### getProperties

          protected static Properties getProperties​(String propText)

      Parse properties from the string. Format of the string must be [propertyName=property;]*.
      Parameters:
        `propText` - The properties string
      Returns:
        the properties