ZCube Rule Engine: Modeling, Execution, and Practical Integration

The article introduces ZCube, a rule engine designed to address the need for flexible business rule customization in membership and marketing platforms, highlighting its role as a key solution for dynamic rule management.

It outlines the development of a custom rule engine called ZCube, which includes a visual rule modeling designer (supporting script‑based and wizard‑based designs), high‑availability architecture, and capabilities for packaging multiple rules into knowledge bundles for gray‑release, full‑release, version control, and health monitoring.

Integration steps are described: first, adding the ZCube SDK dependency via Maven, then invoking the rule execution API, followed by an AB testing deployment strategy to ensure stability while rolling out new rule logic.

Key code snippets include the Maven dependency:

<!--规则引擎客户端SDK -->
<dependency>
    <groupId>***.rule.*</groupId>
    <artifactId>rule-core-client-spring</artifactId>
    <version>1.0.1-SNAPSHOT</version>
</dependency>

and the API call:

RuleExecutionResultruleExecutionResult = ruleExecuteService.fireRules(knowPackageName, param);

The article then delves into the core principles of ZCube, starting with rule modeling. It explains two modeling approaches:

Script‑based modeling using a DSL defined with ANTLR (lexer and parser grammars are provided).

Wizard‑based modeling that generates XML configurations representing the rule logic.

For the script‑based approach, the ANTLR lexer grammar is shown:

lexergrammar ZCubeLexer;
//常用函数
COUNT : 'count';
AVG : 'avg';
... //数据类型
Datatype : 'String' | 'int' | 'Integer' | 'double' ... ;
//操作符
GreaterThen : '>'|'\u5927\u4e8e';
GreaterThenOrEquals : '>='|'\u5927\u4e8e\u7b49\u4e8e';
LessThen : '<'|'\u5c0f\u4e8e';
LessThenOrEquals : '<='|'\u5c0f\u4e8e\u7b49\u4e8e';
Equals : '=='|'\u7b49\u4e8e';
...

and the corresponding parser grammar:

grammar ZCubeParser;
import ZCubeLexer;
Def : ('rule'|'\u89c4\u5219') STRING attribute* left right other? ('end'|'\u7ed3\u675f') ';' ;
attribute : loopAttribute | salienceAttribute | effectiveDateAttribute | expiresDateAttribute ;
left : ('if'|'\u5982\u679c') condition? ;
condition : leftParen condition rightParen #parenConditions ;
leftParen : '(';
rightParen : ')';
right : ('then'|'\u90a3\u4e48') action* ;
other : ('else'|'\u5426\u5219') action* ;
action : outAction ';'? | methodInvoke ';'? ;
outAction : 'out' '(' complexValue ')';
methodInvoke : beanMethod '(' actionParameters? ')';
...

A Java method that builds the rule set from a script is also presented:

public ZCubeSet build(String script) throws IOException{
  ANTLRInputStream antlrInputStream = new ANTLRInputStream(script);
  ZCubeParserLexer lexer = new ZCubeParserLexer(antlrInputStream);
  CommonTokenStream tokenStream = new CommonTokenStream(lexer);
  ZCubeParserParser parser = new ZCubeParserParser(tokenStream);
  BuildZCubesVisitor visitor = new BuildZCubesVisitor(contextBuilders, tokenStream);
  ZCubeSet ZCubeSet = visitor.visitZCubeSet(parser.ZCubeSet());
  rebuildZCubeSet(ZCubeSet);
  String error = errorListener.getErrorMessage();
  if(error != null){
    throw new ZCubeException("Script parse error:" + error);
  }
  return ZCubeSet;
}

The article explains how the parsed script is transformed into a collection of Rule objects (with fields such as name, lhs, rhs, other) and then compiled into a RETE network consisting of type nodes, criteria (atomic) nodes, junction (AND/OR) nodes, and terminal nodes.

For the wizard‑based approach, the XML schema for LHS, RHS, and other elements is detailed, showing how visual configuration maps to XML tags like <if> , <and> , <or> , <atom> , and how actions are represented with <execute-function> and <console-print> .

Execution flow is then described: a session is created from a knowledge package, facts are inserted, the RETE network is instantiated, and pattern matching proceeds node by node using cached left/right part values in a work memory. Matching results are placed into an agenda with three groups (execution, mutex, default) that determine rule firing order based on priority and focus flags.

Finally, the article summarizes the advantages of ZCube: rule count does not affect matching speed due to RETE, efficient handling of low‑frequency fact changes, and memory‑based caching for rapid evaluation, making it suitable for high‑performance business rule scenarios.