public final class Rule extends java.lang.Object implements RuleListElement
As the pattern recognition engine processes an AST, it applies rules
in a RuleSet
to various nodes in the tree. A rule's condition
expression is executed to determine whether that rule's actions need to
be executed. A symbol resolver uses the data stored in an AST object to
supply the information needed by the condition expression during
expression. This data is exposed to user expressions via libraries
registered by PatternWorker
implementations.
An expression used for the rule's condition may contain any combination
of variables and user functions, so long as the final operation of the
expression resolves to a boolean result. It is this boolean result which
determines whether any of the rule's actions/nested rules will be executed.
Actions and nested rules can be set to register on either a
true
or false
result from the condition
expression.
Action expressions will typically contain a user function to act as a callback or hook to some processing, since variables and simple operators cannot be made to perform any task beyond simple evaluation to a boolean or numeric result. The value returned by an action is always ignored.
Rules are used in multiple ways. By embedding an action as a function in
a rule's condition expression, one can perform some desired functionality
unconditionally. This is in fact how a RuleSet
's initialization
and termination rules are typically used, though they are not limited to
this use.
By nesting rules within rules, one can build up an arbitrary set of control flow to match specific application requirements.
Using the loop
instance member, this rule can be converted
into a while
loop instead of the default if/else
control structure. Please see apply(int)
for more details.
RuleSet
,
AstSymbolResolver
Modifier and Type | Class and Description |
---|---|
private static class |
Rule.BreakException
Specialized exception type thrown by a break action to terminate a
loop within a while rule.
|
private static class |
Rule.ContinueException
Specialized exception type thrown by a continue action to continue a
loop within a while rule.
|
private class |
Rule.ExceptionAction
Abstract base class for specialized action implementations which throw
an exception when applied.
|
Modifier and Type | Field and Description |
---|---|
private Expression |
condition
Logical expression which forms the condition of this rule
|
private java.util.List<RuleListElement> |
falseActions
List of actions/rules to trigger if rule's condition is not met
|
private java.lang.String |
file
The file this rule is defined in, used for tracing.
|
private int |
line
The file line this rule is defined at, used for tracing.
|
private boolean |
loop
If
true this rule acts as a WHILE instead as an IF. |
private java.util.List<RuleListElement> |
trueActions
List of actions/rules to trigger if rule's condition is met
|
private int |
type
Type of rule from
RuleContainer constants |
Constructor and Description |
---|
Rule(java.lang.String infix,
int type)
Constructor which accepts a resolver and an expression which represents
the condition of this rule.
|
Rule(java.lang.String infix,
int type,
java.lang.String file,
int line)
Constructor which accepts a resolver and an expression which represents
the condition of this rule.
|
Modifier and Type | Method and Description |
---|---|
void |
addAction(java.lang.String infix,
boolean trigger,
java.lang.String file,
int line)
Add an action to be executed in the event this rule's condition
evaluates to
trigger . |
void |
addBreak(boolean trigger)
Add a break action to be executed in the event this rule's condition
evaluates to
trigger . |
void |
addContinue(boolean trigger)
Add a continue action to be executed in the event this rule's condition
evaluates to
trigger . |
void |
addRule(RuleListElement rule,
boolean trigger)
Add a nested
Rule to be executed in the event this rule's
condition evaluates to trigger . |
void |
apply(int type)
Apply this rule (if and only if this rule's type matches the specified
type) by evaluating its condition expression and executing
the appropriate list of actions, based upon the result of evaluating
the rule's condition.
|
void |
cleanup()
Termination hook to allow resources to be cleaned up when this object is
about to go out of service.
|
private java.lang.String |
composeAstString(Aast ast)
Compose and return a string which represents the contents of an AST.
|
private void |
coreProcessing(java.lang.Object result)
Centralizes the core processing of this rule so that multiple types
of control flow construct can be implemented externally but the common
processing can be shared.
|
(package private) java.lang.String |
createReport()
Create a simple report which describes the current state of this rule.
|
private java.lang.String |
createReportFooter()
Create a standard footer which is appended to a report describing the
current state of this rule.
|
private java.lang.String |
createReportHeader()
Create a simple report header which describes the current state of this
rule.
|
private void |
executeActions(java.util.List<RuleListElement> actions)
Execute all actions/rules in the specified list, in order, discarding
results of the action expressions themselves.
|
boolean |
getLoop()
Gets the state variable for whether this rule acts as a WHILE instead
of as an IF.
|
private java.lang.String |
getRuleTypeName()
Debug helper method to get the descriptive name of this rule's type.
|
(package private) int |
getType()
Get the rule type; one of the
RuleContainer constants. |
boolean |
hasType(int type)
Indicates whether this object either represents a rule of the specified
type.
|
boolean |
isContainer()
Reports that this instance is NOT rule container.
|
void |
setLoop(boolean loop)
Sets the state variable for whether this rule acts as a WHILE instead
of as an IF.
|
private Expression condition
private java.util.List<RuleListElement> trueActions
private java.util.List<RuleListElement> falseActions
private int type
RuleContainer
constantsprivate boolean loop
true
this rule acts as a WHILE instead as an IF.private java.lang.String file
private int line
public Rule(java.lang.String infix, int type)
infix
- A logical (boolean) expression, in infix notation, which
defines the condition which will trigger this rule's action(s)
to be executed.type
- Type of rule from RuleContainer
constants.apply(int)
public Rule(java.lang.String infix, int type, java.lang.String file, int line)
infix
- A logical (boolean) expression, in infix notation, which
defines the condition which will trigger this rule's action(s)
to be executed.type
- Type of rule from RuleContainer
constants.file
- The file this rule is defined in, used for tracing.line
- The file line this rule is defined at, used for tracing.apply(int)
public void setLoop(boolean loop)
loop
- If true
, this is a WHILE loop.public boolean getLoop()
true
, this is a WHILE loop.public void addAction(java.lang.String infix, boolean trigger, java.lang.String file, int line)
trigger
. This action is added to the end of
the list of such actions to be performed, and it will be executed in the
order of that list. The list is lazily created.infix
- An expression, in infix notation, which defines an action to
execute if the specified condition evaluates to the value
specified by trigger
. This typically consists
of one or more user functions.trigger
- The boolean result of evaluating this rule's condition which
should trigger this action. That is, if true
, the
action will be triggered only if the condition evaluates to
true
. If false
, the action will be
triggered only if the condition evaluates to
false
.file
- The file the action is defined in, used for tracing.line
- The file line the action is defined at, used for tracing.apply(int)
public void addRule(RuleListElement rule, boolean trigger)
Rule
to be executed in the event this rule's
condition evaluates to trigger
. This rule is added to the
end of the list of such actions/rules to be performed, and it will be
executed in the order of that list. The list is lazily created.rule
- The rule to execute if the specified condition evaluates to
the value specified by trigger
.trigger
- The boolean result of evaluating this rule's condition which
should trigger this action. That is, if true
, the
rule will be triggered only if the condition evaluates to
true
. If false
, the rule will be
triggered only if the condition evaluates to
false
.apply(int)
public void addBreak(boolean trigger)
trigger
. This action is added to the end of
the list of such actions to be performed, and it will be executed in the
order of that list. The list is lazily created.
Upon execution of the break action, a Rule.BreakException
is
thrown.
trigger
- The boolean result of evaluating this rule's condition which
should trigger this action. That is, if true
, the
action will be triggered only if the condition evaluates to
true
. If false
, the action will be
triggered only if the condition evaluates to
false
.apply(int)
public void addContinue(boolean trigger)
trigger
. This action is added to the end of
the list of such actions to be performed, and it will be executed in the
order of that list. The list is lazily created.
Upon execution of the break action, a Rule.ContinueException
is
thrown.
trigger
- The boolean result of evaluating this rule's condition which
should trigger this action. That is, if true
, the
action will be triggered only if the condition evaluates to
true
. If false
, the action will be
triggered only if the condition evaluates to
false
.apply(int)
public void apply(int type)
true
, all "on true" actions defined for this rule are
executed, in the order in which they were added, regardless of the
success of any action previously executed in the list. If the condition
evaluates to false
, all "on false" actions defined for
this rule are executed, in the order in which they were added,
regardless of the success of any action previously executed in the
list.
If the loop instance member is true
, the core processing
will be executed multiple times as long as the return value of the
condition expression is not null
and the return type
is a Boolean
. If the loop member is false
,
the core processing is essentially an IF/ELSE construct. It is
important to note that any falseActions
WILL NOT EVER be
executed if loop
is true
since actions
are only processed in the WHILE loop when the condition is
true
.
If trace level debugging is enabled, a rule report is emitted to
stdout
for debug purposes. This includes the current
source and copy AST set in the symbol resolver, as well as details
about the condition expression and each action which is executed in
the course of applying this rule.
apply
in interface RuleListElement
type
- Type of rule for which to apply: init, walk, or post, using
the RULE_*
constants.public boolean hasType(int type)
hasType
in interface RuleListElement
type
- Type of rule for which to search: init, walk, or post, using
the RULE_*
constants.true
if the object is a rule of the specified
type, else false
.public boolean isContainer()
isContainer
in interface RuleListElement
false
.public void cleanup()
Cascades to all RuleListElement
s managed by this rule.
cleanup
in interface RuleListElement
int getType()
RuleContainer
constants.java.lang.String createReport()
private java.lang.String createReportHeader()
private java.lang.String createReportFooter()
private void coreProcessing(java.lang.Object result)
result
- The return value from the condition expression of this rule.private void executeActions(java.util.List<RuleListElement> actions)
actions
- The list of actions/rules to be executed, either
trueActions
(if the rule's condition evaluated to
true
), or falseActions
(if the rule's
condition evaluated to false
).private java.lang.String composeAstString(Aast ast)
This text is used in the rule report generated for debug purposes.
ast
- AST on which the string is based.private java.lang.String getRuleTypeName()