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

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