Structure of a Rulebase
A rulebase object is primarily composed of a set of rule objects. Each rule has a Data Source and a list of Test objects. Each Test has a TestExpressionOperator object and a list of ConsequenceAction objects. Thus, a rulebase can be represented as a tree structure with a single Rulebase object as the root and Action objects as the leaves.
RuleBaseElement Class
The RulebaseElement class is the super class of the following classes:
• | Rulebase |
• | Rule |
• | Test |
• | Action |
The RulebaseElement
class provides common methods to get and set the element's name and schedule parameters. The Rule, Test and Action classes do not require a name to be specified in the constructor. Only the Rulebase class requires a name specified in the constructor. In places where an array of RulebaseElement objects is required, all elements in the array must have unique names.
These includes the constructors for:
• | Rulebase (requires array of Rule) |
• | Rule (requires array of Test) |
• | Test (requires array of Action) |
and the following methods:
• | Rulebase.setRules() |
• | Rule.setTests() |
• | Test.setConsequenceActions() |
• | Test.setClearActions() |
Rule Class
A Rule consists of a data source and a list of tests. The DataSource of a rule specifies a MethodSubscription, which supplies a stream of data samples to be monitored. The method used in the MethodSubscription can be either synchronous or asynchronous. Every new data sample from a Rule Object 's Data Source is distributed to all Test objects contained within that Rule object.
For more information on MethodSubscription refer to the Console API .
DataSource Class
The data source for a Rule is its source of input data, and is always a method subscription to a microagent. The data source of a Rule provides information about some condition on a managed node. After information is received, one or more tests are applied to evaluate it. The MethodSubscription
of a data source provides a stream of data objects.
The microAgentName
and the method name used to construct the DataSource can be obtained from MicroAgentDescriptor
and MethodDescriptor
, respectively.
The MicroAgentDescriptor which is used to construct the MethodSubscription defines the type of data the subscription will yield.
This data will be one of the following OpenData types:
• | String |
• | Char |
• | Boolean |
• | Byte |
• | Short |
• | Integer |
• | Long |
• | Float |
• | Double |
• | CompositeData |
• | TabularData (represents a table composed of rows uniquely indexed by uniformly structured CompositeData objects) |
Test Class
Tests define the tests which are performed on the rule's data source and what actions to take. Each test uses the data to compute a true or false value which is used in determining when to trigger actions. Test objects have a state that is either true or false. The initial state of a new Test object is false. State transitions are caused by evaluating the received data based on the specified conditions and the policies of the test. The possible Test object state transitions are:
• | false to false (F->F) |
• | false to true (F->T) |
• | true to false (T->F) |
• | true to true (T->T) |
All Test
object state transitions cause its ConsequenceAction
objects to be evaluated. The policy of the ConsequenceAction
objects govern whether an evaluation results in an action execution. The ClearAction
objects are a list of actions that will be executed when the Test
object undergoes the T->F transition.
State transitions resulting from the receipt of data start with an evaluation of the TestExpressionOperator against the data. The resulting true or false value of the TestExpression, in conjunction with the Test object's TrueConditionPolicy and ClearConditionPolicy, determines the type of Test object state transition, as follows:
• | F->F and T->T Test Object StateTransitions |
If the previous state of the Test object was false and the current evaluation of the Test Expression is false, then the Test object undergoes a F->F transition.
If the previous state of the Test object was true and the current evaluation of the TestExpression is true, then the Test object undergoes a T->T transition.
These two transitions are not affected by the true or clear policy.
• | F->T Test Object State Transitions |
This transition is governed by the TrueConditionPolicy.
The policy TrueCountThreshold specifies how many sequential true evaluations of the TestExpression must occur before the Test object transitions F->T.
• | T->F Test Object Transitions - "Clearing" the Test object |
This transition is governed by the ClearConditionPolicy. This transition is synonymous with "Clearing" the Test object.
The policy FirstFalse indicates that the T->F transition should occur upon the first false evaluation of the TestExpression operator. This is the default ClearConditionPolicy.
The policy ClearTimer indicates the number of seconds which must elapse without a true evaluation of the TestExpression before the T->F occurs. A T->F transition caused as a result of a clear timer expiration occurs independently of the Test object's receipt of data.
The ClearTest policy specifies an additional test expression (clear test expression), which governs when the T->F transition occurs. The Clear Test Expression receives data each time the Test object receives data. It will cause a T->F transition of the Test object if (the current state of the Test object is true and) the clear test expression evaluates to true.
TestExpressionOperators Class
TestExpressionOperator are created using the Operator class. The static method Operator.getOperatorDescriptors() returns a list of descriptors describing all available operators. Using the information in the OperatorDescriptor, you can then build instances of the Operator class by supplying the operator name and a list of operands. The operands you supply must be of the same number and type as those specified by the corresponding descriptor. An operand of an operator may itself be another operator, as long as its stated return type matches the operand position it occupies. Operators can thus be nested to form more complex operators.
Although operators can return different types, only those which return a Boolean value may be used in tests (i.e. as arguments to Test.setTestExpressionOperator
() ). The other non-Boolean operators are used only as nested operators.
Test operators access the rule's data source through the COM.TIBCO.hawk.config.rbengine.rulebase.operators.getRuleData operator. This operator takes a name and returns the associated data. As described, if a data source produces TabularData then that data is decomposed into CompositeData objects before seen by the tests and thus the getRuleData operator. The name parameter to this operator references the corresponding data element of the CompositeData object which is then returned by the getRuleData operator. If the data source produces one of the remaining OpenData types (String, Char, Boolean, Byte, Short, Integer, Long, Float, Double) then that value is accessible via the getRuleData operator using the name assigned to the return type in the MethodDescriptor for this data source.
ConsequenceAction Class
The ConsequenceAction object extends the Action object. The Test object invokes its ConsequenceAction objects each time the Test object makes a state transition. The type of transition along with the ConsequenceAction object's PerformActionPolicy and EscalationPeriod determines whether or not the action is executed.
A True Series of transitions is defined as a series of transitions that begins with F->T and is followed by one or more T->T transitions. A T->F marks the end of a true series but is not part of it.
Actions are not enabled during an entire true series. The EscalationPeriod specifies the number of seconds that must elapse since the start of a true series before the action becomes enabled. An EscalationPeriod of 0 indicates that the action is always enabled. Actions may only execute when enabled.
The PerformActionPolicy controls how many times and how often the action executes during a true series, after the action has been enabled.
The PerformOnceOnly policy causes the action to be executed only once during a true series. An exception to this rule involves variable substitution. If variable substitution would result in a different action than the last one that has executed within the current true series (For example, raise an alert with different text), then the action will also be re-executed on the current T->T transition.
The PerformAlways policy causes the action to be executed upon every evaluation within a true series (after the action has become enabled).
The PerformCountOnInterval policy is more involved. It causes the action to be executed at the start of a true series (or as soon as it becomes enabled), and on subsequent evaluations within the same series that occur at a time greater than Y seconds since the last action execution within the current true series. This continues until the action has executed for a maximum of X times within the current true series.