Package oracle.rules.rl.extensions.pool

Class RuleSessionPool

java.lang.Object
oracle.rules.rl.extensions.pool.RuleSessionPool
public class RuleSessionPool extends 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

    Fields
    Modifier and Type
    Field
    Description
    static final int
    INITIAL_SIZE
    The default number of RuleSession instances created initially.
    static final int
    SOFT_MAXIMUM_SIZE
    The default soft upper limit on the size of the pool.

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    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(List<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 Details

    • INITIAL_SIZE

      public static final int INITIAL_SIZE
      The default number of RuleSession instances created initially.
      See Also:

    • SOFT_MAXIMUM_SIZE

      public static final int SOFT_MAXIMUM_SIZE
      The default soft upper limit on the size of the pool.
      See Also:

  • Constructor Details

    • RuleSessionPool

      public RuleSessionPool(List<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(List<String> rl, 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(List<String> rl, 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 Details

    • 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(List<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()