com.alibaba.qlexpress4

Class Express4Runner

java.lang.Object

com.alibaba.qlexpress4.Express4Runner

public class Express4Runner
extends java.lang.Object

Author: DQinYuan

Constructor Summary

Constructors

Constructor and Description
Express4Runner(InitOptions initOptions)

Method Summary

Modifier and Type	Method and Description
boolean	addAlias(java.lang.String alias, java.lang.String originToken) add alias for keyWord, operator and function
boolean	addCompileTimeFunction(java.lang.String name, CompileTimeFunction compileTimeFunction) add compile time function
void	addExtendFunction(ExtensionFunction extensionFunction) add extension function
void	addExtendFunction(java.lang.String name, java.lang.Class<?> bindingClass, QLFunctionalVarargs functionalVarargs) add an extension function with variable arguments.
<T> boolean	addFunction(java.lang.String name, java.util.function.Consumer<T> consumer)
boolean	addFunction(java.lang.String name, CustomFunction function) add user defined function to QLExpress engine
<T,R> boolean	addFunction(java.lang.String name, java.util.function.Function<T,R> function)
<T> boolean	addFunction(java.lang.String name, java.util.function.Predicate<T> predicate)
boolean	addFunction(java.lang.String name, java.lang.Runnable runnable)
BatchAddFunctionResult	addFunctionsDefinedInScript(java.lang.String scriptWithFunctionDefine, ExpressContext context, QLOptions qlOptions) execute `scriptWithFunctionDefine` and add functions defined in script
boolean	addMacro(java.lang.String name, java.lang.String macroScript) add user defined global macro to QLExpress engine
BatchAddFunctionResult	addObjFunction(java.lang.Object object) add object member method with annotation QLFunction as function
boolean	addOperator(java.lang.String operator, CustomBinaryOperator customBinaryOperator) add operator with multi precedences
boolean	addOperator(java.lang.String operator, CustomBinaryOperator customBinaryOperator, int precedence) add operator
boolean	addOperator(java.lang.String operator, QLFunctionalVarargs functionalVarargs)
<T,U,R> boolean	addOperatorBiFunction(java.lang.String operator, java.util.function.BiFunction<T,U,R> biFunction)
void	addOrReplaceMacro(java.lang.String name, java.lang.String macroScript) add or replace user defined global macro to QLExpress engine
BatchAddFunctionResult	addStaticFunction(java.lang.Class<?> clazz) add class static method with annotation QLFunction as function
boolean	addVarArgsFunction(java.lang.String name, QLFunctionalVarargs functionalVarargs)
void	check(java.lang.String script)
void	check(java.lang.String script, CheckOptions checkOptions)
void	clearCompileCache() Clear the compilation cache.
QLResult	execute(java.lang.String script, ExpressContext context, QLOptions qlOptions)
QLResult	execute(java.lang.String script, java.util.Map<java.lang.String,java.lang.Object> context, QLOptions qlOptions) Execute the script with variables set in the context; the map key corresponds to the variable name referenced in the script.
QLResult	execute(java.lang.String script, java.lang.Object context, QLOptions qlOptions) Execute the script with variables resolved from the fields of the given context object.
QLResult	executeTemplate(java.lang.String template, java.util.Map<java.lang.String,java.lang.Object> context, QLOptions qlOptions) Execute a template string by wrapping it as a dynamic string literal.
QLResult	executeWithAliasObjects(java.lang.String script, QLOptions qlOptions, java.lang.Object... objects) Execute the script using objects annotated with @QLAlias.
CompileTimeFunction	getCompileTimeFunction(java.lang.String functionName)
java.util.List<TracePointTree>	getExpressionTracePoints(java.lang.String script) Get the expression trace trees for the script without executing it.
CustomFunction	getFunction(java.lang.String functionName)
java.util.Set<java.lang.String>	getOutFunctions(java.lang.String script) Get external functions (those that must be provided via context) referenced by the script.
java.util.Set<java.util.List<java.lang.String>>	getOutVarAttrs(java.lang.String script) Get external variable attribute access paths referenced by the script.
java.util.Set<java.lang.String>	getOutVarNames(java.lang.String script) Get external variables (those that must be provided via context) referenced by the script.
Value	loadField(java.lang.Object object, java.lang.String fieldName)
QCompileCache	parseToDefinitionWithCache(java.lang.String script) parse script with cache
QLambdaTrace	parseToLambda(java.lang.String script, ExpressContext context, QLOptions qlOptions)
QLParser.ProgramContext	parseToSyntaxTree(java.lang.String script)
boolean	replaceDefaultOperator(java.lang.String operator, CustomBinaryOperator customBinaryOperator)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Express4Runner

public Express4Runner(InitOptions initOptions)

Method Detail

getFunction

public CustomFunction getFunction(java.lang.String functionName)

getCompileTimeFunction

public CompileTimeFunction getCompileTimeFunction(java.lang.String functionName)

execute

public QLResult execute(java.lang.String script,
                        java.util.Map<java.lang.String,java.lang.Object> context,
                        QLOptions qlOptions)
                 throws QLException

Execute the script with variables set in the context; the map key corresponds to the variable name referenced in the script.

Parameters:

script - the script content to execute

context - variables for execution, keyed by variable name

qlOptions - execution options (e.g. interpolation, debug)

Returns:

result of script execution and related traces

Throws:

QLException - if a script or runtime error occurs

executeTemplate

public QLResult executeTemplate(java.lang.String template,
                                java.util.Map<java.lang.String,java.lang.Object> context,
                                QLOptions qlOptions)
                         throws QLException

Execute a template string by wrapping it as a dynamic string literal. Template does not support newlines in this mode.

Parameters:

template - the template text to evaluate as a dynamic string

context - variables available to the template

qlOptions - execution options

Returns:

result of template evaluation

Throws:

QLException - if compilation or execution fails

execute

public QLResult execute(java.lang.String script,
                        java.lang.Object context,
                        QLOptions qlOptions)
                 throws QLException

Execute the script with variables resolved from the fields of the given context object. The variable name in the script corresponds to the field name on the object.

Parameters:

script - the script content to execute

context - the object whose public fields/properties are exposed as variables

qlOptions - execution options

Returns:

result of script execution

Throws:

QLException - if a script or runtime error occurs

executeWithAliasObjects

public QLResult executeWithAliasObjects(java.lang.String script,
                                        QLOptions qlOptions,
                                        java.lang.Object... objects)

Execute the script using objects annotated with @QLAlias. The QLAlias.value serves as the variable name for each object. Objects without the annotation are ignored.

Parameters:

script - the script content to execute

qlOptions - execution options

objects - objects annotated with @QLAlias

Returns:

result of script execution

Throws:

QLException - if a script or runtime error occurs

execute

public QLResult execute(java.lang.String script,
                        ExpressContext context,
                        QLOptions qlOptions)

getOutVarNames

public java.util.Set<java.lang.String> getOutVarNames(java.lang.String script)

Get external variables (those that must be provided via context) referenced by the script.

Parameters:

script - the script content

Returns:

names of external variables referenced in the script

getOutVarAttrs

public java.util.Set<java.util.List<java.lang.String>> getOutVarAttrs(java.lang.String script)

Get external variable attribute access paths referenced by the script.

Parameters:

script - the script content

Returns:

attribute chains accessed on external variables

getOutFunctions

public java.util.Set<java.lang.String> getOutFunctions(java.lang.String script)

Get external functions (those that must be provided via context) referenced by the script.

Parameters:

script - the script content

Returns:

names of external functions referenced in the script

getExpressionTracePoints

public java.util.List<TracePointTree> getExpressionTracePoints(java.lang.String script)

Get the expression trace trees for the script without executing it.

Parameters:

script - the script content

Returns:

trace trees for each expression

addMacro

public boolean addMacro(java.lang.String name,
                        java.lang.String macroScript)

add user defined global macro to QLExpress engine

Parameters:

name - macro name

macroScript - script for macro

Returns:

true if add macro successfully. fail if macro name already exists.

addOrReplaceMacro

public void addOrReplaceMacro(java.lang.String name,
                              java.lang.String macroScript)

add or replace user defined global macro to QLExpress engine

Parameters:

name - macro name

macroScript - script for macro

addFunction

public boolean addFunction(java.lang.String name,
                           CustomFunction function)

add user defined function to QLExpress engine

Parameters:

name - function name

function - function definition

Returns:

true if add function successfully. fail if function name already exists.

addFunction

public <T,R> boolean addFunction(java.lang.String name,
                                 java.util.function.Function<T,R> function)

addVarArgsFunction

public boolean addVarArgsFunction(java.lang.String name,
                                  QLFunctionalVarargs functionalVarargs)

addFunction

public <T> boolean addFunction(java.lang.String name,
                               java.util.function.Predicate<T> predicate)

addFunction

public boolean addFunction(java.lang.String name,
                           java.lang.Runnable runnable)

addFunction

public <T> boolean addFunction(java.lang.String name,
                               java.util.function.Consumer<T> consumer)

addFunctionsDefinedInScript

public BatchAddFunctionResult addFunctionsDefinedInScript(java.lang.String scriptWithFunctionDefine,
                                                          ExpressContext context,
                                                          QLOptions qlOptions)

execute `scriptWithFunctionDefine` and add functions defined in script

Parameters:

scriptWithFunctionDefine - script with function define

context - context when execute script

qlOptions - qlOptions when execute script

Returns:

succ and fail functions. fail if function name already exists

addObjFunction

public BatchAddFunctionResult addObjFunction(java.lang.Object object)

add object member method with annotation QLFunction as function

Parameters:

object - object with member method with annotation QLFunction

Returns:

succ and fail functions. fail if function name already exists or method is not public

addStaticFunction

public BatchAddFunctionResult addStaticFunction(java.lang.Class<?> clazz)

add class static method with annotation QLFunction as function

Parameters:

clazz - class with static method with annotation QLFunction

Returns:

succ and fail functions. fail if function name already exists or method is not public

addCompileTimeFunction

public boolean addCompileTimeFunction(java.lang.String name,
                                      CompileTimeFunction compileTimeFunction)

add compile time function

Parameters:

name - function name

compileTimeFunction - definition

Returns:

true if successful

addExtendFunction

public void addExtendFunction(ExtensionFunction extensionFunction)

add extension function

Parameters:

extensionFunction - definition of extansion function

addExtendFunction

public void addExtendFunction(java.lang.String name,
                              java.lang.Class<?> bindingClass,
                              QLFunctionalVarargs functionalVarargs)

add an extension function with variable arguments.

Parameters:

name - the name of the extension function

bindingClass - the receiver type (class)

functionalVarargs - custom logic

parseToSyntaxTree

public QLParser.ProgramContext parseToSyntaxTree(java.lang.String script)

check

public void check(java.lang.String script,
                  CheckOptions checkOptions)
           throws QLSyntaxException

Throws:

QLSyntaxException

check

public void check(java.lang.String script)
           throws QLSyntaxException

Throws:

QLSyntaxException

parseToLambda

public QLambdaTrace parseToLambda(java.lang.String script,
                                  ExpressContext context,
                                  QLOptions qlOptions)

parseToDefinitionWithCache

public QCompileCache parseToDefinitionWithCache(java.lang.String script)

parse script with cache

Parameters:

script - script to parse

Returns:

QLambdaDefinition and TracePointTrees

loadField

public Value loadField(java.lang.Object object,
                       java.lang.String fieldName)

clearCompileCache

public void clearCompileCache()

Clear the compilation cache. This method clears the cache that stores compiled scripts for performance optimization. When the cache is cleared, subsequent script executions will need to recompile the scripts, which may temporarily impact performance until the cache is rebuilt.

addOperatorBiFunction

public <T,U,R> boolean addOperatorBiFunction(java.lang.String operator,
                                             java.util.function.BiFunction<T,U,R> biFunction)

addOperator

public boolean addOperator(java.lang.String operator,
                           QLFunctionalVarargs functionalVarargs)

addOperator

public boolean addOperator(java.lang.String operator,
                           CustomBinaryOperator customBinaryOperator)

add operator with multi precedences

Parameters:

operator - operator name

customBinaryOperator - operator implement

Returns:

true if add operator successfully; false if operator already exist

addOperator

public boolean addOperator(java.lang.String operator,
                           CustomBinaryOperator customBinaryOperator,
                           int precedence)

add operator

Parameters:

operator - operator name

customBinaryOperator - operator implement

precedence - precedence, see QLPrecedences

Returns:

true if add operator successfully; false if operator already exist

replaceDefaultOperator

public boolean replaceDefaultOperator(java.lang.String operator,
                                      CustomBinaryOperator customBinaryOperator)

Parameters:

operator - operator name

customBinaryOperator - operator implement

Returns:

true if replace operator successfully; false if default operator not exists

addAlias

public boolean addAlias(java.lang.String alias,
                        java.lang.String originToken)

add alias for keyWord, operator and function

Parameters:

alias - must be a valid id

originToken - key word in qlexpress

Returns:

true if add alias successfully