org.apache.tomcat.dbcp.dbcp.datasources

## Class PerUserPoolDataSource

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

- All Implemented Interfaces:
    java.io.Serializable, java.sql.Wrapper, javax.naming.Referenceable, javax.sql.CommonDataSource, javax.sql.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.

  Author:
    John D. McNally
  See Also:
    Serialized Form

- - ### Field Summary

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

      `instanceKey, 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.dbcp.datasources.PooledConnectionManager` | `getConnectionManager(org.apache.tomcat.dbcp.dbcp.datasources.UserPassKey upkey)`
    `int` | `getDefaultMaxActive()` The maximum number of active connections that can be allocated from this pool at the same time, or non-positive for no limit.
    `int` | `getDefaultMaxIdle()` The maximum number of active connections that can remain idle in the pool, without extra ones being released, or negative for no limit.
    `int` | `getDefaultMaxWait()` The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely.
    `int` | `getNumActive()` Get the number of active connections in the default pool.
    `int` | `getNumActive(java.lang.String username, java.lang.String password)` Get the number of active connections in the pool for a given user.
    `int` | `getNumIdle()` Get the number of idle connections in the default pool.
    `int` | `getNumIdle(java.lang.String username, java.lang.String password)` Get the number of idle connections in the pool for a given user.
    `java.lang.Boolean` | `getPerUserDefaultAutoCommit(java.lang.String key)` The keys are usernames and the value is the --.
    `java.lang.Boolean` | `getPerUserDefaultReadOnly(java.lang.String username)` The keys are usernames and the value is the --.
    `java.lang.Integer` | `getPerUserDefaultTransactionIsolation(java.lang.String username)` The isolation level of connections when returned from getConnection.
    `java.lang.Integer` | `getPerUserMaxActive(java.lang.String username)` The maximum number of active connections that can be allocated from this pool at the same time, or non-positive for no limit.
    `java.lang.Integer` | `getPerUserMaxIdle(java.lang.String username)` The maximum number of active connections that can remain idle in the pool, without extra ones being released, or negative for no limit.
    `java.lang.Integer` | `getPerUserMaxWait(java.lang.String username)` The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely.
    `protected org.apache.tomcat.dbcp.dbcp.datasources.PooledConnectionAndInfo` | `getPooledConnectionAndInfo(java.lang.String username, java.lang.String password)`
    `javax.naming.Reference` | `getReference()` Returns a `PerUserPoolDataSource` `Reference`.
    `void` | `setDefaultMaxActive(int maxActive)` The maximum number of active connections that can be allocated from this pool at the same time, or non-positive for no limit.
    `void` | `setDefaultMaxIdle(int defaultMaxIdle)` The maximum number of active connections that can remain idle in the pool, without extra ones being released, or negative for no limit.
    `void` | `setDefaultMaxWait(int defaultMaxWait)` The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely.
    `void` | `setPerUserDefaultAutoCommit(java.lang.String username, java.lang.Boolean value)` The keys are usernames and the value is the --.
    `void` | `setPerUserDefaultReadOnly(java.lang.String username, java.lang.Boolean value)` The keys are usernames and the value is the --.
    `void` | `setPerUserDefaultTransactionIsolation(java.lang.String username, java.lang.Integer value)` The isolation level of connections when returned from getConnection.
    `void` | `setPerUserMaxActive(java.lang.String username, java.lang.Integer value)` The maximum number of active connections that can be allocated from this pool at the same time, or non-positive for no limit.
    `void` | `setPerUserMaxIdle(java.lang.String username, java.lang.Integer value)` The maximum number of active connections that can remain idle in the pool, without extra ones being released, or negative for no limit.
    `void` | `setPerUserMaxWait(java.lang.String username, java.lang.Integer value)` The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely.
    `protected void` | `setupDefaults(java.sql.Connection con, java.lang.String username)`

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

      `assertInitializationAllowed, getConnection, getConnection, getConnectionPoolDataSource, getDataSourceName, getDefaultTransactionIsolation, getDescription, getJndiEnvironment, getLoginTimeout, getLogWriter, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getParentLogger, getTestOnBorrow, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRunsMillis, getValidationQuery, isDefaultAutoCommit, isDefaultReadOnly, isRollbackAfterValidation, isTestOnBorrow, isTestOnReturn, isTestWhileIdle, isWrapperFor, setConnectionPoolDataSource, setDataSourceName, setDefaultAutoCommit, setDefaultReadOnly, setDefaultTransactionIsolation, setDescription, setJndiEnvironment, setLoginTimeout, setLogWriter, setMinEvictableIdleTimeMillis, setNumTestsPerEvictionRun, setRollbackAfterValidation, setTestOnBorrow, setTestOnReturn, setTestWhileIdle, setTimeBetweenEvictionRunsMillis, setValidationQuery, testCPDS, unwrap, whenExhaustedAction`

    - ### 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 class `InstanceKeyDataSource`

    - #### getDefaultMaxActive

          public int getDefaultMaxActive()

      The maximum number of active connections that can be allocated from this pool at the same time, or non-positive for no limit. This value is used for any username which is not specified in perUserMaxConnections.

    - #### setDefaultMaxActive

          public void setDefaultMaxActive(int maxActive)

      The maximum number of active connections that can be allocated from this pool at the same time, or non-positive for no limit. This value is used for any username which is not specified in perUserMaxConnections. The default is 8.

    - #### getDefaultMaxIdle

          public int getDefaultMaxIdle()

      The maximum number of active connections that can remain idle in the pool, without extra ones being released, or negative for no limit. This value is used for any username which is not specified in perUserMaxIdle.

    - #### setDefaultMaxIdle

          public void setDefaultMaxIdle(int defaultMaxIdle)

      The maximum number of active connections that can remain idle in the pool, without extra ones being released, or negative for no limit. This value is used for any username which is not specified in perUserMaxIdle. The default is 8.

    - #### getDefaultMaxWait

          public int getDefaultMaxWait()

      The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely. Will fail immediately if value is 0. This value is used for any username which is not specified in perUserMaxWait. The default is -1.

    - #### setDefaultMaxWait

          public void setDefaultMaxWait(int defaultMaxWait)

      The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely. Will fail immediately if value is 0. This value is used for any username which is not specified in perUserMaxWait. The default is -1.

    - #### getPerUserDefaultAutoCommit

          public java.lang.Boolean getPerUserDefaultAutoCommit(java.lang.String key)

      The keys are usernames and the value is the --. Any username specified here will override the value of defaultAutoCommit.

    - #### setPerUserDefaultAutoCommit

          public void setPerUserDefaultAutoCommit(java.lang.String username,
                                         java.lang.Boolean value)

      The keys are usernames and the value is the --. Any username specified here will override the value of defaultAutoCommit.

    - #### getPerUserDefaultTransactionIsolation

          public java.lang.Integer getPerUserDefaultTransactionIsolation(java.lang.String username)

      The isolation level of connections when returned from getConnection. If null, the username will use the value of defaultTransactionIsolation.

    - #### setPerUserDefaultTransactionIsolation

          public void setPerUserDefaultTransactionIsolation(java.lang.String username,
                                                   java.lang.Integer value)

      The isolation level of connections when returned from getConnection. Valid values are the constants defined in Connection.

    - #### getPerUserMaxActive

          public java.lang.Integer getPerUserMaxActive(java.lang.String username)

      The maximum number of active connections that can be allocated from this pool at the same time, or non-positive for no limit. The keys are usernames and the value is the maximum connections. Any username specified here will override the value of defaultMaxActive.

    - #### setPerUserMaxActive

          public void setPerUserMaxActive(java.lang.String username,
                                 java.lang.Integer value)

      The maximum number of active connections that can be allocated from this pool at the same time, or non-positive for no limit. The keys are usernames and the value is the maximum connections. Any username specified here will override the value of defaultMaxActive.

    - #### getPerUserMaxIdle

          public java.lang.Integer getPerUserMaxIdle(java.lang.String username)

      The maximum number of active connections that can remain idle in the pool, without extra ones being released, or negative for no limit. The keys are usernames and the value is the maximum connections. Any username specified here will override the value of defaultMaxIdle.

    - #### setPerUserMaxIdle

          public void setPerUserMaxIdle(java.lang.String username,
                               java.lang.Integer value)

      The maximum number of active connections that can remain idle in the pool, without extra ones being released, or negative for no limit. The keys are usernames and the value is the maximum connections. Any username specified here will override the value of defaultMaxIdle.

    - #### getPerUserMaxWait

          public java.lang.Integer getPerUserMaxWait(java.lang.String username)

      The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely. Will fail immediately if value is 0. The keys are usernames and the value is the maximum connections. Any username specified here will override the value of defaultMaxWait.

    - #### setPerUserMaxWait

          public void setPerUserMaxWait(java.lang.String username,
                               java.lang.Integer value)

      The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely. Will fail immediately if value is 0. The keys are usernames and the value is the maximum connections. Any username specified here will override the value of defaultMaxWait.

    - #### getPerUserDefaultReadOnly

          public java.lang.Boolean getPerUserDefaultReadOnly(java.lang.String username)

      The keys are usernames and the value is the --. Any username specified here will override the value of defaultReadOnly.

    - #### setPerUserDefaultReadOnly

          public void setPerUserDefaultReadOnly(java.lang.String username,
                                       java.lang.Boolean value)

      The keys are usernames and the value is the --. Any username specified here will override the value of defaultReadOnly.

    - #### getNumActive

          public int getNumActive()

      Get the number of active connections in the default pool.

    - #### getNumActive

          public int getNumActive(java.lang.String username,
                         java.lang.String password)

      Get the number of active connections in the pool for a given user.

    - #### getNumIdle

          public int getNumIdle()

      Get the number of idle connections in the default pool.

    - #### getNumIdle

          public int getNumIdle(java.lang.String username,
                       java.lang.String password)

      Get the number of idle connections in the pool for a given user.

    - #### getPooledConnectionAndInfo

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

      Specified by:
        `getPooledConnectionAndInfo` in class `InstanceKeyDataSource`
      Throws:
        `java.sql.SQLException`

    - #### setupDefaults

          protected void setupDefaults(java.sql.Connection con,
                           java.lang.String username)
                                throws java.sql.SQLException

      Specified by:
        `setupDefaults` in class `InstanceKeyDataSource`
      Throws:
        `java.sql.SQLException`

    - #### getConnectionManager

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

      Specified by:
        `getConnectionManager` in class `InstanceKeyDataSource`

    - #### getReference

          public javax.naming.Reference getReference()
                                              throws javax.naming.NamingException

      Returns a `PerUserPoolDataSource` `Reference`.
      Specified by:
        `getReference` in interface `javax.naming.Referenceable`
      Overrides:
        `getReference` in class `InstanceKeyDataSource`
      Returns:
        The non-null Reference of this object.
      Throws:
        `javax.naming.NamingException` - If a naming exception was encountered while retrieving the reference.
      Since:
        1.2.2

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