public class GMConnectionPoolConfig extends Object
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:
whenExhaustedAction
is WhenExhaustedAction.FAIL
,
PooledGMService.getConnection()
will throw a NoSuchElementException
whenExhaustedAction
is WhenExhaustedAction.GROW
,
PooledGMService.getConnection()
will create a new GM connection and return it (essentially making
maxActive
meaningless.)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.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.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
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.
testOnReturn
is set, the pool will attempt to validate each GM connection before
it is returned to the pool in the #returnObject
method. (Using the provided factory's
PoolableObjectFactory#validateObject
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
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.
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 and Description |
---|
GMConnectionPoolConfig() |
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
GMConnection s 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
GMConnection s allowed in the pool before the evictor thread (if active)
spawns new GMConnection s. |
int |
getNumTestsPerEvictionRun()
Returns the max number of
GMConnection s 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,
GMConnection s will be validated} before being returned by the
PooledGMService.getConnection() method. |
boolean |
getTestOnReturn()
When true,
GMConnection s will be validated before
being returned to the pool within the #returnObject . |
boolean |
getTestWhileIdle()
|
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" GMConnection s 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
GMConnection s 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
GMConnection s allowed in the pool before the evictor thread (if active) spawns
new GMConnection s. |
void |
setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
Sets the max number of
GMConnection s 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,
GMConnection s will be validated before being returned by the
PooledGMService.getConnection() method. |
void |
setTestOnReturn(boolean testOnReturn)
When true,
GMConnection s will be validated before
being returned to the pool within the #returnObject . |
void |
setTestWhileIdle(boolean testWhileIdle)
|
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" GMConnection s has been reached). |
public static final String DEFAULT_GM_PATH
public static final int DEFAULT_EVICT_AFTER_NUMBER_OF_USE
public int getMaxActive()
GMConnection
s 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
GMConnection
s that can be managed by the pool at one time.GMConnection
instances managed by the pool.setMaxActive(int)
public void setMaxActive(int maxActive)
GMConnection
s 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.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 GMConnection
s allocated by the pool.getMaxActive()
public WhenExhaustedAction getWhenExhaustedAction()
PooledGMService.getConnection()
method is invoked when the pool is
exhausted (the maximum number of "active" GMConnection
s has been reached).WhenExhaustedAction
enum valuesetWhenExhaustedAction(org.gm4java.engine.support.WhenExhaustedAction)
public void setWhenExhaustedAction(WhenExhaustedAction whenExhaustedAction)
PooledGMService.getConnection()
method is invoked when the pool is
exhausted (the maximum number of "active" GMConnection
s has been reached).whenExhaustedAction
- the action to setgetWhenExhaustedAction()
public long getMaxWait()
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.GMConnection
.setMaxWait(long)
,
setWhenExhaustedAction(org.gm4java.engine.support.WhenExhaustedAction)
public void setMaxWait(long maxWait)
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.maxWait
- maximum number of milliseconds to block when getting an GMConnection
.getMaxWait()
,
setWhenExhaustedAction(org.gm4java.engine.support.WhenExhaustedAction)
public int getMaxIdle()
setMaxIdle(int)
public void setMaxIdle(int maxIdle)
GMConnection
s being destroyed and almost immediately new GMConnection
s being created. This is a result of the active threads momentarily returning GMConnection
s faster than
they are requesting them them, causing the number of idle GMConnection
s to rise above maxIdle. The best
value for maxIdle for heavily loaded system will vary but the default is a good starting point.maxIdle
- The cap on the number of "idle" instances in the pool. Use a negative value to indicate an unlimited
number of idle instances.getMaxIdle()
public void setMinIdle(int minIdle)
GMConnection
s allowed in the pool before the evictor thread (if active) spawns
new GMConnection
s. Note that no GMConnection
s are created when
numActive + numIdle >= maxActive.
This setting has no effect if the idle GMConnection
evictor is disabled (i.e. if timeBetweenEvictionRunsMillis <= 0
).minIdle
- The minimum number of GMConnection
s.getMinIdle()
,
getTimeBetweenEvictionRunsMillis()
public int getMinIdle()
GMConnection
s allowed in the pool before the evictor thread (if active)
spawns new GMConnection
s. (Note no GMConnection
s are created when: numActive + numIdle >=
maxActive)GMConnection
s.setMinIdle(int)
public boolean getTestOnGet()
GMConnection
s 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.true
if GMConnection
s are validated before being returned.setTestOnGet(boolean)
public void setTestOnGet(boolean testOnGet)
GMConnection
s 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.testOnGet
- true
if GMConnection
s should be validated before being returned.getTestOnGet()
public boolean getTestOnReturn()
GMConnection
s will be validated
before
being returned to the pool within the #returnObject
.true
when GMConnection
s will be validated after returned to #returnObject
.setTestOnReturn(boolean)
public void setTestOnReturn(boolean testOnReturn)
GMConnection
s will be validated
before
being returned to the pool within the #returnObject
.testOnReturn
- true
so GMConnection
s will be validated after returned to #returnObject
.getTestOnReturn()
public long getTimeBetweenEvictionRunsMillis()
GMConnection
evictor thread. When
non-positive, no idle GMConnection
evictor thread will be run.setTimeBetweenEvictionRunsMillis(long)
public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
GMConnection
evictor thread. When
non-positive, no idle GMConnection
evictor thread will be run.timeBetweenEvictionRunsMillis
- number of milliseconds to sleep between evictor runs.getTimeBetweenEvictionRunsMillis()
public int getNumTestsPerEvictionRun()
GMConnection
s to examine during each run of the idle GMConnection
evictor thread (if any).GMConnection
s to examine during each evictor run.setNumTestsPerEvictionRun(int)
,
setTimeBetweenEvictionRunsMillis(long)
public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
GMConnection
s to examine during each run of the idle GMConnection
evictor
thread (if any).
When a negative value is supplied, ceil(#getNumIdle
)/abs(getNumTestsPerEvictionRun()
)
tests will be run. That is, when the value is -n, roughly one nth of the idle GMConnection
s
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.
numTestsPerEvictionRun
- max number of GMConnection
s to examine during each evictor run.getNumTestsPerEvictionRun()
,
setTimeBetweenEvictionRunsMillis(long)
public long getMinEvictableIdleTimeMillis()
GMConnection
may sit idle in the pool before it is eligible for
eviction by the idle GMConnection
evictor (if any).GMConnection
may sit idle in the pool before it is eligible for
eviction.setMinEvictableIdleTimeMillis(long)
,
setTimeBetweenEvictionRunsMillis(long)
public void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
GMConnection
may sit idle in the pool before it is eligible for
eviction by the idle GMConnection
evictor (if any). When non-positive, no GMConnection
s will be
evicted from the pool due to idle time alone.minEvictableIdleTimeMillis
- minimum amount of time an GMConnection
may sit idle in the pool before it is eligible for
eviction.getMinEvictableIdleTimeMillis()
,
setTimeBetweenEvictionRunsMillis(long)
public long getSoftMinEvictableIdleTimeMillis()
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.GMConnection
may sit idle in the pool before it is eligible for
eviction.setSoftMinEvictableIdleTimeMillis(long)
public void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)
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 GMConnection
s will be evicted
from the pool due to idle time alone.softMinEvictableIdleTimeMillis
- minimum amount of time an GMConnection
may sit idle in the pool before it is eligible for
eviction.getSoftMinEvictableIdleTimeMillis()
public boolean getTestWhileIdle()
GMConnection
s will be validated
by the
idle GMConnection
evictor (if any). If an GMConnection
fails to validate, it will be dropped from
the pool.true
when GMConnection
s will be validated by the evictor.setTestWhileIdle(boolean)
,
setTimeBetweenEvictionRunsMillis(long)
public void setTestWhileIdle(boolean testWhileIdle)
GMConnection
s will be validated
by the
idle GMConnection
evictor (if any). If an GMConnection
fails to validate, it will be dropped from
the pool.testWhileIdle
- true
so GMConnection
s will be validated by the evictor.getTestWhileIdle()
,
setTimeBetweenEvictionRunsMillis(long)
public boolean isLifo()
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.true
if the pool is configured to act as a LIFO queuepublic void setLifo(boolean lifo)
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.lifo
- the new value for the LIFO propertypublic String getGMPath()
public void setGMPath(String gmPath)
gmPath
- The path for the gm executable.public int getEvictAfterNumberOfUse()
public void setEvictAfterNumberOfUse(int evictAfterNumberOfUse)
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.
evictAfterNumberOfUse
- the number of times a GraphicsMagick process can be used to execute commands before it gets evicted
and destroyed.Copyright © 2013. All Rights Reserved.