IKEXPRESSIONV2.0简易表达式解析器使用说明.doc

1、IKExpressionV2.0.5 简易表达式解析器使用说明目录1. IK 表达式介绍（IK Expression Introduction） 22. 快速入门（Quick Start） .63. 表达式公式规范（Expression Formula Specification） .114. 高级特性（Advance） 181. IK 表达式介绍（IK Expression Introduction）IK Expression 是一个开源的（OpenSource ） ，可扩展的（Extensible ） ，基于 java 语言开发的一个超轻量级（Super lightweight）的公式化语

2、言解析执行工具包。IK ExpressionV2.0.5 不依赖于任何第三方的 java 库。它做为一个简单的jar，可以集成于任意的 Java 应用中。这包括了 JavaEE 应用（基于应用服务器的） ， Java 桌面应用以及 Java WebStart 方式的应用。IK Expression 最初诞生的原因是为了能增强工作流引擎，如 jBPM 等对流程配置的灵活度。使其能在流程运行期获得同配置期一样灵活地对执行逻辑条件进行变更。经过扩展后的 IK Expression 还可以适用于各种常规业务系统的动态条件配置，如需要图形化配置应用的场合，或是模拟 Excel 电子表格的公式运算的场景。

3、同 EL 和 BeanScript 不同，IK Expression 的设计目标是面向最终用户的，因此它被设计成语法简单（像数学算式） ，通俗易懂（支持中文变量及函数名）但功能有限的解析引擎。如果你需要一个功能强大的表达式引擎，也许 IK Expression 并不是最好的选择。1.1 概要（OverView）IK Expression 是一个采用逆波兰式算法结合指针栈优化的公式解析引擎，它由表达式编译、 、表达式执行、变量容器、以及函数配置管理四部分构成。它具有以下特点： 支持基础运算符+ - / % 逻辑运算符！ args0 = “IK Expression“;/定义表达式String e

4、xpression = “Hello World “ + 用户名“;/给表达式中的变量“用户名”付上下文的值List variables = new ArrayList();variables.add(Variable.createVariable(“用户名“, args0);/执行表达式Object result = ExpressionEvaluator.evaluate(expression, variables);System.out.println(“Result = “ + result); 执行结果： Result = Hello World IK ExpressionAPI 说

5、明 类 org.wltea.expression.ExpressionEvaluator方法 1： public static Object evaluate(String expression, Collection variables)说明：传入表达式和表达式上下文的变量，执行表达式返回结果参数 1 ：String expression, 要传入执行的表达式参数 2 ：Collection variables 表达式上下文的变量集合（详细请看类 org.wltea.expression.datameta.Variable 的说明） 。返回值：表达式执行结果，可能是以下类型的 java 对象

6、中的一种：Int、Long、Float、Double 、Boolean 、String 、Date、List 、Object。方法 2： public static Object evaluate(String expression)说明：对方法 1 的重载，执行简单的没有变量的表达式。请参考方法 1 说明. 方法 3：public static String compile(String expression, Collection variables) throws IllegalExpressionException说明：传入表达式和表达式上下文的变量，对表达式进行语法编译测试，返回逆波

7、兰式表示。参数 1 ：String expression, 要传入执行的表达式参数 2 ：Collection variables 表达式上下文的变量集合（详细请看类 org.wltea.expression.datameta.Variable 的说明） 。返回值：表达式的逆波兰式表示异常：编译器将尽力的告知用户，表达式语法错误的位置方法 4： public static String compile(String expression)throws IllegalExpressionException说明：对方法 3 的重载，编译简单的没有变量的表达式。请参考方法 3 说明. 类 org.w

8、ltea.expression.datameta.Variable该类是用来表示表达式的上下文变量的，上面的例子中用到了别名为“用户名”的上下文变量，这是也是表达式最有用的地方。例如，在 jBPM 的流程定义中，我们需要定义一个报销审批流程中，用来决定流程分支走向的表达式：（申请金额 10000）？“总经理审批”：“部门经理审批”这里需要定义一个别名为“申请金额“变量。变量通过 evaluate(String expression, Collection variables)方法中的 variables 参数传入表达式中。而 Variable 类型变量的构造十分的简单，它是标准的 POJO。方

9、法 1： public static Variable createVariable(String varName , Object varValue)说明：根据参数别名和参数值，构造 Variable 实例参数 1 ：String varName, 参数的别名，可以是中文别名参数 2 ：Object varValue，参数的值 , 可以是下类型的 java 对象中的一种：Int、Long、Float、Double 、Boolean 、String 、Date、List 、Object。返回值：org.wltea.expression.datameta.Variable 类的实例方法 2：(直

10、接使用构造函数)public Variable(String varName , DataType varDataType , Object varValue)说明：根据指定的参数类型、参数别名和参数值，构造 Variable 实例参数 1 ：String varName, 参数的别名，可以是中文别名参数 2 ：DataType varDataType, 变量类型，它是org.wltea.expression.datameta. BaseDataMeta.DataType 枚举类型，包括的枚举值有:/NULL类型 DATATYPE_NULL ,/字符窜 DATATYPE_STRING ,/布尔

11、类 DATATYPE_BOOLEAN ,/整型数 DATATYPE_INT ,/长整型数 DATATYPE_LONG ,/浮点数 DATATYPE_FLOAT ,/双精度浮点 DATATYPE_DOUBLE ,/日期时间 DATATYPE_DATE ,/集合对象 DATATYPE_LIST,/通用对象类型 DATATYPE_OBJECT,参数 3 ：Object varValue，参数的值 , 可以是下类型的 java 对象中的一种：Int、Long、Float、Double 、Boolean 、String 、Date、List 、Object。返回值：org.wltea.expressio

12、n.datameta.Variable 类的实例3. 表达式公式规范（Expression Formula Specification）3.1 数据类型（Types, Values, and Variables）a) 数字型 ：i. 整形 integer ： -2321 ， 34234ii. 长整型 long ：3245235235Liii. 单精度浮点 float ： 342.555Fiv. 双精度浮点 double： 234234.3423b) 字符型：“a-zA-Z012456789”c) 布尔型：true 、falsed) 日期时间型：2008-08-08 或 2009-01-01 1

13、2:33:14e) 扩展类型：List 对象集合 （ 该类型不支持表达式字面定义，由操作符或函数运算结果生成 ）f) 通用对象：Object 类型 （ 该类型不支持表达式字面定义，由操作符或函数运算结果生成 ）3.2 运算符（Operators）运算符描述 符号 操作数个数 补充说明逻辑取反 ！ 一元 对布尔型取反运算取负（负号） - 一元 对所有数值型参数取负值算术乘 * 二元 支持数值型计算算术除 / 二元 支持数值型计算取余（模） % 二元 支持数值型计算加 + 二元 支持数值型计算 支持字符窜连接 所有类型的参数同字符串相加都转成字符串 遇到 null 型同字符串相加，忽略 null算

14、术减 - 二元 支持数值型计算小于 二元 支持数值型、日期型、字符型比较大等于 = 二元 支持数值型、日期型、字符型比较逻辑等 = 二元 支持数值型、日期型、字符型、Object型比较（注，对日期时间类型比较，误差精确到秒。对 Object 类型则依靠它的equals 实现） 支持 Null 同数值型、日期型、字符型、Object 型比较逻辑不等 ！= 二元 支持数值型、日期型、字符型比较 支持 Null 同数值型、日期型、字符型比较逻辑与 $SYSDATE 无 Date 当前系统日期（时间）,同 java 的new Date()$DAYEQUALS Date , Date Boolean 日

15、期相等比较2008-08-08 00:00:01与2008-08-08 23:59:59是同一天，将返回 true3.5 语法约束（Lexical Structure） 变量命名遵循 java 变量命名规范（如，不能以数字打头，不能用系统操作符打头等） 。 函数声明以“$”符号打头，自定义函数命名遵循 java 方法命名规范。 日期型常量使用“” 符号界定，格式为 yyyy-MM-dd 24h-mm-ss，不支持毫秒。 用户自定义函数别名不能重复。 （详细请参阅本文 4.1 章节） 用户自定义函数的参数和返回值类型限定于 3.1 章节描述的数据类型。 （详细请参阅本文 4.1 章节）3.6 公

16、式样例（Formula Example）1. +、 - 、* 、/ 、%（取模） 常规的算术运算，支持括号优先级 ：如：常见的 OA 中用于年休假工资计算公式3000 / 21.5 *（12 - 转正月份）/ 2 其中， “转正月份”可以是上下文变量2. 不同数据类型的字符串连接 ：“ABC”+（123+10） 运算结果 “ABC133”“ABC”+ 123 + 10 运算结果“ABC12310”“2009-08-08 + false + 123 + “a String“ + null”运算结果 “2009-08-08 00:00:00false123a String” （PS:忽略 null

17、型变量）3. = 223 运算结果 true 3-2.字符大小比较 : “1234”“223” 运算结果 fasle3-3.日期大小比较 : 2008-12-23 = 2008-08-08 true3-4 同 null 的 = 与 != 比较 ： 申请人!=null (其中， “申请人”为执行上下文的变量)4. 逻辑与、逻辑或、逻辑非运算： true & $DAYEQUALS(2008-01-01 , 2008-11-01) falsetrue | $DAYEQUALS(2008-01-01 , 2008-11-01) truetrue & ！$DAYEQUALS(2008-01-01 , 2

18、008-11-01) true5. 结果连接运算“#”：1000/10 # 2008-12-23$SYSDATE() # “ABC”+123 运算结果 包含 100 ， false ， “ABC123”三种不同类型对象的 List6. 函数与操作符混合、嵌套调用，如：$DAYEQUALS($CALCDATE( $SYSDATE() , 0 , 0 , (8+11-5*(6/3) * (2- 59 % 7) ,0 ,0,0 ),2009-10-01) 运算结果 false4. 高级特性（Advance）4.1 函数定制（Functions Customize）IK-Expression 最吸引人

19、的特性莫过于它允许你以非常简单的方式扩展你的自定义函数。IK-Expression 带有一个 xml 配置文件 functionConfig.xml。在使用 IK-Expression 时，该配置文件应放置于 class 的根目录中(如同 spring和 hibernate 等的配置文件一样) 。配置文件内部格式如下：functionConfig.xmljava.lang.Stringjava.lang.Stringjava.lang.Stringjava.lang.Stringjava.lang.Stringjava.lang.Stringjava.util.Dateintintintint

20、intintjava.util.Datejava.util.Date配置文件中默认配置了系统内部函数定义（在没有绝对必要的原因下，不建议修改系统默认函数配置） 。在默认配置的下方，用户可以定义自己的函数，格式如下：用户自定义函数配置123aajava.lang.String这里自定义了一个名称为“问好”的函数，它有一个 String 类型的参数。该函数映射对应于 org.wltea.expression.test.TestFunctions 类的 sayHello 方法，而类 org.wltea.expression.test.TestFunctions 具有一个构造函数，构造函数带有 Int

21、eger 型和 String 型的参数。配置中给出了构造函数的初始化参数“123”和“aa”。通过上述定义，用户就可以在表达式中使用该函数，如:$问好（当前用户） ， 其中“当前用户”为表达式的上下文变量。上述例子直观的展示了用户函数自定义的过程。下面，我们将系统的了解一下IK-Expression 的函数扩展定义规则和约束：1. 在 IK-Expression 中，函数直接对应于 java 的一个类的一个明确的方法。如：$CONTAINS 对应 org.wltea.expression.function.SystemFunctions 类的contains 方法；2. 所有的函数定义前，必须

22、先定义对应的 java 类。如果该类使用带参数的构造函数，则必须提供明确的构造参数，如：123aajava.lang.String3. java 类的加载和实例化在初始化阶段一次性完成。目前 IK-Expression 仅支持单例形式的加载，即对一个 java 类仅实例化一次。4. 定义函数时，必须明确定义函数对应 java 方法，以及 java 方法的参数类型和顺序，如：java.lang.Stringjava.lang.String你可以使用不同的函数名（英文的和中文的） ，对应相同的 java 方法，但对 java 中的方法重载必须使用不同的函数名对应( 即，IK-Expression

23、不支持函数名重载)5. 函数的参数和返回值只能是 IK-Expression 支持的数据类型(请参考 3.1 数据类型 章节).6. 为了增加灵活性，IK-Expression 给出了一个通过编码方式添加自定义函数的 static 方法。函数扩展 API 说明 类 org.wltea.expression.function.FunctionLoader方法 1： public static void addFunction(String functionName, Object instance, Method method)参数 1 ：String functionName, 要定义的函数名称（中英文皆可） 。参数 2 ：Object instance 函数要映射的 java 类的实例。参数 3 ：Method method 函数要映射的 java 类的方法对象。（全文终）