org.epics.pvmanager.pva.rpcservice.rpcclient

Interface PoolConfiguration

public interface PoolConfiguration

A list of properties that are configurable for a rpc client pool.

Author:

fhanik (tomcat connection pool), dkumar (modified for a rpc client pool implementation)

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_MAX_ACTIVE

Method Summary

Methods

Modifier and Type	Method and Description
int	getAbandonWhenPercentageFull() rpc clients that have been abandoned (timed out) wont get closed and reported up unless the number of rpc clients in use are above the percentage defined by abandonWhenPercentageFull.
int	getInitialSize() Returns the number of rpc clients that will be established when the rpc client pool is started.
int	getMaxActive() The maximum number of active rpc clients that can be allocated from this pool at the same time.
long	getMaxAge() Time in milliseconds to keep this rpc client alive even when used.
int	getMaxIdle() The maximum number of rpc clients that should be kept in the idle pool if isPoolSweeperEnabled() returns true.
int	getMaxWait() The maximum number of milliseconds that the pool will wait (when there are no available rpc clients) and the getMaxActive() has been reached) for a rpc client to be returned before throwing an exception.
int	getMinEvictableIdleTimeMillis() The minimum amount of time an object must sit idle in the pool before it is eligible for eviction.
int	getMinIdle() The minimum number of established rpc clients that should be kept in the pool at all times.
int	getRemoveAbandonedTimeout() The time in seconds before a rpc client can be considered abandoned.
int	getSuspectTimeout() Returns the time in seconds to pass before a rpc client is marked an abanoned suspect.
int	getTimeBetweenEvictionRunsMillis() The number of milliseconds to sleep between runs of the idle rpc client validation, abandoned cleaner and idle pool resizing.
boolean	getUseLock() Return true if a lock should be used when operations are performed on the rpc client object.
long	getValidationInterval() Avoid excess validation, only run validation at most at this frequency - time in milliseconds.
boolean	isLogAbandoned() boolean flag to set if stack traces should be logged for application code which abandoned a rpc client.
boolean	isPoolSweeperEnabled() Returns true if the pool sweeper is enabled for the rpc client pool.
boolean	isRemoveAbandoned() boolean flag to remove abandoned rpc clients if they exceed the removeAbandonedTimout.
boolean	isTestOnBorrow() The indication of whether objects will be validated before being borrowed from the pool.
boolean	isTestOnReturn() The indication of whether objects will be validated after being returned to the pool.
boolean	isTestWhileIdle() Set to true if validation should take place while the rpc client is idle.
void	setAbandonWhenPercentageFull(int percentage) rpc clients that have been abandoned (timed out) wont get closed and reported up unless the number of rpc clients in use are above the percentage defined by abandonWhenPercentageFull.
void	setInitialSize(int initialSize) Set the number of rpc clients that will be established when the rpc client pool is started.
void	setLogAbandoned(boolean logAbandoned) boolean flag to set if stack traces should be logged for application code which abandoned a rpc client.
void	setMaxActive(int maxActive) The maximum number of active rpc clients that can be allocated from this pool at the same time.
void	setMaxAge(long maxAge) Time in milliseconds to keep this rpc client alive even when used.
void	setMaxIdle(int maxIdle) The maximum number of rpc clients that should be kept in the idle pool if isPoolSweeperEnabled() returns false.
void	setMaxWait(int maxWait) The maximum number of milliseconds that the pool will wait (when there are no available rpc clients and the getMaxActive() has been reached) for a rpc client to be returned before throwing an exception.
void	setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis) The minimum amount of time an object must sit idle in the pool before it is eligible for eviction.
void	setMinIdle(int minIdle) The minimum number of established rpc clients that should be kept in the pool at all times.
void	setRemoveAbandoned(boolean removeAbandoned) boolean flag to remove abandoned rpc clients if they exceed the removeAbandonedTimout.
void	setRemoveAbandonedTimeout(int removeAbandonedTimeout) The time in seconds before a rpc client can be considered abandoned.
void	setSuspectTimeout(int seconds) Similar to setRemoveAbandonedTimeout(int) but instead of treating the rpc client as abandoned, and potentially closing the rpc client, this simply logs the warning if isLogAbandoned() returns true.
void	setTestOnBorrow(boolean testOnBorrow) The indication of whether objects will be validated before being borrowed from the pool.
void	setTestOnReturn(boolean testOnReturn) The indication of whether objects will be validated after being returned to the pool.
void	setTestWhileIdle(boolean testWhileIdle) Set to true if validation should take place while the rpc client is idle.
void	setTimeBetweenEvictionRunsMillis(int timeBetweenEvictionRunsMillis) The number of milliseconds to sleep between runs of the idle rpc client validation, abandoned cleaner and idle pool resizing.
void	setUseLock(boolean useLock) Set to true if a lock should be used when operations are performed on the rpc client object.
void	setValidationInterval(long validationInterval) avoid excess validation, only run validation at most at this frequency - time in milliseconds.

Field Detail

DEFAULT_MAX_ACTIVE

static final int DEFAULT_MAX_ACTIVE

See Also:

Constant Field Values

Method Detail

setAbandonWhenPercentageFull

void setAbandonWhenPercentageFull(int percentage)

rpc clients that have been abandoned (timed out) wont get closed and reported up unless the number of rpc clients in use are above the percentage defined by abandonWhenPercentageFull. The value should be between 0-100. The default value is 0, which implies that rpc clients are eligible for closure as soon as removeAbandonedTimeout has been reached.

Parameters:

percentage - a value between 0 and 100 to indicate when rpc clients that have been abandoned/timed out are considered abandoned

getAbandonWhenPercentageFull

int getAbandonWhenPercentageFull()

rpc clients that have been abandoned (timed out) wont get closed and reported up unless the number of rpc clients in use are above the percentage defined by abandonWhenPercentageFull. The value should be between 0-100. The default value is 0, which implies that rpc clients are eligible for closure as soon as removeAbandonedTimeout has been reached.

Returns:

percentage - a value between 0 and 100 to indicate when rpc clients that have been abandoned/timed out are considered abandoned

getInitialSize

int getInitialSize()

Returns the number of rpc clients that will be established when the rpc client pool is started. Default value is 10

Returns:

number of rpc clients to be started when pool is started

setInitialSize

void setInitialSize(int initialSize)

Set the number of rpc clients that will be established when the rpc client pool is started. Default value is 10. If this value exceeds setMaxActive(int) it will automatically be lowered.

Parameters:

initialSize - the number of rpc clients to be established.

isLogAbandoned

boolean isLogAbandoned()

boolean flag to set if stack traces should be logged for application code which abandoned a rpc client. Logging of abandoned rpc clients adds overhead for every rpc client borrow because a stack trace has to be generated. The default value is false.

Returns:

true if the rpc client pool logs stack traces when rpc clients are borrowed from the pool.

setLogAbandoned

void setLogAbandoned(boolean logAbandoned)

boolean flag to set if stack traces should be logged for application code which abandoned a rpc client. Logging of abandoned rpc clients adds overhead for every rpc client borrow because a stack trace has to be generated. The default value is false.

Parameters:

logAbandoned - set to true if stack traces should be recorded.

getMaxActive

int getMaxActive()

The maximum number of active rpc clients that can be allocated from this pool at the same time. The default value is 100

Returns:

the maximum number of rpc clients used by this pool

setMaxActive

void setMaxActive(int maxActive)

The maximum number of active rpc clients that can be allocated from this pool at the same time. The default value is 100

Parameters:

maxActive - hard limit for number of managed rpc clients by this pool

getMaxIdle

int getMaxIdle()

The maximum number of rpc clients that should be kept in the idle pool if isPoolSweeperEnabled() returns true. If the If isPoolSweeperEnabled() returns true, then the idle pool can grow up to getMaxActive() and will be shrunk according to getMinEvictableIdleTimeMillis() setting. Default value is maxActive:100

Returns:

the maximum number of idle rpc clients.

setMaxIdle

void setMaxIdle(int maxIdle)

The maximum number of rpc clients that should be kept in the idle pool if isPoolSweeperEnabled() returns false. If the If isPoolSweeperEnabled() returns true, then the idle pool can grow up to getMaxActive() and will be shrunk according to getMinEvictableIdleTimeMillis() setting. Default value is maxActive:100

Parameters:

maxIdle - the maximum size of the idle pool

getMaxWait

int getMaxWait()

The maximum number of milliseconds that the pool will wait (when there are no available rpc clients) and the getMaxActive() has been reached) for a rpc client to be returned before throwing an exception. Default value is 30000 (30 seconds)

Returns:

the number of milliseconds to wait for a rpc client to become available if the pool is maxed out.

setMaxWait

void setMaxWait(int maxWait)

The maximum number of milliseconds that the pool will wait (when there are no available rpc clients and the getMaxActive() has been reached) for a rpc client to be returned before throwing an exception. Default value is 30000 (30 seconds)

Parameters:

maxWait - the maximum number of milliseconds to wait.

getMinEvictableIdleTimeMillis

int getMinEvictableIdleTimeMillis()

The minimum amount of time an object must sit idle in the pool before it is eligible for eviction. The default value is 60000 (60 seconds).

Returns:

the minimum amount of idle time in milliseconds before a rpc client is considered idle and eligible for eviction.

setMinEvictableIdleTimeMillis

void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis)

The minimum amount of time an object must sit idle in the pool before it is eligible for eviction. The default value is 60000 (60 seconds).

Parameters:

minEvictableIdleTimeMillis - the number of milliseconds a rpc client must be idle to be eligible for eviction.

getMinIdle

int getMinIdle()

The minimum number of established rpc clients that should be kept in the pool at all times. The rpc client pool can shrink below this number if validation fail and rpc clients get closed. Default value is derived from getInitialSize() (also see setTestWhileIdle(boolean) The idle pool will not shrink below this value during an eviction run, hence the number of actual rpc clients can be between getMinIdle() and somewhere between getMaxIdle() and getMaxActive()

Returns:

the minimum number of idle or established rpc clients

setMinIdle

void setMinIdle(int minIdle)

The minimum number of established rpc clients that should be kept in the pool at all times. The rpc client pool can shrink below this number if validation fail and rpc clients get closed. Default value is derived from getInitialSize() (also see setTestWhileIdle(boolean) The idle pool will not shrink below this value during an eviction run, hence the number of actual rpc clients can be between getMinIdle() and somewhere between getMaxIdle() and getMaxActive()

Parameters:

minIdle - the minimum number of idle or established rpc clients

isRemoveAbandoned

boolean isRemoveAbandoned()

boolean flag to remove abandoned rpc clients if they exceed the removeAbandonedTimout. If set to true a rpc client is considered abandoned and eligible for removal if it has been in use longer than the getRemoveAbandonedTimeout() and the condition for getAbandonWhenPercentageFull() is met. Setting this to true can recover rpc clients from applications that fail to close a rpc client. See also isLogAbandoned() The default value is false.

Returns:

true if abandoned rpc clients can be closed and expelled out of the pool

setRemoveAbandoned

void setRemoveAbandoned(boolean removeAbandoned)

boolean flag to remove abandoned rpc clients if they exceed the removeAbandonedTimout. If set to true a rpc client is considered abandoned and eligible for removal if it has been in use longer than the getRemoveAbandonedTimeout() and the condition for getAbandonWhenPercentageFull() is met. Setting this to true can recover rpc clients from applications that fail to close a rpc client. See also isLogAbandoned() The default value is false.

Parameters:

removeAbandoned - set to true if abandoned rpc clients can be closed and expelled out of the pool

setRemoveAbandonedTimeout

void setRemoveAbandonedTimeout(int removeAbandonedTimeout)

The time in seconds before a rpc client can be considered abandoned.

Parameters:

removeAbandonedTimeout - the time in seconds before a used rpc client can be considered abandoned

getRemoveAbandonedTimeout

int getRemoveAbandonedTimeout()

The time in seconds before a rpc client can be considered abandoned.

Returns:

the time in seconds before a used rpc client can be considered abandoned

isTestOnBorrow

boolean isTestOnBorrow()

The indication of whether objects will be validated before being borrowed from the pool. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another. Default value is false In order to have a more efficient validation, see setValidationInterval(long)

Returns:

true if the rpc client is to be validated upon borrowing a rpc client from the pool

See Also:

getValidationInterval()

setTestOnBorrow

void setTestOnBorrow(boolean testOnBorrow)

The indication of whether objects will be validated before being borrowed from the pool. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another. Default value is false In order to have a more efficient validation, see setValidationInterval(long)

Parameters:

testOnBorrow - set to true if validation should take place before a rpc client is handed out to the application

See Also:

getValidationInterval()

isTestOnReturn

boolean isTestOnReturn()

The indication of whether objects will be validated after being returned to the pool. If the object fails to validate, it will be dropped from the pool. Default value is false In order to have a more efficient validation, see setValidationInterval(long)

Returns:

true if validation should take place after a rpc client is returned to the pool

See Also:

getValidationInterval()

setTestOnReturn

void setTestOnReturn(boolean testOnReturn)

The indication of whether objects will be validated after being returned to the pool. If the object fails to validate, it will be dropped from the pool. Default value is false In order to have a more efficient validation, see setValidationInterval(long)

Parameters:

testOnReturn - true if validation should take place after a rpc client is returned to the pool

See Also:

getValidationInterval()

isTestWhileIdle

boolean isTestWhileIdle()

Set to true if validation should take place while the rpc client is idle.

Returns:

true if validation should take place during idle checks

See Also:

setTimeBetweenEvictionRunsMillis(int)

setTestWhileIdle

void setTestWhileIdle(boolean testWhileIdle)

Set to true if validation should take place while the rpc client is idle.

Parameters:

testWhileIdle - true if validation should take place during idle checks

See Also:

setTimeBetweenEvictionRunsMillis(int)

getTimeBetweenEvictionRunsMillis

int getTimeBetweenEvictionRunsMillis()

The number of milliseconds to sleep between runs of the idle rpc client validation, abandoned cleaner and idle pool resizing. This value should not be set under 1 second. It dictates how often we check for idle, abandoned rpc clients, and how often we validate idle rpc client and resize the idle pool. The default value is 5000 (5 seconds)

Returns:

the sleep time in between validations in milliseconds

setTimeBetweenEvictionRunsMillis

void setTimeBetweenEvictionRunsMillis(int timeBetweenEvictionRunsMillis)

The number of milliseconds to sleep between runs of the idle rpc client validation, abandoned cleaner and idle pool resizing. This value should not be set under 1 second. It dictates how often we check for idle, abandoned rpc clients, and how often we validate idle rpc client and resize the idle pool. The default value is 5000 (5 seconds)

Parameters:

timeBetweenEvictionRunsMillis - the sleep time in between validations in milliseconds

getValidationInterval

long getValidationInterval()

Avoid excess validation, only run validation at most at this frequency - time in milliseconds. If a rpc client is due for validation, but has been validated previously within this interval, it will not be validated again. The default value is 30000 (30 seconds).

Returns:

the validation interval in milliseconds

setValidationInterval

void setValidationInterval(long validationInterval)

avoid excess validation, only run validation at most at this frequency - time in milliseconds. If a rpc client is due for validation, but has been validated previously within this interval, it will not be validated again. The default value is 30000 (30 seconds).

Parameters:

validationInterval - the validation interval in milliseconds

isPoolSweeperEnabled

boolean isPoolSweeperEnabled()

Returns true if the pool sweeper is enabled for the rpc client pool. The pool sweeper is enabled if any settings that require async intervention in the pool are turned on

   boolean result = getTimeBetweenEvictionRunsMillis()>0;
   result = result && (isRemoveAbandoned() && getRemoveAbandonedTimeout()>0);
   result = result || (isTestWhileIdle();
   return result;
   

Returns:

true if a background thread is or will be enabled for this pool

getMaxAge

long getMaxAge()

Time in milliseconds to keep this rpc client alive even when used. When a rpc client is returned to the pool, the pool will check to see if the ((now - time-when-connected) > maxAge) has been reached, and if so, it closes the rpc client rather than returning it to the pool. The default value is 0, which implies that rpc clients will be left open and no age check will be done upon returning the rpc client to the pool.

Returns:

the time in milliseconds a rpc client will be open for when used

setMaxAge

void setMaxAge(long maxAge)

Time in milliseconds to keep this rpc client alive even when used. When a rpc client is returned to the pool, the pool will check to see if the ((now - time-when-connected) > maxAge) has been reached, and if so, it closes the rpc client rather than returning it to the pool. The default value is 0, which implies that rpc clients will be left open and no age check will be done upon returning the rpc client to the pool.

Parameters:

maxAge - the time in milliseconds a rpc client will be open for when used

getUseLock

boolean getUseLock()

Return true if a lock should be used when operations are performed on the rpc client object. Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting.

Returns:

true if a lock is used.

setUseLock

void setUseLock(boolean useLock)

Set to true if a lock should be used when operations are performed on the rpc client object. Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting.

Parameters:

useLock - set to true if a lock should be used on rpc client operations

setSuspectTimeout

void setSuspectTimeout(int seconds)

Similar to setRemoveAbandonedTimeout(int) but instead of treating the rpc client as abandoned, and potentially closing the rpc client, this simply logs the warning if isLogAbandoned() returns true. If this value is equal or less than 0, no suspect checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and the rpc client was not abandoned or if abandon check is disabled. If a rpc client is suspect a WARN message gets logged.

Parameters:

seconds - - the amount of time in seconds that has to pass before a rpc client is marked suspect.

getSuspectTimeout

int getSuspectTimeout()

Returns the time in seconds to pass before a rpc client is marked an abanoned suspect. Any value lesser than or equal to 0 means the check is disabled.

Returns:

Returns the time in seconds to pass before a rpc client is marked an abanoned suspect.