Package org.apache.manifoldcf.connectorcommon.interfaces

Interface IConnectionThrottler

  • All Known Implementing Classes:
    Throttler.ConnectionThrottler
    public interface IConnectionThrottler
    An IConnectionThrottler object is not thread-local. It gates connection creation and pool management. The underlying model is a pool of connections. A connection gets pulled off the pool and used to perform a fetch. If there are insufficient connections in the pool, and there is sufficient capacity to create a new connection, a connection will be created instead. When the fetch is done, the connection is returned, and then there is a decision whether or not to put the connection back into the pool, or to destroy it. Finally, the pool is periodically evaluated, and connections may be destroyed if either they have expired, or the allocated connections are still over capacity. This object does not in itself contain a connection pool - but it is intended to assist in the management of that pool. Specifically, it tracks connections that are in the pool, and connections that are handed out for use, and performs ALL the waiting needed due to the pool being empty and/or the number of active connections being at or over the quota.

    • Field Detail

      • CONNECTION_FROM_POOL

        static final int CONNECTION_FROM_POOL
        Get the connection from the pool
        See Also:
        Constant Field Values

      • CONNECTION_FROM_CREATION

        static final int CONNECTION_FROM_CREATION
        Create a connection
        See Also:
        Constant Field Values

      • CONNECTION_FROM_NOWHERE

        static final int CONNECTION_FROM_NOWHERE
        Pool shutting down
        See Also:
        Constant Field Values

    • Method Detail

      • waitConnectionAvailable

        int waitConnectionAvailable()
                     throws java.lang.InterruptedException
        Get permission to grab a connection for use. If this object believes there is a connection available in the pool, it will update its pool size variable and return If not, this method evaluates whether a new connection should be created. If neither condition is true, it waits until a connection is available.
        Returns:
        whether to take the connection from the pool, or create one, or whether the throttler is being shut down.
        Throws:
        java.lang.InterruptedException

      • waitConnectionAvailable

        int waitConnectionAvailable​(IBreakCheck breakCheck)
                     throws java.lang.InterruptedException,
                            BreakException
        Get permission to grab a connection for use. If this object believes there is a connection available in the pool, it will update its pool size variable and return If not, this method evaluates whether a new connection should be created. If neither condition is true, it waits until a connection is available.
        Returns:
        whether to take the connection from the pool, or create one, or whether the throttler is being shut down.
        Throws:
        java.lang.InterruptedException
        BreakException

      • getNewConnectionFetchThrottler

        IFetchThrottler getNewConnectionFetchThrottler()
        For a new connection, obtain the fetch throttler to use for the connection. If the result from waitConnectionAvailable() is CONNECTION_FROM_CREATION, the calling code is expected to create a connection using the result of this method.
        Returns:
        the fetch throttler for a new connection.

      • noteReturnedConnection

        boolean noteReturnedConnection()
        This method indicates whether a formerly in-use connection should be placed back in the pool or destroyed.
        Returns:
        true if the connection should not be put into the pool but should instead simply be destroyed. If true is returned, the caller MUST call noteConnectionDestroyed() after the connection is destroyed in order for the bookkeeping to work. If false is returned, the caller MUST call noteConnectionReturnedToPool() after the connection is returned to the pool.

      • checkDestroyPooledConnection

        boolean checkDestroyPooledConnection()
        This method calculates whether a connection should be taken from the pool and destroyed /* in order to meet quota requirements. If this method returns /* true, you MUST remove a connection from the pool, and you MUST call /* noteConnectionDestroyed() afterwards.
        Returns:
        true if a pooled connection should be destroyed. If true is returned, the caller MUST call noteConnectionDestroyed() (below) in order for the bookkeeping to work.

      • checkExpireConnection

        boolean checkExpireConnection()
        Connection expiration is tricky, because even though a connection may be identified as being expired, at the very same moment it could be handed out in another thread. So there is a natural race condition present. The way the connection throttler deals with that is to allow the caller to reserve a connection for expiration. This must be called BEFORE the actual identified connection is removed from the connection pool. If the value returned by this method is "true", then a connection MUST be removed from the pool and destroyed, whether or not the identified connection is actually still available for destruction or not.
        Returns:
        true if a connection from the pool can be expired. If true is returned, noteConnectionDestruction() MUST be called once the connection has actually been destroyed.

      • noteConnectionReturnedToPool

        void noteConnectionReturnedToPool()
        Note that a connection has been returned to the pool. Call this method after a connection has been placed back into the pool and is available for use.

      • noteConnectionDestroyed

        void noteConnectionDestroyed()
        Note that a connection has been destroyed. Call this method ONLY after noteReturnedConnection() or checkDestroyPooledConnection() returns true, AND the connection has been already destroyed.