com.tibco.cep.runtime.session

## Interface RuleSession

-     public interface RuleSession

  The RuleSession is the interface which interacts with the kernel of the engine. It allows the programmer to assert objects and evaluate rules.

  The programmer gets access to an initialized `RuleSession` in one of the following ways:

  - `RuleSessionManager.getCurrentRuleSession()`
  - `RuleServiceProvider.getRuleRuntime().getRuleSession(somename)`

  These mechanisms are very different and have different meanings.

  The first one is used when coding a custom function. Since the custom function is evaluated as a callback while evaluating/executing a rule, the session is well known, so the programmer get access to the `RuleSession` whitin which the function is operating.

  The second mechanism is used when the programmer is managing the lifecycle of the `RuleSession`'s.

  A rule evaluation cycle (RTC) is:

  - Test all the rules that match a condition for the fact that got asserted.
  - Create a rule agenda for all the rules ready to be fired - a rule in which all conditions are true is considered to be ready
  - Select the top rule based on rule priority as specified during designtime.
  - Execute the actions associated to the rule.
  - The action may change the agenda by modifying/asserting/deleting facts, which in turn causes the system to reevaluate the agenda.
  - The Run To Completion ends when there are no agenda items and the system is in equilibrium.

  The rule session is always stateful, i.e. it always maintains the state of the instances asserted across multiple RTCs. The programmer can call `assert(object, true)` multiple times with different objects. To create an object use the the `TypeManager` factory and pass the object fact type (concept/event/scorecard) which was created in TIBCO Designer. Set the object's property values using standard `setProperty` methods.

  Stateless behavior can be achieved by calling `reset` on the `RuleSession` after every RTC.

  The RTC is evaluated on the caller's thread when an assert is invoked with execute permission. At this point, the rule session is set as a ThreadLocal on the caller's thread, so it is available to every function/custom function which is invoked as a result of an action fired or condition evaluated.

  Since:
    2.0.0

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `assertObject(java.lang.Object object, boolean executeRules)` Adds an object to the Rule Session and optionally executes all the triggered rules (conflict resolve / executeRules is called).
    `void` | `executeRules()` Executes rules that are triggered by previous actions (Add, Update, Remove Object).
    `RuleSessionConfig` | `getConfig()` Gets the configuration parameters used for building this `RuleSession`.
    `java.lang.String` | `getName()` Returns the name of this `RuleSession`.
    `java.util.List` | `getObjects()` Gets all the simple events, concepts and scorecards present in this Session.
    `RuleRuntime` | `getRuleRuntime()` Gets the manager (parent) who created this session.
    `RuleServiceProvider` | `getRuleServiceProvider()` Returns the `RuleServiceProvider` associated with this session.
    `java.lang.Object` | `invokeCatalog(java.lang.String functionFQName, java.lang.Object[] args)`
    `java.lang.Object` | `invokeFunction(java.lang.String functionURI, java.lang.Object[] args, boolean synchronize)` Invoke a RuleFunction on this `RuleSession`.
    `void` | `retractObject(java.lang.Object object, boolean executeRules)` Removes an object from the session.
    `void` | `setActiveMode(boolean active)` Sets the ActiveMode of this `RuleSession`.

- - ### Method Detail

    - #### getName

          java.lang.String getName()

      Returns the name of this `RuleSession`. This is the same as the name of the corresponding BusinessEvents Archive Resource specified in TIBCO Designer.
      Returns:
        the name of this `RuleSession`.
      Since:
        2.0.0

    - #### getConfig

          RuleSessionConfig getConfig()

      Gets the configuration parameters used for building this `RuleSession`.
      Returns:
        the configuration parameters used for building this `RuleSession`.
      Since:
        2.0.0

    - #### executeRules

          void executeRules()

      Executes rules that are triggered by previous actions (Add, Update, Remove Object).
      Since:
        2.0.0
      See Also:
        `RuleSession.assertObject(Object, boolean)`

    - #### getObjects

          java.util.List getObjects()

      Gets all the simple events, concepts and scorecards present in this Session.
      Returns:
        a List of `SimpleEvent` or `Concept`.
      Throws:
        `java.lang.Exception`
      Since:
        2.0.0

    - #### assertObject

          void assertObject(java.lang.Object object,
                            boolean executeRules)
                     throws DuplicateExtIdException

      Adds an object to the Rule Session and optionally executes all the triggered rules (conflict resolve / executeRules is called).
      Parameters:
        `object` - the object to assert.
        `executeRules` - determines if conflict resolution will happen after asserting the object.
      Throws:
        `DuplicateExtIdException` - if the external ID of the object to assert already exist in the session.
      Since:
        2.0.0

    - #### retractObject

          void retractObject(java.lang.Object object,
                             boolean executeRules)

      Removes an object from the session.
      Parameters:
        `object` - or the handle of the object.
        `executeRules` - determines if conflict resolution will happen after retracting the object.
      Since:
        2.0.0

    - #### getRuleRuntime

          RuleRuntime getRuleRuntime()

      Gets the manager (parent) who created this session.
      Returns:
        the `RuleRuntime` object which is the manager who created this session.
      Since:
        2.0.0

    - #### getRuleServiceProvider

          RuleServiceProvider getRuleServiceProvider()

      Returns the `RuleServiceProvider` associated with this session.
      Returns:
        the `RuleServiceProvider` associated with this session.
      Since:
        2.0.0

    - #### setActiveMode

          void setActiveMode(boolean active)

      Sets the ActiveMode of this `RuleSession`.
      Parameters:
        `active` - activate the ruleSession or not.
      Since:
        2.0.0

    - #### invokeFunction

          java.lang.Object invokeFunction(java.lang.String functionURI,
                                          java.lang.Object[] args,
                                          boolean synchronize)

      Invoke a RuleFunction on this `RuleSession`.
      Parameters:
        `functionURI` - the URI of the RuleFunction to be invoked
        `args` - an Object array specifies the input arguments
        `synchronize` - tells whether to execute the RuleFunction inside the RuleSession OR execute externally and apply newly created and deleted instance(s) to the RuleSession. Modify a Concept instance is not allow if this parameter is set to true or the engine will throw a RuntimeException.
      Returns:
        the result of the RuleFunction
      Since:
        3.0.2

    - #### invokeCatalog

          java.lang.Object invokeCatalog(java.lang.String functionFQName,
                                         java.lang.Object[] args)

      Parameters:
        `functionFQName` - the fully qualified Catalog function name to be invoked i.e. "System.debugOut"
        `args` - a variable argument specifying the input arguments
      Returns:
        the result of the Catalog function
      Since:
        5.2