Class OpenExpression

java.lang.Object
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 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 | 构建器

    • 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 | 缓存大小