Class 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 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 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. one that has lost connection to the server).
      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. one that has lost connection to the server).
      • 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.

      • 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:
        setIdleTimeout(int), setMinIdle(int), getPurgeInterval(), getIdleTimeout(), 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:
        setPurgeInterval(int), setIdleTimeout(int), setMinIdle(int), getPurgeInterval(), 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:
        setPurgeInterval(int), setIdleTimeout(int), setMinIdle(int), getPurgeInterval(), 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:
        setPurgeInterval(int), setIdleTimeout(int), getMinIdle(), getPurgeInterval(), 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