org.apache.cayenne.conn

## Class PoolManager

- java.lang.Object
- - org.apache.cayenne.conn.PoolManager

- All Implemented Interfaces:
    Wrapper, EventListener, CommonDataSource, ConnectionEventListener, DataSource, ScopeEventListener

      public class PoolManager
      extends Object
      implements ScopeEventListener, DataSource, ConnectionEventListener

  PoolManager is a Cayenne implementation of a pooling DataSource.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected String` | `dataSourceUrl`
    `protected String` | `jdbcDriver`
    `static int` | `MAX_QUEUE_WAIT` Defines a maximum time in milliseconds that a connection request could wait in the connection queue.
    `protected int` | `maxConnections`
    `protected int` | `minConnections`
    `protected String` | `password`
    `protected ConnectionPoolDataSource` | `poolDataSource`
    `protected List<PooledConnection>` | `unusedPool`
    `protected List<PooledConnection>` | `usedPool`
    `protected String` | `userName`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PoolManager(ConnectionPoolDataSource poolDataSource, int minCons, int maxCons, String userName, String password)` Creates new PoolManager with the specified policy for connection pooling and a ConnectionPoolDataSource object.
    `PoolManager(String jdbcDriver, String dataSourceUrl, int minCons, int maxCons, String userName, String password)` Creates new PoolManager using org.apache.cayenne.conn.PoolDataSource for an underlying ConnectionPoolDataSource.
    `PoolManager(String jdbcDriver, String dataSourceUrl, int minCons, int maxCons, String userName, String password, JdbcEventLogger logger)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `beforeScopeEnd()` An implementation of `ScopeEventListener` that simply calls `shutdown()`.
    `protected boolean` | `canGrowPool()`
    `void` | `connectionClosed(ConnectionEvent event)` Returns closed connection to the pool.
    `void` | `connectionErrorOccurred(ConnectionEvent event)` Removes connection with an error from the pool.
    `void` | `dispose()` Deprecated. since 3.1 replaced with `shutdown()` method for naming consistency.
    `protected void` | `disposeOfMaintenanceThread()`
    `Connection` | `getConnection()` Returns connection from the pool using internal values of user name and password.
    `Connection` | `getConnection(String userName, String password)` Returns connection from the pool.
    `int` | `getCurrentlyInUse()` Returns the number of connections obtained via this DataSource that are currently in use by the DataSource clients.
    `int` | `getCurrentlyUnused()` Returns the number of connections maintained in the pool that are currently not used by any clients and are available immediately via `getConnection` method.
    `String` | `getDataSourceUrl()` Returns a database URL used to initialize this pool.
    `String` | `getJdbcDriver()` Returns a name of a JDBC driver used to initialize this pool.
    `int` | `getLoginTimeout()`
    `PrintWriter` | `getLogWriter()`
    `int` | `getMaxConnections()` Returns maximum number of connections this pool can keep.
    `int` | `getMinConnections()` Returns the absolute minimum number of connections allowed in this pool at any moment in time.
    `Logger` | `getParentLogger()`
    `String` | `getPassword()` Returns a data source password used to initialize this pool.
    `int` | `getPoolSize()` Returns current number of connections.
    `String` | `getUserName()` Returns a data source user name used to initialize this pool.
    `protected int` | `growPool(int addConnections, String userName, String password)` Increases connection pool by the specified number of connections.
    `protected void` | `init(ConnectionPoolDataSource poolDataSource, int minCons, int maxCons, String userName, String password)` Initializes pool.
    `boolean` | `isWrapperFor(Class<?> iface)`
    `protected PooledConnection` | `newPooledConnection(String userName, String password)` Creates and returns new PooledConnection object, adding itself as a listener for connection events.
    `void` | `setLoginTimeout(int seconds)`
    `void` | `setLogWriter(PrintWriter out)`
    `void` | `setMaxConnections(int maxConnections)`
    `void` | `setMinConnections(int minConnections)`
    `protected void` | `shrinkPool(int closeConnections)`
    `void` | `shutdown()` Closes all existing connections, drains the pool and stops the maintenance thread.
    `protected void` | `startMaintenanceThread()`
    `<T> T` | `unwrap(Class<T> iface)`

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

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

- - ### Field Detail

    - #### MAX_QUEUE_WAIT

          public static final int MAX_QUEUE_WAIT

      Defines a maximum time in milliseconds that a connection request could wait in the connection queue. After this period expires, an exception will be thrown in the calling method. In the future this parameter should be made configurable.
      See Also:
        Constant Field Values

    - #### poolDataSource

          protected ConnectionPoolDataSource poolDataSource

    - #### minConnections

          protected int minConnections

    - #### maxConnections

          protected int maxConnections

    - #### dataSourceUrl

          protected String dataSourceUrl

    - #### jdbcDriver

          protected String jdbcDriver

    - #### password

          protected String password

    - #### userName

          protected String userName

    - #### unusedPool

          protected List<PooledConnection> unusedPool

    - #### usedPool

          protected List<PooledConnection> usedPool

  - ### Constructor Detail

    - #### PoolManager

          public PoolManager(String jdbcDriver,
                             String dataSourceUrl,
                             int minCons,
                             int maxCons,
                             String userName,
                             String password)
                      throws SQLException

      Creates new PoolManager using org.apache.cayenne.conn.PoolDataSource for an underlying ConnectionPoolDataSource.
      Throws:
        `SQLException`

    - #### PoolManager

          public PoolManager(String jdbcDriver,
                             String dataSourceUrl,
                             int minCons,
                             int maxCons,
                             String userName,
                             String password,
                             JdbcEventLogger logger)
                      throws SQLException

      Throws:
        `SQLException`

    - #### PoolManager

          public PoolManager(ConnectionPoolDataSource poolDataSource,
                             int minCons,
                             int maxCons,
                             String userName,
                             String password)
                      throws SQLException

      Creates new PoolManager with the specified policy for connection pooling and a ConnectionPoolDataSource object.
      Parameters:
        `poolDataSource` - data source for pooled connections
        `minCons` - Non-negative integer that specifies a minimum number of open connections to keep in the pool at all times
        `maxCons` - Non-negative integer that specifies maximum number of simultaneuosly open connections
      Throws:
        `SQLException` - if pool manager can not be created.

  - ### Method Detail

    - #### init

          protected void init(ConnectionPoolDataSource poolDataSource,
                              int minCons,
                              int maxCons,
                              String userName,
                              String password)
                       throws SQLException

      Initializes pool. Normally called from constructor.
      Throws:
        `SQLException`

    - #### startMaintenanceThread

          protected void startMaintenanceThread()

    - #### newPooledConnection

          protected PooledConnection newPooledConnection(String userName,
                                                         String password)
                                                  throws SQLException

      Creates and returns new PooledConnection object, adding itself as a listener for connection events.
      Throws:
        `SQLException`

    - #### dispose

          @Deprecated
          public void dispose()
                                    throws SQLException

      Deprecated. since 3.1 replaced with `shutdown()` method for naming consistency.
      Closes all existing connections, removes them from the pool.
      Throws:
        `SQLException`

    - #### shutdown

          public void shutdown()
                        throws SQLException

      Closes all existing connections, drains the pool and stops the maintenance thread.
      Throws:
        `SQLException`
      Since:
        3.1

    - #### beforeScopeEnd

          public void beforeScopeEnd()

      An implementation of `ScopeEventListener` that simply calls `shutdown()`.
      Specified by:
        `beforeScopeEnd` in interface `ScopeEventListener`
      Since:
        3.1

    - #### disposeOfMaintenanceThread

          protected void disposeOfMaintenanceThread()

    - #### canGrowPool

          protected boolean canGrowPool()

      Returns:
        true if at least one more connection can be added to the pool.

    - #### growPool

          protected int growPool(int addConnections,
                                 String userName,
                                 String password)
                          throws SQLException

      Increases connection pool by the specified number of connections.
      Returns:
        the actual number of created connections.
      Throws:
        `SQLException` - if an error happens when creating a new connection.

    - #### shrinkPool

          protected void shrinkPool(int closeConnections)

    - #### getMaxConnections

          public int getMaxConnections()

      Returns maximum number of connections this pool can keep. This parameter when configured allows to limit the number of simultaneously open connections.

    - #### setMaxConnections

          public void setMaxConnections(int maxConnections)

    - #### getMinConnections

          public int getMinConnections()

      Returns the absolute minimum number of connections allowed in this pool at any moment in time.

    - #### setMinConnections

          public void setMinConnections(int minConnections)

    - #### getDataSourceUrl

          public String getDataSourceUrl()

      Returns a database URL used to initialize this pool. Will return null if the pool was initialized with ConnectionPoolDataSource.

    - #### getJdbcDriver

          public String getJdbcDriver()

      Returns a name of a JDBC driver used to initialize this pool. Will return null if the pool was initialized with ConnectionPoolDataSource.

    - #### getPassword

          public String getPassword()

      Returns a data source password used to initialize this pool.

    - #### getUserName

          public String getUserName()

      Returns a data source user name used to initialize this pool.

    - #### getPoolSize

          public int getPoolSize()

      Returns current number of connections.

    - #### getCurrentlyInUse

          public int getCurrentlyInUse()

      Returns the number of connections obtained via this DataSource that are currently in use by the DataSource clients.

    - #### getCurrentlyUnused

          public int getCurrentlyUnused()

      Returns the number of connections maintained in the pool that are currently not used by any clients and are available immediately via `getConnection` method.

    - #### getConnection

          public Connection getConnection()
                                   throws SQLException

      Returns connection from the pool using internal values of user name and password. Equivalent to calling:

      `ds.getConnection(ds.getUserName(), ds.getPassword())`

      Specified by:
        `getConnection` in interface `DataSource`
      Throws:
        `SQLException`

    - #### getConnection

          public Connection getConnection(String userName,
                                          String password)
                                   throws SQLException

      Returns connection from the pool.
      Specified by:
        `getConnection` in interface `DataSource`
      Throws:
        `SQLException`

    - #### getLoginTimeout

          public int getLoginTimeout()
                              throws SQLException

      Specified by:
        `getLoginTimeout` in interface `CommonDataSource`
      Throws:
        `SQLException`

    - #### setLoginTimeout

          public void setLoginTimeout(int seconds)
                               throws SQLException

      Specified by:
        `setLoginTimeout` in interface `CommonDataSource`
      Throws:
        `SQLException`

    - #### getLogWriter

          public PrintWriter getLogWriter()
                                   throws SQLException

      Specified by:
        `getLogWriter` in interface `CommonDataSource`
      Throws:
        `SQLException`

    - #### setLogWriter

          public void setLogWriter(PrintWriter out)
                            throws SQLException

      Specified by:
        `setLogWriter` in interface `CommonDataSource`
      Throws:
        `SQLException`

    - #### connectionClosed

          public void connectionClosed(ConnectionEvent event)

      Returns closed connection to the pool.
      Specified by:
        `connectionClosed` in interface `ConnectionEventListener`

    - #### connectionErrorOccurred

          public void connectionErrorOccurred(ConnectionEvent event)

      Removes connection with an error from the pool. This method is called by PoolManager connections on connection errors to notify PoolManager that connection is in invalid state.
      Specified by:
        `connectionErrorOccurred` in interface `ConnectionEventListener`

    - #### isWrapperFor

          public boolean isWrapperFor(Class<?> iface)
                               throws SQLException

      Specified by:
        `isWrapperFor` in interface `Wrapper`
      Throws:
        `SQLException`
      Since:
        3.0

    - #### unwrap

          public <T> T unwrap(Class<T> iface)
                       throws SQLException

      Specified by:
        `unwrap` in interface `Wrapper`
      Throws:
        `SQLException`
      Since:
        3.0

    - #### getParentLogger

          public Logger getParentLogger()
                                 throws SQLFeatureNotSupportedException

      Specified by:
        `getParentLogger` in interface `CommonDataSource`
      Throws:
        `SQLFeatureNotSupportedException`
      Since:
        3.1 JDBC 4.1 compatibility under Java 1.5

Copyright © 2001–2018 Apache Cayenne. All rights reserved.