org.apache.manifoldcf.connectorcommon.throttler

Class Throttler.ConnectionThrottler

java.lang.Object

org.apache.manifoldcf.connectorcommon.throttler.Throttler.ConnectionThrottler

All Implemented Interfaces:

IConnectionThrottler

Enclosing class:

Throttler

protected static class Throttler.ConnectionThrottler
extends java.lang.Object
implements IConnectionThrottler

Connection throttler implementation class. This class instance stores some parameters and links back to ThrottlingGroup. But each class instance models a connection pool with the specified bins. But the description of each pool consists of more than just the bin names that describe the throttling - it also may include connection parameters which we have no insight into at this level. Thus, in order to do pool tracking properly, we cannot simply rely on the individual connection bin instances to do all the work, since they cannot distinguish between different pools properly. So that leaves us with two choices. (1) We can somehow push the separate pool instance parameters down to the connection bin level, or (2) the connection bins cannot actually do any waiting or blocking. The benefit of having blocking take place in connection bins is that they are in fact designed to be precisely the thing you would want to synchronize on. If we presume that the waits happen in those classes, then we need the ability to send in our local pool count to them, and we need to be able to "wake up" those underlying classes when the local pool count changes.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String[]	binNames
protected Throttler.ThrottlingGroup	parent
protected java.util.concurrent.atomic.AtomicInteger[]	poolCounts

Fields inherited from interface org.apache.manifoldcf.connectorcommon.interfaces.IConnectionThrottler

_rcsid, CONNECTION_FROM_CREATION, CONNECTION_FROM_NOWHERE, CONNECTION_FROM_POOL

Constructor Summary

Constructors

Constructor and Description
ConnectionThrottler(Throttler.ThrottlingGroup parent, java.lang.String[] binNames)

Method Summary

Modifier and Type	Method and Description
boolean	checkDestroyPooledConnection() This method calculates whether a connection should be taken from the pool and destroyed /* in order to meet quota requirements.
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.
IFetchThrottler	getNewConnectionFetchThrottler() For a new connection, obtain the fetch throttler to use for the connection.
void	noteConnectionDestroyed() Note that a connection has been destroyed.
void	noteConnectionReturnedToPool() Note that a connection has been returned to the pool.
boolean	noteReturnedConnection() For returning a connection from use, there is only one method.
int	waitConnectionAvailable() Get permission to grab a connection for use.
int	waitConnectionAvailable(IBreakCheck breakCheck) Get permission to grab a connection for use.

Methods inherited from class java.lang.Object

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

Field Detail

parent

protected final Throttler.ThrottlingGroup parent

binNames

protected final java.lang.String[] binNames

poolCounts

protected final java.util.concurrent.atomic.AtomicInteger[] poolCounts

Constructor Detail

ConnectionThrottler

public ConnectionThrottler(Throttler.ThrottlingGroup parent,
                           java.lang.String[] binNames)

Method Detail

waitConnectionAvailable

public 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.

Specified by:

waitConnectionAvailable in interface IConnectionThrottler

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

public 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.

Specified by:

waitConnectionAvailable in interface IConnectionThrottler

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

public 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.

Specified by:

getNewConnectionFetchThrottler in interface IConnectionThrottler

Returns:

the fetch throttler for a new connection.

noteReturnedConnection

public boolean noteReturnedConnection()

For returning a connection from use, there is only one method. This method signals /* whether a formerly in-use connection should be placed back in the pool or destroyed.

Specified by:

noteReturnedConnection in interface IConnectionThrottler

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() (below) in order for the bookkeeping to work.

checkDestroyPooledConnection

public 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.

Specified by:

checkDestroyPooledConnection in interface IConnectionThrottler

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

public 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.

Specified by:

checkExpireConnection in interface IConnectionThrottler

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

public 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.

Specified by:

noteConnectionReturnedToPool in interface IConnectionThrottler

noteConnectionDestroyed

public 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.

Specified by:

noteConnectionDestroyed in interface IConnectionThrottler