com.tietoenator.trip.jxp.pool

## Class TdbConnectionPool

- java.lang.Object
- - com.tietoenator.trip.jxp.pool.TdbConnectionPool

- Direct Known Subclasses:
    TdbTripNetConnectionPool, TdbWebConnectionPool

      public abstract class TdbConnectionPool
      extends java.lang.Object

  Basic session pooling class, allowing multiple uses of the same session by recycling sessions when the logout() method is called, rather than releasing them.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `INFINITE_TIMEOUT` Value to pass to `acquire` in order to block indefinitly waiting for a session to become available.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `TdbPooledSession` | `acquire()` Acquire a session from the pool -- the first time a session is acquired, it will incur the cost of a full login to the server.
    `TdbPooledSession` | `acquire(long timeout)` Acquire a session from the pool -- the first time a session is acquired, it will incur the cost of a full login to the server.
    `void` | `close()` Shuts down the session pool.
    `TdbActivityLogger` | `getActivityLog()` Retrieve a reference to the activity logger currently in use
    `int` | `getIdleTimeout()` Get/set number of seconds a session can remain idle in the pool without being removed by the purge routine.
    `boolean` | `getIsolateSessions()` Check if sessions in the pool are to be isolated.
    `int` | `getLimit()` Returns the limit for the number of sessions that can be maintained by this session pool.
    `int` | `getMinIdle()` Get the minimum number of idle sessions that should remain in the pool after a purge.
    `TdbPoolInitializer` | `getPoolInitializer()` Returns the current pool initialization procedure for sessions in the pool.
    `int` | `getPurgeInterval()` Get the purge interval.
    `int` | `getRestoreDelay()` Get the number of milliseconds to wait between session attempts to re-establish a broken session.
    `int` | `getRestoreRetries()` Get the max number of retries for re-establising a broken session (e.g.
    `int` | `getSize()` Returns the current size of the pool.
    `boolean` | `isClosed()` Returns true if this connection pool has been closed.
    `void` | `reserve(int reserve)` Establish a reserve of sessions within the pool.
    `void` | `setActivityLog(TdbActivityLogger logger)` Set the activity logger reference for this pool.
    `void` | `setIdleTimeout(int idleTimeout)` Set the number of seconds a session can remain idle in the pool without being removed by the purge routine.
    `void` | `setIsolateSessions(boolean isolate)` Determine if sessions in the pool are to be isolated.
    `void` | `setLimit(int newLimit)` Set a limit to the number of sessions that can be maintained by this session pool.
    `void` | `setMinIdle(int minIdle)` Set the minimum number of idle sessions that should remain in the pool after a purge.
    `void` | `setPoolInitializer(TdbPoolInitializer initproc)` Assigns a pool initialization procedure for sessions in the pool.
    `void` | `setPurgeInterval(int purgeInterval)` Set the purge interval.
    `void` | `setRestoreDelay(int delay)` Set the number of milliseconds to wait between session attempts to re-establish a broken session.
    `void` | `setRestoreRetries(int retries)` Set the max number of retries for re-establising a broken session (e.g.

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

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

- - ### Field Detail

    - #### INFINITE_TIMEOUT

          public static final long INFINITE_TIMEOUT

      Value to pass to `acquire` in order to block indefinitly waiting for a session to become available.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### acquire

          public TdbPooledSession acquire()
                                   throws TdbException

      Acquire a session from the pool -- the first time a session is acquired, it will incur the cost of a full login to the server. If a size limit has been set for this pool, this method will throw a TdbException with the `code` set to `UNUSABLE_SESSION` if there are no available idle sessions to return.
      Returns:
        A session, or null if no session could be acquired.
      Throws:
        `TdbException` - If the pool is closed or a failure occurred reserve a session.

    - #### acquire

          public TdbPooledSession acquire(long timeout)
                                   throws TdbException

      Acquire a session from the pool -- the first time a session is acquired, it will incur the cost of a full login to the server. If a size limit has been set for this pool, this method will throw a TdbException with the `code` set to `UNUSABLE_SESSION` if there are no available idle sessions to return.
      Parameters:
        `timeout` - Timeout in milliseconds, or use `INFINITE_TIMEOUT` to wait indefinitely.
      Returns:
        A session, or null if no session could be acquired before timeout.
      Throws:
        `TdbException` - If the pool is closed or a failure occurred reserve a session.

    - #### reserve

          public void reserve(int reserve)
                       throws TdbException

      Establish a reserve of sessions within the pool. This can be called at any time, not just during application initialization. Note that new sessions can't be handed out by the acquire() method while this method is running, however, so applications should take care to call this method only during idle time.
      Parameters:
        `reserve` - Number of sessions to establish
      Throws:
        `TdbException`

    - #### close

          public void close()

      Shuts down the session pool.

      Available sessions in the pool will be closed by this method. Any sessions still in use by the application are allowed to remain so, but will be closed upon their return to the pool. The application is responsible for returning sessions to the closed pool as soon as possible after calling this method.

    - #### isClosed

          public boolean isClosed()

      Returns true if this connection pool has been closed.

      A closed connection pool will not yield any sessions on calls to its Acquire() method. Any sessions still in use must be returned to the pool as soon as possible.

      Returns:
        False if the pool is active and true if it has been closed.

    - #### setPoolInitializer

          public void setPoolInitializer(TdbPoolInitializer initproc)

      Assigns a pool initialization procedure for sessions in the pool. The usage of a pool initializer turns a connection pool into a session pool. The difference is that in a session pool, the pool initializer opens databases to be used, sets up views, defines, etc. All things that need to done one time and does not have to be repeated for ever single request. This results in greater performance for the application using the pool.
      Parameters:
        `initproc` - Instance of class that implements the TdbPoolInitializer interface.

    - #### getPoolInitializer

          public TdbPoolInitializer getPoolInitializer()

      Returns the current pool initialization procedure for sessions in the pool.
      Returns:
        Instance of class that implements the TdbPoolInitializer interface.

    - #### setLimit

          public void setLimit(int newLimit)

      Set a limit to the number of sessions that can be maintained by this session pool.
      Parameters:
        `newLimit` - The new limit (pass 0 to remove the limit)

    - #### getLimit

          public int getLimit()

      Returns the limit for the number of sessions that can be maintained by this session pool.
      Returns:
        The current limit, or 0 (zero) if no limit exists.

    - #### getSize

          public int getSize()

      Returns the current size of the pool.
      Returns:
        Pool size, includes idle as well as acquired sessions.

    - #### getRestoreRetries

          public int getRestoreRetries()

      Get the max number of retries for re-establising a broken session (e.g. one that has lost connection to the server). Default is 10.

    - #### setRestoreRetries

          public void setRestoreRetries(int retries)

      Set the max number of retries for re-establising a broken session (e.g. one that has lost connection to the server). Default is 10.

    - #### getRestoreDelay

          public int getRestoreDelay()

      Get the number of milliseconds to wait between session attempts to re-establish a broken session. Default is 500 milliseconds. This delay will only be used if the session cannot be re-established on one attempt and further re-tries must be used.

    - #### setRestoreDelay

          public void setRestoreDelay(int delay)

      Set the number of milliseconds to wait between session attempts to re-establish a broken session. Default is 500 milliseconds. This delay will only be used if the session cannot be re-established on one attempt and further re-tries must be used.

    - #### getIsolateSessions

          public boolean getIsolateSessions()

      Check if sessions in the pool are to be isolated. Isolation means that the actions in an acquired session (search sets, etc) do not affect the session when it is acquired the next time. The default value of this property is true. This means that anything that the application does in an acquired session is totally isolated from the next time it is acquired. Any search sets created are automatically deleted when the session is restored to the pool.

      NOTE: When this property is false, the use of any other means than the TdbRecordSet class to search and retrieve (e.g. via the TdbCclCommand class) is NOT RECOMMENDED.

    - #### setIsolateSessions

          public void setIsolateSessions(boolean isolate)

      Determine if sessions in the pool are to be isolated. Isolation means that the actions in an acquired session (search sets, etc) do not affect the session when it is acquired the next time.

      The default value of this property is true. This means that anything that the application does in an acquired session is totally isolated from the next time it is acquired. Any search sets created are automatically deleted when the session is restored to the pool.

      Setting this property to false will reduce the number of network transactions by two, which will have a positive performance impact in high-load scenarios.

      NOTE: Setting this property to false is only recommended if the TdbRecordSet class is used to search and retrieve, and no other TRIPjxp functionality is used. When using the TdbRecordSet class there will still be a session isolation in effect, because the implementation of the record set on the server-side contains its own isolation mechanism. The use of any other means to search (e.g. via the TdbCclCommand) is NOT RECOMMENDED if this property is false.

    - #### getPurgeInterval

          public int getPurgeInterval()

      Get the purge interval. This is the number of seconds between attempts to purge idle sessions.
      Returns:
        Purge interval in seconds.
      See Also:
        `TdbConnectionPool.setPurgeInterval(int)`, `TdbConnectionPool.setIdleTimeout(int)`, `TdbConnectionPool.setMinIdle(int)`, `TdbConnectionPool.getIdleTimeout()`, `TdbConnectionPool.getMinIdle()`

    - #### setPurgeInterval

          public void setPurgeInterval(int purgeInterval)

      Set the purge interval. This is the number of seconds between attempts to purge idle sessions.

      By default, purging of idle sessions is disabled. To enable it, both this property and the IdleTimeout property must be set to positive values.

      By default, the purge interval is 0 (zero), which means that purging is disabled. Recommended minimum interval for purging is 30 seconds.

      Parameters:
        `purgeInterval` - Interval in seconds for the purge routine to run.
      See Also:
        `TdbConnectionPool.setIdleTimeout(int)`, `TdbConnectionPool.setMinIdle(int)`, `TdbConnectionPool.getPurgeInterval()`, `TdbConnectionPool.getIdleTimeout()`, `TdbConnectionPool.getMinIdle()`

    - #### getIdleTimeout

          public int getIdleTimeout()

      Get/set number of seconds a session can remain idle in the pool without being removed by the purge routine.

      By default, purging of idle sessions is disabled. To enable it, both this property and the IdleTimeout property must be set to positive values.

      Returns:
        The timeout in seconds for idle sessions in this pool.
      See Also:
        `TdbConnectionPool.setPurgeInterval(int)`, `TdbConnectionPool.setIdleTimeout(int)`, `TdbConnectionPool.setMinIdle(int)`, `TdbConnectionPool.getPurgeInterval()`, `TdbConnectionPool.getMinIdle()`

    - #### setIdleTimeout

          public void setIdleTimeout(int idleTimeout)

      Set the number of seconds a session can remain idle in the pool without being removed by the purge routine.
      Parameters:
        `idleTimeout` - New timeout in seconds for idle sessions in this pool.
      See Also:
        `TdbConnectionPool.setPurgeInterval(int)`, `TdbConnectionPool.setMinIdle(int)`, `TdbConnectionPool.getPurgeInterval()`, `TdbConnectionPool.getIdleTimeout()`, `TdbConnectionPool.getMinIdle()`

    - #### getMinIdle

          public int getMinIdle()

      Get the minimum number of idle sessions that should remain in the pool after a purge.

      This property is used when purging idle sessions. The purge will allow up to MinIdle sessions to remain idle in the pool, even if they otherwise would be candidates for removal.

      Returns:
        The minimum number of idle sessions that should remain in the pool after a purge.
      See Also:
        `TdbConnectionPool.setPurgeInterval(int)`, `TdbConnectionPool.setIdleTimeout(int)`, `TdbConnectionPool.setMinIdle(int)`, `TdbConnectionPool.getPurgeInterval()`, `TdbConnectionPool.getIdleTimeout()`

    - #### setMinIdle

          public void setMinIdle(int minIdle)

      Set the minimum number of idle sessions that should remain in the pool after a purge.

      This property is used when purging idle sessions. The purge will allow up to MinIdle sessions to remain idle in the pool, even if they otherwise would be candidates for removal.

      Parameters:
        `minIdle` - The minimum number of idle sessions that should remain in the pool after a purge.
      See Also:
        `TdbConnectionPool.setPurgeInterval(int)`, `TdbConnectionPool.setIdleTimeout(int)`, `TdbConnectionPool.getMinIdle()`, `TdbConnectionPool.getPurgeInterval()`, `TdbConnectionPool.getIdleTimeout()`

    - #### getActivityLog

          public TdbActivityLogger getActivityLog()

      Retrieve a reference to the activity logger currently in use
      Returns:
        The logger instance in use

    - #### setActivityLog

          public void setActivityLog(TdbActivityLogger logger)

      Set the activity logger reference for this pool.

      Note that logging in a pool can be expensive from a performance point of view. However, it is useful for diagnosis of pool usage and size.

      Parameters:
        `logger` - The activity logger to use; set this to null to remove any pre-existing logger