org.gm4java.engine.support

Class GMConnectionPoolConfig

java.lang.Object

org.gm4java.engine.support.GMConnectionPoolConfig

public class GMConnectionPoolConfig
extends Object

Configuration of PooledGMService that provides a number of configuration parameters.

• maxActive controls the maximum number of GM connections that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. When non-positive, there is no limit to the number of GM connections that can be managed by the pool at one time. When maxActive is reached, the pool is said to be exhausted. The default setting for this parameter is 8.
• maxIdle controls the maximum number of GM connections that can sit idle in the pool at any time. When negative, there is no limit to the number of GM connections that may be idle at one time. The default setting for this parameter is 8.
• whenExhaustedAction specifies the behavior of the PooledGMService.getConnection() method when the pool is exhausted:
  • When whenExhaustedAction is WhenExhaustedAction.FAIL, PooledGMService.getConnection() will throw a NoSuchElementException
  • When whenExhaustedAction is WhenExhaustedAction.GROW, PooledGMService.getConnection() will create a new GM connection and return it (essentially making maxActive meaningless.)
  • When whenExhaustedAction is WhenExhaustedAction.BLOCK, PooledGMService.getConnection() will block (invoke Object.wait()) until a new or idle GM connection is available. If a positive maxWait value is supplied, then PooledGMService.getConnection() will block for at most that many milliseconds, after which a NoSuchElementException will be thrown. If maxWait is non-positive, the PooledGMService.getConnection() method will block indefinitely.
  The default whenExhaustedAction setting is WhenExhaustedAction.BLOCK and the default maxWait setting is -1. By default, therefore, PooledGMService.getConnection() will block indefinitely until an idle instance becomes available.
• When testOnGet is set, the pool will attempt to validate each GM connection before it is returned from the PooledGMService.getConnection() method. (Using the provided factory's PoolableObjectFactory.validateObject(T) method.) Objects that fail to validate will be dropped from the pool, and a different GM connection will be returned. The default setting for this parameter is false.
• When testOnReturn is set, the pool will attempt to validate each GM connection before it is returned to the pool in the GenericObjectPool.returnObject(T) method. (Using the provided factory's PoolableObjectFactory.validateObject(T) method.) Objects that fail to validate will be dropped from the pool. The default setting for this parameter is false.

Optionally, one may configure the pool to examine and possibly evict GM connections as they sit idle in the pool and to ensure that a minimum number of idle GM connections are available. This is performed by an "idle GM connection eviction" thread, which runs asynchronously. Caution should be used when configuring this optional feature. Eviction runs contend with client threads for access to GM connections in the pool, so if they run too frequently performance issues may result. The idle GM connection eviction thread may be configured using the following attributes:

• timeBetweenEvictionRunsMillis indicates how long the eviction thread should sleep before "runs" of examining idle GM connections. When non-positive, no eviction thread will be launched. The default setting for this parameter is -1 (i.e., idle GM connection eviction is disabled by default).
• minEvictableIdleTimeMillis specifies the minimum amount of time that an GM connection may sit idle in the pool before it is eligible for eviction due to idle time. When non-positive, no GM connection will be dropped from the pool due to idle time alone. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. The default setting for this parameter is 30 minutes.
• testWhileIdle indicates whether or not idle GM connections should be validated using the factory's PoolableObjectFactory.validateObject(T) method. Objects that fail to validate will be dropped from the pool. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. The default setting for this parameter is false.
• softMinEvictableIdleTimeMillis specifies the minimum amount of time a GM connection may sit idle in the pool before it is eligible for eviction by the idle GM connection evictor (if any), with the extra condition that at least "minIdle" GM connection instances remain in the pool. When non-positive, no GM connection will be evicted from the pool due to idle time alone. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. and it is superceded by minEvictableIdleTimeMillis (that is, if minEvictableIdleTimeMillis is positive, then softMinEvictableIdleTimeMillis is ignored). The default setting for this parameter is -1 (disabled).
• numTestsPerEvictionRun determines the number of GM connections examined in each run of the idle GM connection evictor. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. The default setting for this parameter is 3.

The pool can be configured to behave as a LIFO queue with respect to idle GM connections - always returning the most recently used GM connection from the pool, or as a FIFO queue, where PooledGMService.getConnection() always returns the oldest GM connection in the idle GM connection pool.

• lifo determines whether or not the pool returns idle GM connections in last-in-first-out order. The default setting for this parameter is true.

Author:

Kenneth Xu

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_EVICT_AFTER_NUMBER_OF_USE Default value for the number of times a GraphicsMagick process can be used to execute commands before it gets evicted from pool.
static String	DEFAULT_GM_PATH Default path to GraphcisMagick executable.

Constructor Summary

Constructors

Constructor and Description
GMConnectionPoolConfig()

Method Summary

Methods

Modifier and Type	Method and Description
int	getEvictAfterNumberOfUse() Get the number of times a GraphicsMagick process can be used to execute commands before it gets evicted and destroyed.
String	getGMPath() Gets the path to GraphicsMagick executable.
int	getMaxActive() Returns the maximum number of GMConnections that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time.
int	getMaxIdle() Returns the cap on the number of "idle" instances in the pool.
long	getMaxWait() Returns the maximum amount of time (in milliseconds) the PooledGMService.getConnection() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WhenExhaustedAction.BLOCK.
long	getMinEvictableIdleTimeMillis() Returns the minimum amount of time an GMConnection may sit idle in the pool before it is eligible for eviction by the idle GMConnection evictor (if any).
int	getMinIdle() Returns the minimum number of GMConnections allowed in the pool before the evictor thread (if active) spawns new GMConnections.
int	getNumTestsPerEvictionRun() Returns the max number of GMConnections to examine during each run of the idle GMConnection evictor thread (if any).
long	getSoftMinEvictableIdleTimeMillis() Returns the minimum amount of time an GMConnection may sit idle in the pool before it is eligible for eviction by the idle GMConnection evictor (if any), with the extra condition that at least "minIdle" amount of GMConnection remain in the pool.
boolean	getTestOnGet() When true, GMConnections will be validated} before being returned by the PooledGMService.getConnection() method.
boolean	getTestOnReturn() When true, GMConnections will be validated before being returned to the pool within the GenericObjectPool.returnObject(T).
boolean	getTestWhileIdle() When true, GMConnections will be validated by the idle GMConnection evictor (if any).
long	getTimeBetweenEvictionRunsMillis() Returns the number of milliseconds to sleep between runs of the idle GMConnection evictor thread.
WhenExhaustedAction	getWhenExhaustedAction() Returns the action to take when the PooledGMService.getConnection() method is invoked when the pool is exhausted (the maximum number of "active" GMConnections has been reached).
boolean	isLifo() Whether or not the idle pool acts as a LIFO queue.
void	setEvictAfterNumberOfUse(int evictAfterNumberOfUse) Set the number of times a GraphicsMagick process can be used to execute commands before it gets evicted and destroyed.
void	setGMPath(String gmPath) Sets the path to GraphicsMagick executable.
void	setLifo(boolean lifo) Sets the LIFO property of the pool.
void	setMaxActive(int maxActive) Sets the cap on the number of GMConnections that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time.
void	setMaxIdle(int maxIdle) Sets the cap on the number of "idle" instances in the pool.
void	setMaxWait(long maxWait) Sets the maximum amount of time (in milliseconds) the PooledGMService.getConnection() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WhenExhaustedAction.BLOCK.
void	setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis) Sets the minimum amount of time an GMConnection may sit idle in the pool before it is eligible for eviction by the idle GMConnection evictor (if any).
void	setMinIdle(int minIdle) Sets the minimum number of GMConnections allowed in the pool before the evictor thread (if active) spawns new GMConnections.
void	setNumTestsPerEvictionRun(int numTestsPerEvictionRun) Sets the max number of GMConnections to examine during each run of the idle GMConnection evictor thread (if any).
void	setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis) Sets the minimum amount of time an GMConnection may sit idle in the pool before it is eligible for eviction by the idle GMConnection evictor (if any), with the extra condition that at least "minIdle" GMConnection instances remain in the pool.
void	setTestOnGet(boolean testOnGet) When true, GMConnections will be validated before being returned by the PooledGMService.getConnection() method.
void	setTestOnReturn(boolean testOnReturn) When true, GMConnections will be validated before being returned to the pool within the GenericObjectPool.returnObject(T).
void	setTestWhileIdle(boolean testWhileIdle) When true, GMConnections will be validated by the idle GMConnection evictor (if any).
void	setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis) Sets the number of milliseconds to sleep between runs of the idle GMConnection evictor thread.
void	setWhenExhaustedAction(WhenExhaustedAction whenExhaustedAction) Sets the action to take when the PooledGMService.getConnection() method is invoked when the pool is exhausted (the maximum number of "active" GMConnections has been reached).

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_GM_PATH

public static final String DEFAULT_GM_PATH

Default path to GraphcisMagick executable.

See Also:

Constant Field Values

DEFAULT_EVICT_AFTER_NUMBER_OF_USE

public static final int DEFAULT_EVICT_AFTER_NUMBER_OF_USE

Default value for the number of times a GraphicsMagick process can be used to execute commands before it gets evicted from pool.

See Also:

Constant Field Values

Constructor Detail

GMConnectionPoolConfig

public GMConnectionPoolConfig()

Method Detail

getMaxActive

public int getMaxActive()

Returns the maximum number of GMConnections that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. When non-positive, there is no limit to the number of GMConnections that can be managed by the pool at one time.

Returns:

the cap on the total number of GMConnection instances managed by the pool.

See Also:

setMaxActive(int)

setMaxActive

public void setMaxActive(int maxActive)

Sets the cap on the number of GMConnections that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. Use a negative value for no limit.

Parameters:

maxActive - The cap on the total number of GMConnection instances managed by the pool. Negative values mean that there is no limit to the number of GMConnections allocated by the pool.

See Also:

getMaxActive()

getWhenExhaustedAction

public WhenExhaustedAction getWhenExhaustedAction()

Returns the action to take when the PooledGMService.getConnection() method is invoked when the pool is exhausted (the maximum number of "active" GMConnections has been reached).

Returns:

one of WhenExhaustedAction enum value

See Also:

setWhenExhaustedAction(org.gm4java.engine.support.WhenExhaustedAction)

setWhenExhaustedAction

public void setWhenExhaustedAction(WhenExhaustedAction whenExhaustedAction)

Sets the action to take when the PooledGMService.getConnection() method is invoked when the pool is exhausted (the maximum number of "active" GMConnections has been reached).

Parameters:

whenExhaustedAction - the action to set

See Also:

getWhenExhaustedAction()

getMaxWait

public long getMaxWait()

Returns the maximum amount of time (in milliseconds) the PooledGMService.getConnection() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WhenExhaustedAction.BLOCK. When less than or equal to 0, the PooledGMService.getConnection() method may block indefinitely.

Returns:

maximum number of milliseconds to block when getting an GMConnection.

See Also:

setMaxWait(long), setWhenExhaustedAction(org.gm4java.engine.support.WhenExhaustedAction)

setMaxWait

public void setMaxWait(long maxWait)

Sets the maximum amount of time (in milliseconds) the PooledGMService.getConnection() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WhenExhaustedAction.BLOCK. When less than or equal to 0, the PooledGMService.getConnection() method may block indefinitely.

Parameters:

maxWait - maximum number of milliseconds to block when getting an GMConnection.

See Also:

getMaxWait(), setWhenExhaustedAction(org.gm4java.engine.support.WhenExhaustedAction)

getMaxIdle

public int getMaxIdle()

Returns the cap on the number of "idle" instances in the pool.

Returns:

the cap on the number of "idle" instances in the pool.

See Also:

setMaxIdle(int)

setMaxIdle

public void setMaxIdle(int maxIdle)

Sets the cap on the number of "idle" instances in the pool. If maxIdle is set too low on heavily loaded systems it is possible you will see GMConnections being destroyed and almost immediately new GMConnection s being created. This is a result of the active threads momentarily returning GMConnections faster than they are requesting them them, causing the number of idle GMConnections to rise above maxIdle. The best value for maxIdle for heavily loaded system will vary but the default is a good starting point.

Parameters:

maxIdle - The cap on the number of "idle" instances in the pool. Use a negative value to indicate an unlimited number of idle instances.

See Also:

getMaxIdle()

setMinIdle

public void setMinIdle(int minIdle)

Sets the minimum number of GMConnections allowed in the pool before the evictor thread (if active) spawns new GMConnections. Note that no GMConnections are created when numActive + numIdle >= maxActive. This setting has no effect if the idle GMConnection evictor is disabled (i.e. if timeBetweenEvictionRunsMillis <= 0).

Parameters:

minIdle - The minimum number of GMConnections.

See Also:

getMinIdle(), getTimeBetweenEvictionRunsMillis()

getMinIdle

public int getMinIdle()

Returns the minimum number of GMConnections allowed in the pool before the evictor thread (if active) spawns new GMConnections. (Note no GMConnections are created when: numActive + numIdle >= maxActive)

Returns:

The minimum number of GMConnections.

See Also:

setMinIdle(int)

getTestOnGet

public boolean getTestOnGet()

When true, GMConnections will be validated} before being returned by the PooledGMService.getConnection() method. If the GMConnection fails to validate, it will be dropped from the pool, and we will attempt to get another.

Returns:

true if GMConnections are validated before being returned.

See Also:

setTestOnGet(boolean)

setTestOnGet

public void setTestOnGet(boolean testOnGet)

When true, GMConnections will be validated before being returned by the PooledGMService.getConnection() method. If the GMConnection fails to validate, it will be dropped from the pool, and we will attempt to get another.

Parameters:

testOnGet - true if GMConnections should be validated before being returned.

See Also:

getTestOnGet()

getTestOnReturn

public boolean getTestOnReturn()

When true, GMConnections will be validated before being returned to the pool within the GenericObjectPool.returnObject(T).

Returns:

true when GMConnections will be validated after returned to GenericObjectPool.returnObject(T).

See Also:

setTestOnReturn(boolean)

setTestOnReturn

public void setTestOnReturn(boolean testOnReturn)

When true, GMConnections will be validated before being returned to the pool within the GenericObjectPool.returnObject(T).

Parameters:

testOnReturn - true so GMConnections will be validated after returned to GenericObjectPool.returnObject(T).

See Also:

getTestOnReturn()

getTimeBetweenEvictionRunsMillis

public long getTimeBetweenEvictionRunsMillis()

Returns the number of milliseconds to sleep between runs of the idle GMConnection evictor thread. When non-positive, no idle GMConnection evictor thread will be run.

Returns:

number of milliseconds to sleep between evictor runs.

See Also:

setTimeBetweenEvictionRunsMillis(long)

setTimeBetweenEvictionRunsMillis

public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)

Sets the number of milliseconds to sleep between runs of the idle GMConnection evictor thread. When non-positive, no idle GMConnection evictor thread will be run.

Parameters:

timeBetweenEvictionRunsMillis - number of milliseconds to sleep between evictor runs.

See Also:

getTimeBetweenEvictionRunsMillis()

getNumTestsPerEvictionRun

public int getNumTestsPerEvictionRun()

Returns the max number of GMConnections to examine during each run of the idle GMConnection evictor thread (if any).

Returns:

max number of GMConnections to examine during each evictor run.

See Also:

setNumTestsPerEvictionRun(int), setTimeBetweenEvictionRunsMillis(long)

setNumTestsPerEvictionRun

public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)

Sets the max number of GMConnections to examine during each run of the idle GMConnection evictor thread (if any).

When a negative value is supplied, ceil(GenericObjectPool.getNumIdle())/abs(GenericObjectPool.getNumTestsPerEvictionRun()) tests will be run. That is, when the value is -n, roughly one nth of the idle GMConnections will be tested per run. When the value is positive, the number of tests actually performed in each run will be the minimum of this value and the number of instances idle in the pool.

Parameters:

numTestsPerEvictionRun - max number of GMConnections to examine during each evictor run.

See Also:

getNumTestsPerEvictionRun(), setTimeBetweenEvictionRunsMillis(long)

getMinEvictableIdleTimeMillis

public long getMinEvictableIdleTimeMillis()

Returns the minimum amount of time an GMConnection may sit idle in the pool before it is eligible for eviction by the idle GMConnection evictor (if any).

Returns:

minimum amount of time an GMConnection may sit idle in the pool before it is eligible for eviction.

See Also:

setMinEvictableIdleTimeMillis(long), setTimeBetweenEvictionRunsMillis(long)

setMinEvictableIdleTimeMillis

public void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)

Sets the minimum amount of time an GMConnection may sit idle in the pool before it is eligible for eviction by the idle GMConnection evictor (if any). When non-positive, no GMConnections will be evicted from the pool due to idle time alone.

Parameters:

minEvictableIdleTimeMillis - minimum amount of time an GMConnection may sit idle in the pool before it is eligible for eviction.

See Also:

getMinEvictableIdleTimeMillis(), setTimeBetweenEvictionRunsMillis(long)

getSoftMinEvictableIdleTimeMillis

public long getSoftMinEvictableIdleTimeMillis()

Returns the minimum amount of time an GMConnection may sit idle in the pool before it is eligible for eviction by the idle GMConnection evictor (if any), with the extra condition that at least "minIdle" amount of GMConnection remain in the pool.

Returns:

minimum amount of time an GMConnection may sit idle in the pool before it is eligible for eviction.

See Also:

setSoftMinEvictableIdleTimeMillis(long)

setSoftMinEvictableIdleTimeMillis

public void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)

Sets the minimum amount of time an GMConnection may sit idle in the pool before it is eligible for eviction by the idle GMConnection evictor (if any), with the extra condition that at least "minIdle" GMConnection instances remain in the pool. When non-positive, no GMConnections will be evicted from the pool due to idle time alone.

Parameters:

softMinEvictableIdleTimeMillis - minimum amount of time an GMConnection may sit idle in the pool before it is eligible for eviction.

See Also:

getSoftMinEvictableIdleTimeMillis()

getTestWhileIdle

public boolean getTestWhileIdle()

When true, GMConnections will be validated by the idle GMConnection evictor (if any). If an GMConnection fails to validate, it will be dropped from the pool.

Returns:

true when GMConnections will be validated by the evictor.

See Also:

setTestWhileIdle(boolean), setTimeBetweenEvictionRunsMillis(long)

setTestWhileIdle

public void setTestWhileIdle(boolean testWhileIdle)

When true, GMConnections will be validated by the idle GMConnection evictor (if any). If an GMConnection fails to validate, it will be dropped from the pool.

Parameters:

testWhileIdle - true so GMConnections will be validated by the evictor.

See Also:

getTestWhileIdle(), setTimeBetweenEvictionRunsMillis(long)

isLifo

public boolean isLifo()

Whether or not the idle pool acts as a LIFO queue. True means that PooledGMService.getConnection() returns the most recently used ("last in") idle GMConnection in the pool (if there are idle instances available). False means that the pool behaves as a FIFO queue - GMConnection are taken from the idle pool in the order that they are returned to the pool.

Returns:

true if the pool is configured to act as a LIFO queue

setLifo

public void setLifo(boolean lifo)

Sets the LIFO property of the pool. True means that PooledGMService.getConnection() returns the most recently used ("last in") idle GMConnection in the pool (if there are idle instances available). False means that the pool behaves as a FIFO queue - GMConnection are taken from the idle pool in the order that they are returned to the pool.

Parameters:

lifo - the new value for the LIFO property

getGMPath

public String getGMPath()

Gets the path to GraphicsMagick executable.

Returns:

the path to GraphicsMagick executable.

setGMPath

public void setGMPath(String gmPath)

Sets the path to GraphicsMagick executable.

Parameters:

gmPath - The path for the gm executable.

getEvictAfterNumberOfUse

public int getEvictAfterNumberOfUse()

Get the number of times a GraphicsMagick process can be used to execute commands before it gets evicted and destroyed. A non-positive value disables this feature. This feature is disabled by default until a positive value

Returns:

the number of times a GraphicsMagick process can be used to execute commands before it gets evicted and destroyed. A non-positive value disables this feature. This feature is disabled by default until a positive value

setEvictAfterNumberOfUse

public void setEvictAfterNumberOfUse(int evictAfterNumberOfUse)

Set the number of times a GraphicsMagick process can be used to execute commands before it gets evicted and destroyed. A non-positive value disables this feature. This feature is disabled by default until a positive value

Note: This setting doesn't guarantee the max number of times a GraphicsMagick process is used to execute the command. The eviction and destruction can only occur when the GMConnection instance is obtained from or returned back to the pool. But a client can get hold of the connection and execute as many commands as it wants.

Parameters:

evictAfterNumberOfUse - the number of times a GraphicsMagick process can be used to execute commands before it gets evicted and destroyed.