oracle.rules.rl.extensions.pool
Class RuleSessionPool

java.lang.Object
oracle.rules.rl.extensions.pool.RuleSessionPool

public class RuleSessionPool

extends java.lang.Object

A pool of RuleSession instances.
A typical application that uses rules evaluates the same rules multiple
times with different facts corresponding to separate requests.
Initializing a RuleSession typically takes a few seconds
depending on the number of rules involved. In contrast, the time to execute
the rules typically takes significantly less time.
Therefore, better performance can be achieved by initializing a
RuleSession once and reusing it for each new request. In order
for performance to scale up with increased load, more than one
RuleSession will be required.

This class implements a pool of RuleSession instances to support
improved performance and scalability of applications that use rules.
A pool is instantiated with a list of the RL code that is used to initialize
each RuleSession created by the pool. The RL code
is executed in the order in which it appears in the list. The number
of RuleSession instances to create initially may be specified.
In general, this should be a small value and the default should be
sufficient in most cases.

A poolable RuleSession is acquired by invoking the
getPoolableRuleSession method.
The pool creates new RuleSessions as required.
An invocation of getPoolableRuleSession will not
block waiting for a free RuleSession.
A soft upper bound on the size of the pool can be specified.
This allows the pool to respond
to temporary increases in demand by growing the pool while allowing the pool
to shrink down to this soft upper bound when demand subsides.

When rule execution has been completed, the poolable RuleSession
is returned to the pool by invoking the
returnPoolableRuleSession method. When a
RuleSession is returned to the pool it is reset by the pool by
invoking the built-in RL function, reset(). This removes all
facts from working memory to prepare the RuleSession for the
next execution. Every RuleSession that is retrieved from the
pool should be returned to the pool. If an error has occured during rule
execution that results in the RuleSession being unfit for
further use, the pool detects this and discards it.

Besides clearing working memory, the reset() function
re-executes the initializers of all non-final global variables.
The initializer of a non-final global variable can be used to perform
other initialization at reset if this is required. For example, in the
following

the resetHook() function is executed on each reset and
the function can perform any additional initialization as required.
An example of additional initialization is asserting a set of
initial facts required for each rule execution.
Care should be taken that there are no undesired side affects of
non-final global variable initializers.
Final global variable initializers are not re-executed on reset, so these
should not have any side affects since the initializer is only executed
when the RuleSession is created and loaded with the
RL code from the list.

If the rules in use by an application are updated, the application may
need to load the new rules so that subsequent rule executions use the
new rules. This is supported by the pool by invoking the
refreshPool method passing it a list of the new RL.
After the pool has been refreshed, RuleSessions returned by
getPoolableRuleSession will have been initialized with the
new RL code.
When RuleSessions that were obtained before the refresh are
returned via returnPoolableRuleSession, they are not placed
back in the pool. The refreshed pool will only contain
RuleSessions initialized with the new RL code.

Typically, the RL code will be generated from a RuleDictionary
created with the Rules SDK. The code example below demonstrates
creating and using a RuleSessionPool with RL code from a
RuleDictionary.

RuleSessionPool

Construct a RuleSession pool given an initial size
and a list of RL text.

Parameters:

rl - the list of RL text.

config - RuleSession configuration to be used when creating
new instances. May be null.

initialSize - the number of RuleSession instances to create
initially.

softMaximumSize - a soft upper limit on the size of the pool.
A value of 0 or less disables this feature.
If it is greater than 0 but less than the
initialSize, then it is silently set to
the initialSize.

getSoftMaximumSize

getSize

Returns the number of poolable RuleSession objects associated with
this pool.

Returns:

the poolable RuleSession count

getInuse

public int getInuse()

Returns the number of RuleSession objects from this
that are currently in use.

Returns:

the number of RuleSession object currently in use.

getFree

public int getFree()

Returns the number of free poolable RuleSession objects available for
use.

Returns:

the number of free poolable RuleSession objects

getUsage

public long getUsage()

Returns the total number of times a poolable RuleSession has been
acquired from this pool.

Returns:

the usage count

getCreated

public long getCreated()

Returns the total number of poolable RuleSession objects that have been
created by this pool.

Returns:

the number of RuleSession objects created

getDiscarded

public long getDiscarded()

Returns the total number of RuleSession objects that have been
discarded because they were marked invalid as a result of an error
encountered while the RuleSession was in use.

Returns:

the number of discarded RuleSession objects

getReclaimed

public long getReclaimed()

Returns the total number of RuleSession objects that have been
reclaimed. Bursts in demand for RuleSession objects can result in
a pool size that exceeds the soft maximum pool
size (if one was specified). As the demand lessens, the extra
RuleSession objects are automatically reclaimed from the pool so that
the memory can be reclaimed by the JVM.

Returns:

the number of reclaimed RuleSession objects

getRetired

public long getRetired()

Returns the total number of RuleSession objects that have been
retired because the usage exceeded the specified maximum usage for
a RuleSession.

Returns:

the number of retired RuleSession objects

setMaximumSessionUsage

public void setMaximumSessionUsage(int value)

Sets the maximum RuleSession usage count.
This is the maximum number of times a RuleSession
will be used before it is discarded so that a new one will
be created to replace it. A value less than or equal to 0 disables
this feature.