跳到主要内容

8.3 核心接口

引擎通过以下对象完成配置、编译和执行：

HostConfiguration → QueryManager → QueryBuilder → Query → QueryResult

接口职责​

类型职责常用入口
HostConfiguration实现 HostContext，保存加载器、导入对象、片段执行器和应用对象addImport、addFragment、addAttachment
HostContext向引擎和扩展提供对象查找、加载器及按类型注册的应用对象findBean、findFragmentProcess、getAttachment
QueryManager持有同一个 HostContext，创建查询构建器newBuilder()
QueryBuilder设置查询配置，解析脚本并生成 QIL 或 QueryparserQuery、compilerQuery、createQuery
Query接收参数、执行已编译的脚本execute
QueryResult保存返回值、结果码和执行耗时getData、getCode、executionTime

QueryModel 是解析后的语法树，QIL 是编译后的指令。普通查询直接使用 createQuery(script)，分步编译见独立使用。

共享变量​

共享变量在编译前声明，脚本通过变量名直接访问；调用参数在执行时传入，通过 ${...} 读取：

import java.util.Map;
import net.hasor.dataql.host.HostConfiguration;
import net.hasor.dataql.host.Query;
import net.hasor.dataql.host.QueryBuilder;
import net.hasor.dataql.host.QueryManager;

QueryBuilder builder = new QueryManager(new HostConfiguration()).newBuilder();
builder.addShareVar("application", () -> "orders");
Query query = builder.createQuery("return application + ':' + ${name};");
System.out.println(query.execute(Map.of("name", "Alice")).getData().unwrap());

输出为 orders:Alice。供应器在创建 Query 时调用；已有变量可通过 query.addShareVar(name, value) 更新值，新增变量名需要重新编译。

Hint​

QueryBuilder.setHint(name, value) 为新查询提供初始配置，Query.setHint(name, value) 可覆盖该值，removeHint(name) 可将其移除。脚本中的显式设置在执行时优先。

import net.hasor.dataql.host.HostConfiguration;
import net.hasor.dataql.host.Query;
import net.hasor.dataql.host.QueryBuilder;
import net.hasor.dataql.host.QueryManager;

QueryBuilder builder = new QueryManager(new HostConfiguration()).newBuilder();
builder.setHint("INDEX_OVERFLOW", "near");
Query query = builder.createQuery("var values = [10,20]; return values[5];");
query.setHint("INDEX_OVERFLOW", "null");
Object result = query.execute().getData().unwrap(); // null

setHint(name, Object) 可存放应用对象，复制 Hint 或克隆 Query 时保留对象引用。每次执行使用独立的 Hint 容器，脚本修改不会回写 Query。

脚本语法与选项见 Hint 参考手册，UDF 读取这些对象的方式见自定义函数。

扩展入口​

扩展实现沿用已有文档，独立使用引擎时按下表注册：

扩展引擎注册方式实现说明
UDFbuilder.addShareVar(name, () -> udf)自定义函数
函数库、应用对象host.addImport(name, supplier)函数库、应用对象导入
外部片段host.addFragment(name, supplier)片段执行器
查找器new HostConfiguration(finder)查找器
应用资源host.addAttachment(type, instance)引擎与查询配置
参数作用域query.execute(customizeScope)自定义作用域；Dataway 的参数合并规则仅适用于 Dataway

QueryWrap 是 Query 的委托包装类。需要在执行前后附加逻辑时，可继承它并重写 execute(CustomizeScope)；其他执行重载会进入该方法。