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

 function resetHook() returns boolean
 {
     // additional initialization code here
     return true;
 }

 boolean resetComplete = resetHook();
 

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.

 RuleDictionary rd;
 // Code to load rule dictionary not shown
 List rlList = new ArrayList();
 rlList.add(rd.dataModelRL());
 List rulesetAliases = rd.getRuleSetAliases(true);
 for (String alias : rulesetAliases)
 {
     rlList.add(rd.ruleSetRL(alias));
 }

 RuleSessionPool pool = new RuleSessionPool(rlList);
 

To execute rules, a RuleSession is obtained from the pool and then returned once execution is complete. The code example below demonstrates this.

 PoolableObject<RuleSession> po = pool.getPoolableRuleSession();
 RuleSession engine = po.getPooledObject();
 // use the RuleSession to execute rules as required here
 pool.returnPoolableRuleSession(po);
 

Field Summary

static int	INITIAL_SIZE The default number of RuleSession instances created initially.
static int	SOFT_MAXIMUM_SIZE The default soft upper limit on the size of the pool.

Constructor Summary

RuleSessionPool(java.util.List<java.lang.String> rl)
Construct a RuleSession pool given a list of RL text.

RuleSessionPool(java.util.List<java.lang.String> rl, java.util.Map config)
Construct a RuleSession pool given a list of RL text.

RuleSessionPool(java.util.List<java.lang.String> rl, java.util.Map config, int initialSize, int softMaximumSize)
Construct a RuleSession pool given an initial size and a list of RL text.

Method Summary

long	getCreated() Returns the total number of poolable RuleSession objects that have been created by this pool.
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.
int	getFree() Returns the number of free poolable RuleSession objects available for use.
int	getInitialSize() Returns the initial size for this pool.
int	getInuse() Returns the number of RuleSession objects from this that are currently in use.
int	getMaximumSessionUsage() Gets the current maximum RuleSession usage count.
PoolableObject<RuleSession>	getPoolableRuleSession() Gets a RuleSession poolable object to the pool.
long	getReclaimed() Returns the total number of RuleSession objects that have been reclaimed.
long	getRetired() Returns the total number of RuleSession objects that have been retired because the usage exceeded the specified maximum usage for a RuleSession.
int	getSize() Returns the number of poolable RuleSession objects associated with this pool.
int	getSoftMaximumSize() Returns the soft maximum size for this pool.
long	getUsage() Returns the total number of times a poolable RuleSession has been acquired from this pool.
boolean	isUsingPeers()
void	refreshPool(java.util.List<java.lang.String> rl) Refresh a RuleSession pool with new RL.
void	returnPoolableRuleSession(PoolableObject<RuleSession> po) Returns a RuleSession poolable object to the pool.
void	setMaximumSessionUsage(int value) Sets the maximum RuleSession usage count.

Methods inherited from class java.lang.Object

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

Field Detail

INITIAL_SIZE

public static final int INITIAL_SIZE

The default number of RuleSession instances created initially.

See Also:

Constant Field Values

SOFT_MAXIMUM_SIZE

public static final int SOFT_MAXIMUM_SIZE

The default soft upper limit on the size of the pool.

See Also:

Constant Field Values

Constructor Detail

RuleSessionPool

public RuleSessionPool(java.util.List<java.lang.String> rl)
                throws RLException

Construct a RuleSession pool given a list of RL text. This constructor specifies the defaults for the initial poolsize and the soft maximum size.

Parameters:

rl - the list of RL text.

Throws:

RLException - if an error occurs.

RuleSessionPool

public RuleSessionPool(java.util.List<java.lang.String> rl,
                       java.util.Map config)
                throws RLException

Construct a RuleSession pool given a list of RL text. This constructor specifies the defaults for the initial poolsize and the soft maximum size.

Parameters:

rl - the list of RL text.

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

Throws:

RLException - if an error occurs.

RuleSessionPool

public RuleSessionPool(java.util.List<java.lang.String> rl,
                       java.util.Map config,
                       int initialSize,
                       int softMaximumSize)
                throws RLException

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.

Throws:

RLException - if an error occurs.

Method Detail

returnPoolableRuleSession

public void returnPoolableRuleSession(PoolableObject<RuleSession> po)
                               throws RLException

Returns a RuleSession poolable object to the pool.

Parameters:

po - the poolable object

Throws:

RLException - if an error occurs.

getPoolableRuleSession

public PoolableObject<RuleSession> getPoolableRuleSession()
                                                   throws RLException

Gets a RuleSession poolable object to the pool.

Returns:

the poolable object

Throws:

RLException - if an error occurs.

refreshPool

public void refreshPool(java.util.List<java.lang.String> rl)
                 throws RLException

Refresh a RuleSession pool with new RL.

Parameters:

rl - the list of RL text.

Throws:

RLException - if an error occurs.

getInitialSize

public int getInitialSize()

Returns the initial size for this pool.

Returns:

the initial size for this pool

getSoftMaximumSize

public int getSoftMaximumSize()

Returns the soft maximum size for this pool.

Returns:

the soft maximum size for this pool

getSize

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

Parameters:

value - the new maximum usage count

getMaximumSessionUsage

public int getMaximumSessionUsage()

Gets the current maximum RuleSession usage count.

Returns:

the maximum RuleSession usage count

isUsingPeers

public boolean isUsingPeers()