Class JsonPointer

java.lang.Object
cloud.opencode.base.json.path.JsonPointer
public final class JsonPointer extends Object
JSON Pointer - RFC 6901 Implementation JSON Pointer - RFC 6901 实现

This class implements JSON Pointer (RFC 6901), a syntax for identifying specific values within a JSON document.

此类实现 JSON Pointer（RFC 6901），用于标识 JSON 文档中特定值的语法。

Syntax | 语法:

  • "" - Root document - 根文档
  • "/foo" - Property "foo" of root - 根的属性 "foo"
  • "/foo/0" - First element of array "foo" - 数组 "foo" 的第一个元素
  • "/a~1b" - Property "a/b" (/ escaped as ~1) - 属性 "a/b"（/ 转义为 ~1）
  • "/m~0n" - Property "m~n" (~ escaped as ~0) - 属性 "m~n"（~ 转义为 ~0）

Example | 示例:

JsonNode root = OpenJson.parse("{\"foo\":{\"bar\":[1,2,3]}}");

// Access nested values
JsonPointer pointer = JsonPointer.parse("/foo/bar/1");
JsonNode value = pointer.evaluate(root);  // Returns 2

// Modify values
JsonPointer.parse("/foo/bar/0").set(root, JsonNode.of(10));

Features | 主要功能:

  • RFC 6901 JSON Pointer implementation - RFC 6901 JSON Pointer实现
  • Path-based navigation with escaping support - 支持转义的路径导航
  • Pointer composition and decomposition - 指针组合和分解

Security | 安全性:

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

  • Field Details

    • ROOT

      public static final JsonPointer ROOT
      Empty/root pointer 空/根指针

  • Method Details

    • parse

      public static JsonPointer parse(String pointer)
      Parses a JSON Pointer string. 解析 JSON Pointer 字符串。
      Parameters:
      pointer - the pointer string (e.g., "/foo/bar") - 指针字符串
      Returns:
      the JsonPointer instance - JsonPointer 实例
      Throws:
      OpenJsonProcessingException - if the pointer is invalid - 如果指针无效

    • of

      public static JsonPointer of(String... tokens)
      Creates a JsonPointer from reference tokens. 从引用令牌创建 JsonPointer。
      Parameters:
      tokens - the reference tokens - 引用令牌
      Returns:
      the JsonPointer instance - JsonPointer 实例

    • of

      public static JsonPointer of(List<String> tokens)
      Creates a JsonPointer from reference tokens. 从引用令牌创建 JsonPointer。
      Parameters:
      tokens - the reference tokens - 引用令牌
      Returns:
      the JsonPointer instance - JsonPointer 实例

    • evaluate

      public JsonNode evaluate(JsonNode root)
      Evaluates this pointer against a JSON node. 对 JSON 节点求值此指针。
      Parameters:
      root - the root node - 根节点
      Returns:
      the node at this pointer location - 此指针位置的节点
      Throws:
      OpenJsonProcessingException - if path is invalid - 如果路径无效

    • evaluateOrNull

      public JsonNode evaluateOrNull(JsonNode root)
      Evaluates this pointer, returning null if path doesn't exist. 求值此指针，如果路径不存在则返回 null。
      Parameters:
      root - the root node - 根节点
      Returns:
      the node at this pointer location, or null - 此指针位置的节点，或 null

    • exists

      public boolean exists(JsonNode root)
      Checks if this pointer exists in the given node. 检查此指针是否存在于给定节点中。
      Parameters:
      root - the root node - 根节点
      Returns:
      true if the path exists - 如果路径存在则返回 true

    • parent

      public JsonPointer parent()
      Returns the parent pointer. 返回父指针。
      Returns:
      the parent pointer, or ROOT if this is ROOT - 父指针，如果是 ROOT 则返回 ROOT

    • append

      public JsonPointer append(String property)
      Appends a property name to this pointer. 向此指针追加属性名。
      Parameters:
      property - the property name - 属性名
      Returns:
      a new pointer with the appended property - 追加属性后的新指针

    • append

      public JsonPointer append(int index)
      Appends an array index to this pointer. 向此指针追加数组索引。
      Parameters:
      index - the array index - 数组索引
      Returns:
      a new pointer with the appended index - 追加索引后的新指针

    • getLastToken

      public String getLastToken()
      Returns the last reference token. 返回最后一个引用令牌。
      Returns:
      the last token, or null for ROOT - 最后一个令牌，ROOT 返回 null

    • getTokens

      public List<String> getTokens()
      Returns the reference tokens. 返回引用令牌。
      Returns:
      unmodifiable list of tokens - 不可变的令牌列表

    • depth

      public int depth()
      Returns the depth (number of tokens). 返回深度（令牌数量）。
      Returns:
      the depth - 深度

    • isRoot

      public boolean isRoot()
      Returns whether this is the root pointer. 返回此指针是否为根指针。
      Returns:
      true if root - 如果是根则返回 true

    • toString

      public String toString()
      Returns the pointer string representation. 返回指针字符串表示。
      Overrides:
      toString in class Object
      Returns:
      the pointer string - 指针字符串

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object