Class JsonPath

java.lang.Object
cloud.opencode.base.json.path.JsonPath
public final class JsonPath extends Object
JSON Path - XPath-style Query Language for JSON JSON Path - JSON 的 XPath 风格查询语言

This class implements JSONPath, an XPath-like query language for JSON. It supports complex queries including wildcards, filters, and array slices.

此类实现 JSONPath，一种类似 XPath 的 JSON 查询语言。 它支持复杂查询，包括通配符、过滤器和数组切片。

Syntax | 语法:

  • $ - Root element - 根元素
  • .property or ['property'] - Child property - 子属性
  • ..property - Recursive descent - 递归下降
  • * - Wildcard (all children) - 通配符（所有子元素）
  • [n] - Array index - 数组索引
  • [start:end] - Array slice - 数组切片
  • [?(@.price < 10)] - Filter expression - 过滤表达式

Example | 示例:

String json = "{\"store\":{\"books\":[{\"title\":\"A\",\"price\":10},{\"title\":\"B\",\"price\":20}]}}";
JsonNode root = OpenJson.parse(json);

// Simple property access
List<JsonNode> titles = JsonPath.read(root, "$.store.books[*].title");

// Filter expression
List<JsonNode> cheap = JsonPath.read(root, "$.store.books[?(@.price < 15)]");

// Recursive descent
List<JsonNode> allPrices = JsonPath.read(root, "$..price");

Features | 主要功能:

  • XPath-style query language for JSON navigation - JSON导航的XPath风格查询语言
  • Wildcard, filter, array slice, and recursive descent support - 通配符、过滤器、数组切片和递归下降支持
  • Compiled path expressions for reuse - 可重用的编译路径表达式

Security | 安全性:

  • Thread-safe: Yes (immutable record) - 线程安全: 是（不可变记录）
  • Null-safe: Partial (validates inputs) - 空值安全: 部分（验证输入）
Since:
JDK 25, opencode-base-json V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • compile

      public static JsonPath compile(String expression)
      Compiles a JSONPath expression. 编译 JSONPath 表达式。
      Parameters:
      expression - the JSONPath expression - JSONPath 表达式
      Returns:
      the compiled JsonPath - 编译的 JsonPath
      Throws:
      OpenJsonProcessingException - if expression is invalid - 如果表达式无效

    • read

      public static List<JsonNode> read(JsonNode root, String expression)
      Reads all matching values from a JSON node. 从 JSON 节点读取所有匹配的值。
      Parameters:
      root - the root node - 根节点
      expression - the JSONPath expression - JSONPath 表达式
      Returns:
      list of matching nodes - 匹配节点列表

    • readFirst

      public static JsonNode readFirst(JsonNode root, String expression)
      Reads the first matching value from a JSON node. 从 JSON 节点读取第一个匹配的值。
      Parameters:
      root - the root node - 根节点
      expression - the JSONPath expression - JSONPath 表达式
      Returns:
      the first matching node, or null if none - 第一个匹配节点，如果没有则返回 null

    • exists

      public static boolean exists(JsonNode root, String expression)
      Checks if any node matches the expression. 检查是否有任何节点匹配表达式。
      Parameters:
      root - the root node - 根节点
      expression - the JSONPath expression - JSONPath 表达式
      Returns:
      true if at least one match exists - 如果至少有一个匹配则返回 true

    • evaluate

      public List<JsonNode> evaluate(JsonNode root)
      Evaluates this path against a JSON node. 对 JSON 节点求值此路径。
      Parameters:
      root - the root node - 根节点
      Returns:
      list of matching nodes - 匹配节点列表

    • evaluateFirst

      public JsonNode evaluateFirst(JsonNode root)
      Returns the first matching node. 返回第一个匹配节点。
      Parameters:
      root - the root node - 根节点
      Returns:
      the first match, or null - 第一个匹配，或 null

    • getExpression

      public String getExpression()
      Returns the path expression. 返回路径表达式。
      Returns:
      the expression - 表达式

    • toString

      public String toString()
      Overrides:
      toString in class Object