DataSourceFactory (Apache Tomcat 11.0.23 API Documentation)
Description: declaration: package: org.apache.tomcat.jdbc.pool, class: DataSourceFactory

# 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.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final String[]`
  `ALL_PROPERTIES`
  Array of all supported property names.
  `static final String`
  `OBJECT_NAME`
  Property name for the JMX object name.
  `protected static final String`
  `PROP_ABANDONWHENPERCENTAGEFULL`
  Property name for abandonWhenPercentageFull.
  `protected static final String`
  `PROP_ACCESSTOUNDERLYINGCONNECTIONALLOWED`
  Property name for accessToUnderlyingConnectionAllowed.
  `protected static final String`
  `PROP_ALTERNATE_USERNAME_ALLOWED`
  Property name for alternateUsernameAllowed.
  `protected static final String`
  `PROP_COMMITONRETURN`
  Property name for commitOnReturn.
  `protected static final String`
  `PROP_CONNECTIONPROPERTIES`
  Property name for connectionProperties.
  `protected static final String`
  `PROP_DATASOURCE`
  Property name for dataSource.
  `protected static final String`
  `PROP_DATASOURCE_JNDI`
  Property name for dataSourceJNDI.
  `protected static final String`
  `PROP_DEFAULTAUTOCOMMIT`
  Property name for defaultAutoCommit.
  `protected static final String`
  `PROP_DEFAULTCATALOG`
  Property name for defaultCatalog.
  `protected static final String`
  `PROP_DEFAULTREADONLY`
  Property name for defaultReadOnly.
  `protected static final String`
  `PROP_DEFAULTTRANSACTIONISOLATION`
  Property name for defaultTransactionIsolation.
  `protected static final String`
  `PROP_DRIVERCLASSNAME`
  Property name for driverClassName.
  `protected static final String`
  `PROP_FAIR_QUEUE`
  Property name for fairQueue.
  `protected static final String`
  `PROP_IGNOREEXCEPTIONONPRELOAD`
  Property name for ignoreExceptionOnPreLoad.
  `protected static final String`
  `PROP_INITIALSIZE`
  Property name for initialSize.
  `protected static final String`
  `PROP_INITSQL`
  Property name for initSQL.
  `protected static final String`
  `PROP_INTERCEPTORS`
  Property name for jdbcInterceptors.
  `protected static final String`
  `PROP_JMX_ENABLED`
  Property name for jmxEnabled.
  `protected static final String`
  `PROP_LOGABANDONED`
  Property name for logAbandoned.
  `protected static final String`
  `PROP_LOGVALIDATIONERRORS`
  Property name for logValidationErrors.
  `protected static final String`
  `PROP_MAXACTIVE`
  Property name for maxActive.
  `protected static final String`
  `PROP_MAXAGE`
  Property name for maxAge.
  `protected static final String`
  `PROP_MAXIDLE`
  Property name for maxIdle.
  `protected static final String`
  `PROP_MAXOPENPREPAREDSTATEMENTS`
  Property name for maxOpenPreparedStatements.
  `protected static final String`
  `PROP_MAXWAIT`
  Property name for maxWait.
  `protected static final String`
  `PROP_MINEVICTABLEIDLETIMEMILLIS`
  Property name for minEvictableIdleTimeMillis.
  `protected static final String`
  `PROP_MINIDLE`
  Property name for minIdle.
  `protected static final String`
  `PROP_NUMTESTSPEREVICTIONRUN`
  Property name for numTestsPerEvictionRun.
  `protected static final String`
  `PROP_PASSWORD`
  Property name for password.
  `protected static final String`
  `PROP_POOLPREPAREDSTATEMENTS`
  Property name for poolPreparedStatements.
  `protected static final String`
  `PROP_PROPAGATEINTERRUPTSTATE`
  Property name for propagateInterruptState.
  `protected static final String`
  `PROP_REMOVEABANDONED`
  Property name for removeAbandoned.
  `protected static final String`
  `PROP_REMOVEABANDONEDTIMEOUT`
  Property name for removeAbandonedTimeout.
  `protected static final String`
  `PROP_ROLLBACKONRETURN`
  Property name for rollbackOnReturn.
  `protected static final String`
  `PROP_SUSPECT_TIMEOUT`
  Property name for suspectTimeout.
  `protected static final String`
  `PROP_TESTONBORROW`
  Property name for testOnBorrow.
  `protected static final String`
  `PROP_TESTONCONNECT`
  Property name for testOnConnect.
  `protected static final String`
  `PROP_TESTONRETURN`
  Property name for testOnReturn.
  `protected static final String`
  `PROP_TESTWHILEIDLE`
  Property name for testWhileIdle.
  `protected static final String`
  `PROP_TIMEBETWEENEVICTIONRUNSMILLIS`
  Property name for timeBetweenEvictionRunsMillis.
  `protected static final String`
  `PROP_URL`
  Property name for url.
  `protected static final String`
  `PROP_USE_CON_LOCK`
  Property name for useLock.
  `protected static final String`
  `PROP_USE_EQUALS`
  Property name for useEquals.
  `protected static final String`
  `PROP_USEDISPOSABLECONNECTIONFACADE`
  Property name for useDisposableConnectionFacade.
  `protected static final String`
  `PROP_USERNAME`
  Property name for username.
  `protected static final String`
  `PROP_USESTATEMENTFACADE`
  Property name for useStatementFacade.
  `protected static final String`
  `PROP_VALIDATIONINTERVAL`
  Property name for validationInterval.
  `protected static final String`
  `PROP_VALIDATIONQUERY`
  Property name for validationQuery.
  `protected static final String`
  `PROP_VALIDATIONQUERY_TIMEOUT`
  Property name for validationQueryTimeout.
  `protected static final String`
  `PROP_VALIDATOR_CLASS_NAME`
  Property name for validatorClassName.
  `static final int`
  `UNKNOWN_TRANSACTIONISOLATION`
  Value indicating an unknown transaction isolation level.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DataSourceFactory()`
  Default constructor.

- ## Method Summary

  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)`
  Creates and configures a `DataSource` instance based on the given properties.
  `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)`
  Parse the given properties into a PoolConfiguration.
  `void`
  `performJNDILookup(Context context, PoolConfiguration poolProperties)`
  Perform a JNDI lookup for the data source.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### PROP_DEFAULTAUTOCOMMIT

    protected static final String PROP_DEFAULTAUTOCOMMIT
    Property name for defaultAutoCommit.
    See Also:
      - Constant Field Values

  - ### PROP_DEFAULTREADONLY

    protected static final String PROP_DEFAULTREADONLY
    Property name for defaultReadOnly.
    See Also:
      - Constant Field Values

  - ### PROP_DEFAULTTRANSACTIONISOLATION

    protected static final String PROP_DEFAULTTRANSACTIONISOLATION
    Property name for defaultTransactionIsolation.
    See Also:
      - Constant Field Values

  - ### PROP_DEFAULTCATALOG

    protected static final String PROP_DEFAULTCATALOG
    Property name for defaultCatalog.
    See Also:
      - Constant Field Values

  - ### PROP_DRIVERCLASSNAME

    protected static final String PROP_DRIVERCLASSNAME
    Property name for driverClassName.
    See Also:
      - Constant Field Values

  - ### PROP_PASSWORD

    protected static final String PROP_PASSWORD
    Property name for password.
    See Also:
      - Constant Field Values

  - ### PROP_URL

    protected static final String PROP_URL
    Property name for url.
    See Also:
      - Constant Field Values

  - ### PROP_USERNAME

    protected static final String PROP_USERNAME
    Property name for username.
    See Also:
      - Constant Field Values

  - ### PROP_MAXACTIVE

    protected static final String PROP_MAXACTIVE
    Property name for maxActive.
    See Also:
      - Constant Field Values

  - ### PROP_MAXIDLE

    protected static final String PROP_MAXIDLE
    Property name for maxIdle.
    See Also:
      - Constant Field Values

  - ### PROP_MINIDLE

    protected static final String PROP_MINIDLE
    Property name for minIdle.
    See Also:
      - Constant Field Values

  - ### PROP_INITIALSIZE

    protected static final String PROP_INITIALSIZE
    Property name for initialSize.
    See Also:
      - Constant Field Values

  - ### PROP_MAXWAIT

    protected static final String PROP_MAXWAIT
    Property name for maxWait.
    See Also:
      - Constant Field Values

  - ### PROP_MAXAGE

    protected static final String PROP_MAXAGE
    Property name for maxAge.
    See Also:
      - Constant Field Values

  - ### PROP_TESTONBORROW

    protected static final String PROP_TESTONBORROW
    Property name for testOnBorrow.
    See Also:
      - Constant Field Values

  - ### PROP_TESTONRETURN

    protected static final String PROP_TESTONRETURN
    Property name for testOnReturn.
    See Also:
      - Constant Field Values

  - ### PROP_TESTWHILEIDLE

    protected static final String PROP_TESTWHILEIDLE
    Property name for testWhileIdle.
    See Also:
      - Constant Field Values

  - ### PROP_TESTONCONNECT

    protected static final String PROP_TESTONCONNECT
    Property name for testOnConnect.
    See Also:
      - Constant Field Values

  - ### PROP_VALIDATIONQUERY

    protected static final String PROP_VALIDATIONQUERY
    Property name for validationQuery.
    See Also:
      - Constant Field Values

  - ### PROP_VALIDATIONQUERY_TIMEOUT

    protected static final String PROP_VALIDATIONQUERY_TIMEOUT
    Property name for validationQueryTimeout.
    See Also:
      - Constant Field Values

  - ### PROP_VALIDATOR_CLASS_NAME

    protected static final String PROP_VALIDATOR_CLASS_NAME
    Property name for validatorClassName.
    See Also:
      - Constant Field Values

  - ### PROP_NUMTESTSPEREVICTIONRUN

    protected static final String PROP_NUMTESTSPEREVICTIONRUN
    Property name for numTestsPerEvictionRun.
    See Also:
      - Constant Field Values

  - ### PROP_TIMEBETWEENEVICTIONRUNSMILLIS

    protected static final String PROP_TIMEBETWEENEVICTIONRUNSMILLIS
    Property name for timeBetweenEvictionRunsMillis.
    See Also:
      - Constant Field Values

  - ### PROP_MINEVICTABLEIDLETIMEMILLIS

    protected static final String PROP_MINEVICTABLEIDLETIMEMILLIS
    Property name for minEvictableIdleTimeMillis.
    See Also:
      - Constant Field Values

  - ### PROP_ACCESSTOUNDERLYINGCONNECTIONALLOWED

    protected static final String PROP_ACCESSTOUNDERLYINGCONNECTIONALLOWED
    Property name for accessToUnderlyingConnectionAllowed.
    See Also:
      - Constant Field Values

  - ### PROP_REMOVEABANDONED

    protected static final String PROP_REMOVEABANDONED
    Property name for removeAbandoned.
    See Also:
      - Constant Field Values

  - ### PROP_REMOVEABANDONEDTIMEOUT

    protected static final String PROP_REMOVEABANDONEDTIMEOUT
    Property name for removeAbandonedTimeout.
    See Also:
      - Constant Field Values

  - ### PROP_LOGABANDONED

    protected static final String PROP_LOGABANDONED
    Property name for logAbandoned.
    See Also:
      - Constant Field Values

  - ### PROP_ABANDONWHENPERCENTAGEFULL

    protected static final String PROP_ABANDONWHENPERCENTAGEFULL
    Property name for abandonWhenPercentageFull.
    See Also:
      - Constant Field Values

  - ### PROP_POOLPREPAREDSTATEMENTS

    protected static final String PROP_POOLPREPAREDSTATEMENTS
    Property name for poolPreparedStatements.
    See Also:
      - Constant Field Values

  - ### PROP_MAXOPENPREPAREDSTATEMENTS

    protected static final String PROP_MAXOPENPREPAREDSTATEMENTS
    Property name for maxOpenPreparedStatements.
    See Also:
      - Constant Field Values

  - ### PROP_CONNECTIONPROPERTIES

    protected static final String PROP_CONNECTIONPROPERTIES
    Property name for connectionProperties.
    See Also:
      - Constant Field Values

  - ### PROP_INITSQL

    protected static final String PROP_INITSQL
    Property name for initSQL.
    See Also:
      - Constant Field Values

  - ### PROP_INTERCEPTORS

    protected static final String PROP_INTERCEPTORS
    Property name for jdbcInterceptors.
    See Also:
      - Constant Field Values

  - ### PROP_VALIDATIONINTERVAL

    protected static final String PROP_VALIDATIONINTERVAL
    Property name for validationInterval.
    See Also:
      - Constant Field Values

  - ### PROP_JMX_ENABLED

    protected static final String PROP_JMX_ENABLED
    Property name for jmxEnabled.
    See Also:
      - Constant Field Values

  - ### PROP_FAIR_QUEUE

    protected static final String PROP_FAIR_QUEUE
    Property name for fairQueue.
    See Also:
      - Constant Field Values

  - ### PROP_USE_EQUALS

    protected static final String PROP_USE_EQUALS
    Property name for useEquals.
    See Also:
      - Constant Field Values

  - ### PROP_USE_CON_LOCK

    protected static final String PROP_USE_CON_LOCK
    Property name for useLock.
    See Also:
      - Constant Field Values

  - ### PROP_DATASOURCE

    protected static final String PROP_DATASOURCE
    Property name for dataSource.
    See Also:
      - Constant Field Values

  - ### PROP_DATASOURCE_JNDI

    protected static final String PROP_DATASOURCE_JNDI
    Property name for dataSourceJNDI.
    See Also:
      - Constant Field Values

  - ### PROP_SUSPECT_TIMEOUT

    protected static final String PROP_SUSPECT_TIMEOUT
    Property name for suspectTimeout.
    See Also:
      - Constant Field Values

  - ### PROP_ALTERNATE_USERNAME_ALLOWED

    protected static final String PROP_ALTERNATE_USERNAME_ALLOWED
    Property name for alternateUsernameAllowed.
    See Also:
      - Constant Field Values

  - ### PROP_COMMITONRETURN

    protected static final String PROP_COMMITONRETURN
    Property name for commitOnReturn.
    See Also:
      - Constant Field Values

  - ### PROP_ROLLBACKONRETURN

    protected static final String PROP_ROLLBACKONRETURN
    Property name for rollbackOnReturn.
    See Also:
      - Constant Field Values

  - ### PROP_USEDISPOSABLECONNECTIONFACADE

    protected static final String PROP_USEDISPOSABLECONNECTIONFACADE
    Property name for useDisposableConnectionFacade.
    See Also:
      - Constant Field Values

  - ### PROP_LOGVALIDATIONERRORS

    protected static final String PROP_LOGVALIDATIONERRORS
    Property name for logValidationErrors.
    See Also:
      - Constant Field Values

  - ### PROP_PROPAGATEINTERRUPTSTATE

    protected static final String PROP_PROPAGATEINTERRUPTSTATE
    Property name for propagateInterruptState.
    See Also:
      - Constant Field Values

  - ### PROP_IGNOREEXCEPTIONONPRELOAD

    protected static final String PROP_IGNOREEXCEPTIONONPRELOAD
    Property name for ignoreExceptionOnPreLoad.
    See Also:
      - Constant Field Values

  - ### PROP_USESTATEMENTFACADE

    protected static final String PROP_USESTATEMENTFACADE
    Property name for useStatementFacade.
    See Also:
      - Constant Field Values

  - ### UNKNOWN_TRANSACTIONISOLATION

    public static final int UNKNOWN_TRANSACTIONISOLATION
    Value indicating an unknown transaction isolation level.
    See Also:
      - Constant Field Values

  - ### OBJECT_NAME

    public static final String OBJECT_NAME
    Property name for the JMX object name.
    See Also:
      - Constant Field Values

  - ### ALL_PROPERTIES

    protected static final String[] ALL_PROPERTIES
    Array of all supported property names.

- ## Constructor Details

  - ### DataSourceFactory

    public DataSourceFactory()
    Default constructor.

- ## Method Details

  - ### 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)
    Parse the given properties into a PoolConfiguration.
    Parameters:
      `properties` - The properties to parse
    Returns:
      The configured PoolConfiguration

  - ### 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
    Creates and configures a `DataSource` instance based on the given properties.
    Parameters:
      `properties` - The datasource configuration properties
      `context` - The JNDI context
      `XA` - `true` to create an XA data source
    Returns:
      The configured datasource
    Throws:
      `Exception` - if an error occurs creating the data source

  - ### performJNDILookup

    public void performJNDILookup(Context context, PoolConfiguration poolProperties)
    Perform a JNDI lookup for the data source.
    Parameters:
      `context` - The JNDI context
      `poolProperties` - The pool configuration

  - ### 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