org.apache.tomcat.dbcp.dbcp2.datasources

## Class PerUserPoolDataSource

- java.lang.Object
- - org.apache.tomcat.dbcp.dbcp2.datasources.InstanceKeyDataSource
  - - org.apache.tomcat.dbcp.dbcp2.datasources.PerUserPoolDataSource

- All Implemented Interfaces:
    Serializable, AutoCloseable, Wrapper, Referenceable, CommonDataSource, DataSource

      public class PerUserPoolDataSource
      extends InstanceKeyDataSource

  A pooling `DataSource` appropriate for deployment within J2EE environment. There are many configuration options, most of which are defined in the parent class. This datasource uses individual pools per user, and some properties can be set specifically for a given user, if the deployment environment can support initialization of mapped properties. So for example, a pool of admin or write-access Connections can be guaranteed a certain number of connections, separate from a maximum set for users with read-only connections.

  User passwords can be changed without re-initializing the datasource. When a `getConnection(username, password)` request is processed with a password that is different from those used to create connections in the pool associated with `username`, an attempt is made to create a new connection using the supplied password and if this succeeds, the existing pool is cleared and a new pool is created for connections using the new password.

  Since:
    2.0
  Author:
    John D. McNally
  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from class org.apache.tomcat.dbcp.dbcp2.datasources.InstanceKeyDataSource

      `UNKNOWN_TRANSACTIONISOLATION`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PerUserPoolDataSource()` Default no-arg constructor for Serialization

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close pool(s) being maintained by this datasource.
    `protected org.apache.tomcat.dbcp.dbcp2.datasources.PooledConnectionManager` | `getConnectionManager(org.apache.tomcat.dbcp.dbcp2.datasources.UserPassKey upkey)`
    `int` | `getNumActive()`
    `int` | `getNumActive(String username)`
    `int` | `getNumIdle()`
    `int` | `getNumIdle(String username)`
    `boolean` | `getPerUserBlockWhenExhausted(String key)` Gets the user specific value for `BaseGenericObjectPool.getBlockWhenExhausted()` for the specified user's pool or the default if no user specific value is defined.
    `Boolean` | `getPerUserDefaultAutoCommit(String key)` Gets the user specific default value for `Connection.setAutoCommit(boolean)` for the specified user's pool.
    `Boolean` | `getPerUserDefaultReadOnly(String key)` Gets the user specific default value for `Connection.setReadOnly(boolean)` for the specified user's pool.
    `Integer` | `getPerUserDefaultTransactionIsolation(String key)` Gets the user specific default value for `Connection.setTransactionIsolation(int)` for the specified user's pool.
    `String` | `getPerUserEvictionPolicyClassName(String key)` Gets the user specific value for `BaseGenericObjectPool.getEvictionPolicyClassName()` for the specified user's pool or the default if no user specific value is defined.
    `boolean` | `getPerUserLifo(String key)` Gets the user specific value for `BaseGenericObjectPool.getLifo()` for the specified user's pool or the default if no user specific value is defined.
    `int` | `getPerUserMaxIdle(String key)` Gets the user specific value for `GenericObjectPool.getMaxIdle()` for the specified user's pool or the default if no user specific value is defined.
    `int` | `getPerUserMaxTotal(String key)` Gets the user specific value for `BaseGenericObjectPool.getMaxTotal()` for the specified user's pool or the default if no user specific value is defined.
    `long` | `getPerUserMaxWaitMillis(String key)` Gets the user specific value for `BaseGenericObjectPool.getMaxWaitMillis()` for the specified user's pool or the default if no user specific value is defined.
    `long` | `getPerUserMinEvictableIdleTimeMillis(String key)` Gets the user specific value for `BaseGenericObjectPool.getMinEvictableIdleTimeMillis()` for the specified user's pool or the default if no user specific value is defined.
    `int` | `getPerUserMinIdle(String key)` Gets the user specific value for `GenericObjectPool.getMinIdle()` for the specified user's pool or the default if no user specific value is defined.
    `int` | `getPerUserNumTestsPerEvictionRun(String key)` Gets the user specific value for `BaseGenericObjectPool.getNumTestsPerEvictionRun()` for the specified user's pool or the default if no user specific value is defined.
    `long` | `getPerUserSoftMinEvictableIdleTimeMillis(String key)` Gets the user specific value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for the specified user's pool or the default if no user specific value is defined.
    `boolean` | `getPerUserTestOnBorrow(String key)` Gets the user specific value for `BaseGenericObjectPool.getTestOnBorrow()` for the specified user's pool or the default if no user specific value is defined.
    `boolean` | `getPerUserTestOnCreate(String key)` Gets the user specific value for `BaseGenericObjectPool.getTestOnCreate()` for the specified user's pool or the default if no user specific value is defined.
    `boolean` | `getPerUserTestOnReturn(String key)` Gets the user specific value for `BaseGenericObjectPool.getTestOnReturn()` for the specified user's pool or the default if no user specific value is defined.
    `boolean` | `getPerUserTestWhileIdle(String key)` Gets the user specific value for `BaseGenericObjectPool.getTestWhileIdle()` for the specified user's pool or the default if no user specific value is defined.
    `long` | `getPerUserTimeBetweenEvictionRunsMillis(String key)` Gets the user specific value for `BaseGenericObjectPool.getTimeBetweenEvictionRunsMillis()` for the specified user's pool or the default if no user specific value is defined.
    `protected org.apache.tomcat.dbcp.dbcp2.datasources.PooledConnectionAndInfo` | `getPooledConnectionAndInfo(String username, String password)`
    `Reference` | `getReference()`
    `void` | `setPerUserBlockWhenExhausted(String username, Boolean value)` Sets a user specific value for `BaseGenericObjectPool.getBlockWhenExhausted()` for the specified user's pool.
    `void` | `setPerUserDefaultAutoCommit(String username, Boolean value)` Sets a user specific default value for `Connection.setAutoCommit(boolean)` for the specified user's pool.
    `void` | `setPerUserDefaultReadOnly(String username, Boolean value)` Sets a user specific default value for `Connection.setReadOnly(boolean)` for the specified user's pool.
    `void` | `setPerUserDefaultTransactionIsolation(String username, Integer value)` Sets a user specific default value for `Connection.setTransactionIsolation(int)` for the specified user's pool.
    `void` | `setPerUserEvictionPolicyClassName(String username, String value)` Sets a user specific value for `BaseGenericObjectPool.getEvictionPolicyClassName()` for the specified user's pool.
    `void` | `setPerUserLifo(String username, Boolean value)` Sets a user specific value for `BaseGenericObjectPool.getLifo()` for the specified user's pool.
    `void` | `setPerUserMaxIdle(String username, Integer value)` Sets a user specific value for `GenericObjectPool.getMaxIdle()` for the specified user's pool.
    `void` | `setPerUserMaxTotal(String username, Integer value)` Sets a user specific value for `BaseGenericObjectPool.getMaxTotal()` for the specified user's pool.
    `void` | `setPerUserMaxWaitMillis(String username, Long value)` Sets a user specific value for `BaseGenericObjectPool.getMaxWaitMillis()` for the specified user's pool.
    `void` | `setPerUserMinEvictableIdleTimeMillis(String username, Long value)` Sets a user specific value for `BaseGenericObjectPool.getMinEvictableIdleTimeMillis()` for the specified user's pool.
    `void` | `setPerUserMinIdle(String username, Integer value)` Sets a user specific value for `GenericObjectPool.getMinIdle()` for the specified user's pool.
    `void` | `setPerUserNumTestsPerEvictionRun(String username, Integer value)` Sets a user specific value for `BaseGenericObjectPool.getNumTestsPerEvictionRun()` for the specified user's pool.
    `void` | `setPerUserSoftMinEvictableIdleTimeMillis(String username, Long value)` Sets a user specific value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for the specified user's pool.
    `void` | `setPerUserTestOnBorrow(String username, Boolean value)` Sets a user specific value for `BaseGenericObjectPool.getTestOnBorrow()` for the specified user's pool.
    `void` | `setPerUserTestOnCreate(String username, Boolean value)` Sets a user specific value for `BaseGenericObjectPool.getTestOnCreate()` for the specified user's pool.
    `void` | `setPerUserTestOnReturn(String username, Boolean value)` Sets a user specific value for `BaseGenericObjectPool.getTestOnReturn()` for the specified user's pool.
    `void` | `setPerUserTestWhileIdle(String username, Boolean value)` Sets a user specific value for `BaseGenericObjectPool.getTestWhileIdle()` for the specified user's pool.
    `void` | `setPerUserTimeBetweenEvictionRunsMillis(String username, Long value)` Sets a user specific value for `()` for the specified user's pool.
    `protected void` | `setupDefaults(Connection con, String username)`

    - ### Methods inherited from class org.apache.tomcat.dbcp.dbcp2.datasources.InstanceKeyDataSource

      `assertInitializationAllowed, getConnection, getConnection, getConnectionPoolDataSource, getDataSourceName, getDefaultBlockWhenExhausted, getDefaultEvictionPolicyClassName, getDefaultLifo, getDefaultMaxIdle, getDefaultMaxTotal, getDefaultMaxWaitMillis, getDefaultMinEvictableIdleTimeMillis, getDefaultMinIdle, getDefaultNumTestsPerEvictionRun, getDefaultSoftMinEvictableIdleTimeMillis, getDefaultTestOnBorrow, getDefaultTestOnCreate, getDefaultTestOnReturn, getDefaultTestWhileIdle, getDefaultTimeBetweenEvictionRunsMillis, getDefaultTransactionIsolation, getDescription, getInstanceKey, getJndiEnvironment, getLoginTimeout, getLogWriter, getMaxConnLifetimeMillis, getParentLogger, getValidationQuery, getValidationQueryTimeout, isDefaultAutoCommit, isDefaultReadOnly, isRollbackAfterValidation, isWrapperFor, setConnectionPoolDataSource, setDataSourceName, setDefaultAutoCommit, setDefaultBlockWhenExhausted, setDefaultEvictionPolicyClassName, setDefaultLifo, setDefaultMaxIdle, setDefaultMaxTotal, setDefaultMaxWaitMillis, setDefaultMinEvictableIdleTimeMillis, setDefaultMinIdle, setDefaultNumTestsPerEvictionRun, setDefaultReadOnly, setDefaultSoftMinEvictableIdleTimeMillis, setDefaultTestOnBorrow, setDefaultTestOnCreate, setDefaultTestOnReturn, setDefaultTestWhileIdle, setDefaultTimeBetweenEvictionRunsMillis, setDefaultTransactionIsolation, setDescription, setJndiEnvironment, setLoginTimeout, setLogWriter, setMaxConnLifetimeMillis, setRollbackAfterValidation, setValidationQuery, setValidationQueryTimeout, testCPDS, unwrap`

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

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

- - ### Constructor Detail

    - #### PerUserPoolDataSource

          public PerUserPoolDataSource()

      Default no-arg constructor for Serialization

  - ### Method Detail

    - #### close

          public void close()

      Close pool(s) being maintained by this datasource.
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in class `InstanceKeyDataSource`

    - #### getPerUserBlockWhenExhausted

          public boolean getPerUserBlockWhenExhausted(String key)

      Gets the user specific value for `BaseGenericObjectPool.getBlockWhenExhausted()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        `true` to block

    - #### setPerUserBlockWhenExhausted

          public void setPerUserBlockWhenExhausted(String username,
                                          Boolean value)

      Sets a user specific value for `BaseGenericObjectPool.getBlockWhenExhausted()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserEvictionPolicyClassName

          public String getPerUserEvictionPolicyClassName(String key)

      Gets the user specific value for `BaseGenericObjectPool.getEvictionPolicyClassName()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        the policy class name

    - #### setPerUserEvictionPolicyClassName

          public void setPerUserEvictionPolicyClassName(String username,
                                               String value)

      Sets a user specific value for `BaseGenericObjectPool.getEvictionPolicyClassName()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserLifo

          public boolean getPerUserLifo(String key)

      Gets the user specific value for `BaseGenericObjectPool.getLifo()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        `true` to use LIFO

    - #### setPerUserLifo

          public void setPerUserLifo(String username,
                            Boolean value)

      Sets a user specific value for `BaseGenericObjectPool.getLifo()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserMaxIdle

          public int getPerUserMaxIdle(String key)

      Gets the user specific value for `GenericObjectPool.getMaxIdle()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        the maximum idle

    - #### setPerUserMaxIdle

          public void setPerUserMaxIdle(String username,
                               Integer value)

      Sets a user specific value for `GenericObjectPool.getMaxIdle()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserMaxTotal

          public int getPerUserMaxTotal(String key)

      Gets the user specific value for `BaseGenericObjectPool.getMaxTotal()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        the maximum total

    - #### setPerUserMaxTotal

          public void setPerUserMaxTotal(String username,
                                Integer value)

      Sets a user specific value for `BaseGenericObjectPool.getMaxTotal()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserMaxWaitMillis

          public long getPerUserMaxWaitMillis(String key)

      Gets the user specific value for `BaseGenericObjectPool.getMaxWaitMillis()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        the maximum wait time

    - #### setPerUserMaxWaitMillis

          public void setPerUserMaxWaitMillis(String username,
                                     Long value)

      Sets a user specific value for `BaseGenericObjectPool.getMaxWaitMillis()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserMinEvictableIdleTimeMillis

          public long getPerUserMinEvictableIdleTimeMillis(String key)

      Gets the user specific value for `BaseGenericObjectPool.getMinEvictableIdleTimeMillis()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        the minimum idle time for eviction

    - #### setPerUserMinEvictableIdleTimeMillis

          public void setPerUserMinEvictableIdleTimeMillis(String username,
                                                  Long value)

      Sets a user specific value for `BaseGenericObjectPool.getMinEvictableIdleTimeMillis()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserMinIdle

          public int getPerUserMinIdle(String key)

      Gets the user specific value for `GenericObjectPool.getMinIdle()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        the minimum idle count

    - #### setPerUserMinIdle

          public void setPerUserMinIdle(String username,
                               Integer value)

      Sets a user specific value for `GenericObjectPool.getMinIdle()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserNumTestsPerEvictionRun

          public int getPerUserNumTestsPerEvictionRun(String key)

      Gets the user specific value for `BaseGenericObjectPool.getNumTestsPerEvictionRun()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        the tests count

    - #### setPerUserNumTestsPerEvictionRun

          public void setPerUserNumTestsPerEvictionRun(String username,
                                              Integer value)

      Sets a user specific value for `BaseGenericObjectPool.getNumTestsPerEvictionRun()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserSoftMinEvictableIdleTimeMillis

          public long getPerUserSoftMinEvictableIdleTimeMillis(String key)

      Gets the user specific value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        the soft minimum idle time for eviction

    - #### setPerUserSoftMinEvictableIdleTimeMillis

          public void setPerUserSoftMinEvictableIdleTimeMillis(String username,
                                                      Long value)

      Sets a user specific value for `BaseGenericObjectPool.getSoftMinEvictableIdleTimeMillis()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserTestOnCreate

          public boolean getPerUserTestOnCreate(String key)

      Gets the user specific value for `BaseGenericObjectPool.getTestOnCreate()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        `true` to test on create

    - #### setPerUserTestOnCreate

          public void setPerUserTestOnCreate(String username,
                                    Boolean value)

      Sets a user specific value for `BaseGenericObjectPool.getTestOnCreate()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserTestOnBorrow

          public boolean getPerUserTestOnBorrow(String key)

      Gets the user specific value for `BaseGenericObjectPool.getTestOnBorrow()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        `true` to test on borrow

    - #### setPerUserTestOnBorrow

          public void setPerUserTestOnBorrow(String username,
                                    Boolean value)

      Sets a user specific value for `BaseGenericObjectPool.getTestOnBorrow()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserTestOnReturn

          public boolean getPerUserTestOnReturn(String key)

      Gets the user specific value for `BaseGenericObjectPool.getTestOnReturn()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        `true` to test on return

    - #### setPerUserTestOnReturn

          public void setPerUserTestOnReturn(String username,
                                    Boolean value)

      Sets a user specific value for `BaseGenericObjectPool.getTestOnReturn()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserTestWhileIdle

          public boolean getPerUserTestWhileIdle(String key)

      Gets the user specific value for `BaseGenericObjectPool.getTestWhileIdle()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        `true` to test while idle

    - #### setPerUserTestWhileIdle

          public void setPerUserTestWhileIdle(String username,
                                     Boolean value)

      Sets a user specific value for `BaseGenericObjectPool.getTestWhileIdle()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserTimeBetweenEvictionRunsMillis

          public long getPerUserTimeBetweenEvictionRunsMillis(String key)

      Gets the user specific value for `BaseGenericObjectPool.getTimeBetweenEvictionRunsMillis()` for the specified user's pool or the default if no user specific value is defined.
      Parameters:
        `key` - The user
      Returns:
        time between eviction runs

    - #### setPerUserTimeBetweenEvictionRunsMillis

          public void setPerUserTimeBetweenEvictionRunsMillis(String username,
                                                     Long value)

      Sets a user specific value for `()` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserDefaultAutoCommit

          public Boolean getPerUserDefaultAutoCommit(String key)

      Gets the user specific default value for `Connection.setAutoCommit(boolean)` for the specified user's pool.
      Parameters:
        `key` - The user
      Returns:
        `true` to commit automatically

    - #### setPerUserDefaultAutoCommit

          public void setPerUserDefaultAutoCommit(String username,
                                         Boolean value)

      Sets a user specific default value for `Connection.setAutoCommit(boolean)` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserDefaultReadOnly

          public Boolean getPerUserDefaultReadOnly(String key)

      Gets the user specific default value for `Connection.setReadOnly(boolean)` for the specified user's pool.
      Parameters:
        `key` - The user
      Returns:
        `true` is read only by default

    - #### setPerUserDefaultReadOnly

          public void setPerUserDefaultReadOnly(String username,
                                       Boolean value)

      Sets a user specific default value for `Connection.setReadOnly(boolean)` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getPerUserDefaultTransactionIsolation

          public Integer getPerUserDefaultTransactionIsolation(String key)

      Gets the user specific default value for `Connection.setTransactionIsolation(int)` for the specified user's pool.
      Parameters:
        `key` - The user
      Returns:
        the default transaction isolation

    - #### setPerUserDefaultTransactionIsolation

          public void setPerUserDefaultTransactionIsolation(String username,
                                                   Integer value)

      Sets a user specific default value for `Connection.setTransactionIsolation(int)` for the specified user's pool.
      Parameters:
        `username` - The user
        `value` - The value

    - #### getNumActive

          public int getNumActive()

      Returns:
        the number of active connections in the default pool.

    - #### getNumActive

          public int getNumActive(String username)

      Parameters:
        `username` - The user
      Returns:
        the number of active connections in the pool for a given user.

    - #### getNumIdle

          public int getNumIdle()

      Returns:
        the number of idle connections in the default pool.

    - #### getNumIdle

          public int getNumIdle(String username)

      Parameters:
        `username` - The user
      Returns:
        the number of idle connections in the pool for a given user.

    - #### getPooledConnectionAndInfo

          protected org.apache.tomcat.dbcp.dbcp2.datasources.PooledConnectionAndInfo getPooledConnectionAndInfo(String username,
                                                                                                    String password)
                                                                                                         throws SQLException

      Specified by:
        `getPooledConnectionAndInfo` in class `InstanceKeyDataSource`
      Throws:
        `SQLException`

    - #### setupDefaults

          protected void setupDefaults(Connection con,
                           String username)
                                throws SQLException

      Specified by:
        `setupDefaults` in class `InstanceKeyDataSource`
      Throws:
        `SQLException`

    - #### getConnectionManager

          protected org.apache.tomcat.dbcp.dbcp2.datasources.PooledConnectionManager getConnectionManager(org.apache.tomcat.dbcp.dbcp2.datasources.UserPassKey upkey)

      Specified by:
        `getConnectionManager` in class `InstanceKeyDataSource`

    - #### getReference

          public Reference getReference()
                                 throws NamingException

      Returns:
        a `PerUserPoolDataSource` `Reference`.
      Throws:
        `NamingException` - Should not happen

Copyright © 2000-2017 Apache Software Foundation. All Rights Reserved.