cloud.opencode.base.expression.OpenExpression

public final class OpenExpression extends Object

OpenExpression - Main Entry Point OpenExpression - 主入口点

Provides a simple and powerful expression evaluation API.

提供简单而强大的表达式求值API。

Basic Usage | 基本用法

// Simple evaluation
Object result = OpenExpression.eval("1 + 2 * 3");  // 7

// With variables
Object result = OpenExpression.eval("name + ' World'", Map.of("name", "Hello"));  // "Hello World"

// With root object
Object result = OpenExpression.eval("user.name", myUser);  // user's name

// Type conversion
int result = OpenExpression.eval("100 / 3", Integer.class);  // 33

Advanced Usage | 高级用法

// Create parser for reuse
ExpressionParser parser = OpenExpression.parser();
Expression expr = parser.parseExpression("price * quantity");

// Evaluate with different contexts
StandardContext ctx = StandardContext.builder()
    .rootObject(order1)
    .sandbox(DefaultSandbox.standard())
    .build();
Object result1 = expr.getValue(ctx);

ctx.setRootObject(order2);
Object result2 = expr.getValue(ctx);

Features | 主要功能:

Simple one-line expression evaluation - 简单的一行表达式求值
Variable binding via Map or EvaluationContext - 通过Map或EvaluationContext绑定变量
Type-safe evaluation with automatic conversion - 类型安全求值与自动转换
Built-in expression caching (LRU, max 1000) - 内置表达式缓存（LRU，最大1000）
Sandbox support for security constraints - 沙箱支持安全约束
Expression validation - 表达式验证

Security | 安全性:

Thread-safe: Yes, uses synchronized LRU cache - 线程安全: 是，使用同步的LRU缓存
Null-safe: Yes, null context/variables handled gracefully - 空值安全: 是，null上下文/变量优雅处理

Usage Examples | 使用示例:

// Simple evaluation
Object result = OpenExpression.eval("1 + 2 * 3");  // 7

// With variables
Object result = OpenExpression.eval("name + ' World'", Map.of("name", "Hello"));

// Type-safe evaluation
int result = OpenExpression.eval("100 / 3", Integer.class);  // 33

Since:

JDK 25, opencode-base-expression V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

static int

cacheSize()

Get cache size 获取缓存大小

static void

clearCache()

Clear the expression cache 清除表达式缓存

static StandardContext

context()

Create a new standard context 创建新的标准上下文

static StandardContext

context(Object rootObject)

Create a new standard context with root object 使用根对象创建新的标准上下文

static StandardContext.Builder

contextBuilder()

Create a context builder 创建上下文构建器

static Object

eval(String expression)

Evaluate expression 求值表达式

static Object

eval(String expression, EvaluationContext context)

Evaluate expression with context 使用上下文求值表达式

static <T> T

eval(String expression, EvaluationContext context, Class<T> targetType)

Evaluate expression with context and convert to type 使用上下文求值表达式并转换为指定类型

static <T> T

eval(String expression, Class<T> targetType)

Evaluate expression and convert to type 求值表达式并转换为指定类型

static Object

eval(String expression, Object rootObject)

Evaluate expression with root object 使用根对象求值表达式

static Object

eval(String expression, Map<String,Object> variables)

Evaluate expression with variables 使用变量求值表达式

static <T> T

eval(String expression, Map<String,Object> variables, Class<T> targetType)

Evaluate expression with variables and convert to type 使用变量求值表达式并转换为指定类型

static Set<String>

extractVariables(String expression)

Extract variable names from expression 从表达式中提取变量名

static FunctionRegistry

functions()

Get the global function registry 获取全局函数注册表

static boolean

isValid(String expression)

Check if expression is valid 检查表达式是否有效

static ExpressionParser

newParser()

Create a new parser 创建新解析器

static Expression

parse(String expression)

Parse expression 解析表达式

static ExpressionParser

parser()

Get the default expression parser 获取默认表达式解析器

static Sandbox

permissiveSandbox()

Create a permissive sandbox 创建宽松沙箱

static String

render(String template, EvaluationContext context)

Render expression template with context 使用上下文渲染表达式模板

static String

render(String template, Map<String,Object> variables)

Render expression template with variables 使用变量渲染表达式模板

static Sandbox

restrictiveSandbox()

Create a restrictive sandbox 创建限制性沙箱

static Sandbox

standardSandbox()

Create a standard sandbox 创建标准沙箱

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- eval
  
  public static Object eval(String expression)
  
  Evaluate expression 求值表达式
  
  Parameters:
  
  expression - the expression string | 表达式字符串
  
  Returns:
  
  the result | 结果
- eval
  
  public static Object eval(String expression, Map<String,Object> variables)
  
  Evaluate expression with variables 使用变量求值表达式
  
  Parameters:
  
  expression - the expression string | 表达式字符串
  
  variables - the variable map | 变量映射
  
  Returns:
  
  the result | 结果
- eval
  
  public static Object eval(String expression, Object rootObject)
  
  Evaluate expression with root object 使用根对象求值表达式
  
  Parameters:
  
  expression - the expression string | 表达式字符串
  
  rootObject - the root object | 根对象
  
  Returns:
  
  the result | 结果
- eval
  
  public static Object eval(String expression, EvaluationContext context)
  
  Evaluate expression with context 使用上下文求值表达式
  
  Parameters:
  
  expression - the expression string | 表达式字符串
  
  context - the evaluation context | 求值上下文
  
  Returns:
  
  the result | 结果
- eval
  
  public static <T> T eval(String expression, Class<T> targetType)
  
  Evaluate expression and convert to type 求值表达式并转换为指定类型
  
  Type Parameters:
  
  T - the target type | 目标类型
  
  Parameters:
  
  expression - the expression string | 表达式字符串
  
  targetType - the target type | 目标类型
  
  Returns:
  
  the typed result | 类型化结果
- eval
  
  public static <T> T eval(String expression, Map<String,Object> variables, Class<T> targetType)
  
  Evaluate expression with variables and convert to type 使用变量求值表达式并转换为指定类型
  
  Type Parameters:
  
  T - the target type | 目标类型
  
  Parameters:
  
  expression - the expression string | 表达式字符串
  
  variables - the variable map | 变量映射
  
  targetType - the target type | 目标类型
  
  Returns:
  
  the typed result | 类型化结果
- eval
  
  public static <T> T eval(String expression, EvaluationContext context, Class<T> targetType)
  
  Evaluate expression with context and convert to type 使用上下文求值表达式并转换为指定类型
  
  Type Parameters:
  
  T - the target type | 目标类型
  
  Parameters:
  
  expression - the expression string | 表达式字符串
  
  context - the evaluation context | 求值上下文
  
  targetType - the target type | 目标类型
  
  Returns:
  
  the typed result | 类型化结果
- parser
  
  public static ExpressionParser parser()
  
  Get the default expression parser 获取默认表达式解析器
  
  Returns:
  
  the default parser | 默认解析器
- newParser
  
  public static ExpressionParser newParser()
  
  Create a new parser 创建新解析器
  
  Returns:
  
  new parser | 新解析器
- parse
  
  public static Expression parse(String expression)
  
  Parse expression 解析表达式
  
  Parameters:
  
  expression - the expression string | 表达式字符串
  
  Returns:
  
  the parsed expression | 解析后的表达式
- functions
  
  public static FunctionRegistry functions()
  
  Get the global function registry 获取全局函数注册表
  
  Returns:
  
  the global registry | 全局注册表
- standardSandbox
  
  public static Sandbox standardSandbox()
  
  Create a standard sandbox 创建标准沙箱
  
  Returns:
  
  the standard sandbox | 标准沙箱
- restrictiveSandbox
  
  public static Sandbox restrictiveSandbox()
  
  Create a restrictive sandbox 创建限制性沙箱
  
  Returns:
  
  the restrictive sandbox | 限制性沙箱
- permissiveSandbox
  
  public static Sandbox permissiveSandbox()
  
  Create a permissive sandbox 创建宽松沙箱
  
  Returns:
  
  the permissive sandbox | 宽松沙箱
- context
  
  public static StandardContext context()
  
  Create a new standard context 创建新的标准上下文
  
  Returns:
  
  new context | 新上下文
- context
  
  public static StandardContext context(Object rootObject)
  
  Create a new standard context with root object 使用根对象创建新的标准上下文
  
  Parameters:
  
  rootObject - the root object | 根对象
  
  Returns:
  
  new context | 新上下文
- contextBuilder
  
  public static StandardContext.Builder contextBuilder()
  
  Create a context builder 创建上下文构建器
  
  Returns:
  
  the builder | 构建器
- extractVariables
  
  public static Set<String> extractVariables(String expression)
  
  Extract variable names from expression 从表达式中提取变量名
  
  Parameters:
  
  expression - the expression string | 表达式字符串
  
  Returns:
  
  set of variable names | 变量名集合
- render
  
  public static String render(String template, Map<String,Object> variables)
  
  Render expression template with variables 使用变量渲染表达式模板
  Supports ${expression} placeholders.
  
  支持 ${expression} 占位符。
  
  Parameters:
  
  template - the template string | 模板字符串
  
  variables - the variable map | 变量映射
  
  Returns:
  
  the rendered string | 渲染后的字符串
- render
  
  public static String render(String template, EvaluationContext context)
  
  Render expression template with context 使用上下文渲染表达式模板
  
  Parameters:
  
  template - the template string | 模板字符串
  
  context - the evaluation context | 求值上下文
  
  Returns:
  
  the rendered string | 渲染后的字符串
- isValid
  
  public static boolean isValid(String expression)
  
  Check if expression is valid 检查表达式是否有效
  
  Parameters:
  
  expression - the expression string | 表达式字符串
  
  Returns:
  
  true if valid | 如果有效返回true
- clearCache
  
  public static void clearCache()
  
  Clear the expression cache 清除表达式缓存
- cacheSize
  
  public static int cacheSize()
  
  Get cache size 获取缓存大小
  
  Returns:
  
  the cache size | 缓存大小

Class OpenExpression

Basic Usage | 基本用法

Advanced Usage | 高级用法

Method Summary

Methods inherited from class Object

Method Details

eval

eval

eval

eval

eval

eval

eval

parser

newParser

parse

functions

standardSandbox

restrictiveSandbox

permissiveSandbox

context

context

contextBuilder

extractVariables

render

render

isValid

clearCache

cacheSize