cloud.opencode.base.json.OpenJson

public final class OpenJson extends Object

OpenJson - Unified JSON Processing Facade OpenJson - 统一 JSON 处理门面

This is the main entry point for all JSON operations in the OpenCode JSON library. It provides a unified API that delegates to pluggable JSON provider implementations (Jackson, Gson, Fastjson2, etc.).

这是 OpenCode JSON 库中所有 JSON 操作的主入口点。它提供统一的 API，委托给可插拔的 JSON 提供者实现（Jackson、Gson、Fastjson2 等）。

Features | 特性:

Serialization/Deserialization - 序列化/反序列化
Tree Model (JsonNode) - 树模型
Streaming API - 流式 API
JSONPath & JSON Pointer - JSONPath 和 JSON Pointer
JSON Patch & Merge Patch - JSON Patch 和 Merge Patch
JSON Schema Validation - JSON Schema 验证
Custom Type Adapters - 自定义类型适配器
Security Features - 安全特性

Basic Usage | 基本用法:

// Serialize to JSON
String json = OpenJson.toJson(user);

// Deserialize from JSON
User user = OpenJson.fromJson(json, User.class);

// Parse to tree
JsonNode node = OpenJson.parse(json);

// Query with JSONPath
List<JsonNode> results = OpenJson.select(node, "$.users[*].name");

// Custom configuration
OpenJson json = OpenJson.withConfig(config);

Features | 主要功能:

Unified facade for all JSON operations - 所有JSON操作的统一门面
Pluggable provider architecture (Jackson, Gson, Fastjson2) - 可插拔提供者架构
Static and instance API support - 支持静态和实例API

Usage Examples | 使用示例:

// See class-level documentation for usage
// 参见类级文档了解用法

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:

Method Summary

Modifier and Type

Method

Description

static JsonNode

at(JsonNode node, String pointer)

Evaluates a JSON Pointer against a node.

static JsonReader

createReader(InputStream input)

Creates a JsonReader for an InputStream.

static JsonReader

createReader(Reader reader)

Creates a JsonReader for a Reader.

static JsonWriter

createWriter(OutputStream output)

Creates a JsonWriter for an OutputStream.

static JsonWriter

createWriter(Writer writer)

Creates a JsonWriter for a Writer.

<T> T

deserialize(byte[] json, Class<T> clazz)

Deserializes JSON bytes.

<T> T

deserialize(InputStream input, Class<T> clazz)

Deserializes from InputStream.

<T> T

deserialize(Reader reader, Class<T> clazz)

Deserializes from Reader.

<T> T

deserialize(String json, TypeReference<T> typeReference)

Deserializes JSON using TypeReference.

<T> T

deserialize(String json, Class<T> clazz)

Deserializes JSON to an object.

<T> List<T>

deserializeArray(String json, Class<T> elementType)

Deserializes JSON array to List.

<K,V> Map<K,V>

deserializeMap(String json, Class<K> keyType, Class<V> valueType)

Deserializes JSON object to Map.

static JsonDiff.DiffResult

diff(JsonNode source, JsonNode target)

Computes diff between two JSON documents.

static <T> T

fromJson(byte[] json, Class<T> clazz)

Deserializes JSON bytes to an object.

static <T> T

fromJson(InputStream input, Class<T> clazz)

Deserializes from InputStream.

static <T> T

fromJson(Reader reader, Class<T> clazz)

Deserializes from Reader.

static <T> T

fromJson(String json, TypeReference<T> typeReference)

Deserializes JSON string using TypeReference.

static <T> T

fromJson(String json, Class<T> clazz)

Deserializes JSON string to an object.

static <T> List<T>

fromJsonArray(String json, Class<T> elementType)

Deserializes JSON array to List.

static <K,V> Map<K,V>

fromJsonMap(String json, Class<K> keyType, Class<V> valueType)

Deserializes JSON object to Map.

JsonConfig

getConfig()

Returns the configuration.

JsonProvider

getProvider()

Returns the provider.

static JsonNode

mergePatch(JsonNode target, JsonNode patch)

Applies a JSON Merge Patch to a document.

static JsonNode

parse(byte[] json)

Parses JSON bytes to JsonNode tree.

static JsonNode

parse(String json)

Parses JSON string to JsonNode tree.

JsonNode

parseTree(byte[] json)

Parses JSON bytes to tree.

JsonNode

parseTree(String json)

Parses JSON to tree.

static JsonNode

patch(JsonNode target, JsonPatch patch)

Applies a JSON Patch to a document.

static List<JsonNode>

select(JsonNode node, String path)

Selects nodes using JSONPath.

static JsonNode

selectFirst(JsonNode node, String path)

Selects first matching node using JSONPath.

String

serialize(Object obj)

Serializes an object to JSON string.

void

serialize(Object obj, OutputStream output)

Serializes an object to an OutputStream.

void

serialize(Object obj, Writer writer)

Serializes an object to a Writer.

byte[]

serializeToBytes(Object obj)

Serializes an object to JSON bytes.

static String

toJson(Object obj)

Serializes an object to JSON string.

static void

toJson(Object obj, OutputStream output)

Serializes an object to an OutputStream.

static void

toJson(Object obj, Writer writer)

Serializes an object to a Writer.

static byte[]

toJsonBytes(Object obj)

Serializes an object to JSON bytes.

static String

toPrettyJson(Object obj)

Serializes an object to pretty-printed JSON.

static JsonNode

toTree(Object obj)

Converts object to JsonNode tree.

<T> T

treeToObject(JsonNode node, Class<T> clazz)

Converts tree to object.

static <T> T

treeToValue(JsonNode node, Class<T> clazz)

Converts JsonNode to object.

static JsonSchemaValidator.ValidationResult

validate(JsonNode data, JsonNode schema)

Validates JSON against a schema.

static void

validateOrThrow(JsonNode data, JsonNode schema)

Validates and throws if invalid.

JsonNode

valueToTree(Object obj)

Converts object to tree.

static OpenJson

withConfig(JsonConfig config)

Creates a new OpenJson instance with the specified configuration.

static OpenJson

withConfigAndProvider(JsonConfig config, String providerName)

Creates a new OpenJson instance with configuration and provider.

static OpenJson

withProvider(String providerName)

Creates a new OpenJson instance with the specified provider.

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

Method Details
- withConfig
  
  public static OpenJson withConfig(JsonConfig config)
  
  Creates a new OpenJson instance with the specified configuration. 使用指定配置创建新的 OpenJson 实例。
  
  Parameters:
  
  config - the configuration - 配置
  
  Returns:
  
  the OpenJson instance - OpenJson 实例
- withProvider
  
  public static OpenJson withProvider(String providerName)
  
  Creates a new OpenJson instance with the specified provider. 使用指定提供者创建新的 OpenJson 实例。
  
  Parameters:
  
  providerName - the provider name (e.g., "jackson", "gson") - 提供者名称
  
  Returns:
  
  the OpenJson instance - OpenJson 实例
- withConfigAndProvider
  
  public static OpenJson withConfigAndProvider(JsonConfig config, String providerName)
  
  Creates a new OpenJson instance with configuration and provider. 使用配置和提供者创建新的 OpenJson 实例。
  
  Parameters:
  
  config - the configuration - 配置
  
  providerName - the provider name - 提供者名称
  
  Returns:
  
  the OpenJson instance - OpenJson 实例
- toJson
  
  public static String toJson(Object obj)
  
  Serializes an object to JSON string. 将对象序列化为 JSON 字符串。
  
  Parameters:
  
  obj - the object to serialize - 要序列化的对象
  
  Returns:
  
  the JSON string - JSON 字符串
- toJsonBytes
  
  public static byte[] toJsonBytes(Object obj)
  
  Serializes an object to JSON bytes. 将对象序列化为 JSON 字节数组。
  
  Parameters:
  
  obj - the object to serialize - 要序列化的对象
  
  Returns:
  
  the JSON bytes - JSON 字节数组
- toJson
  
  public static void toJson(Object obj, OutputStream output)
  
  Serializes an object to an OutputStream. 将对象序列化到输出流。
  
  Parameters:
  
  obj - the object to serialize - 要序列化的对象
  
  output - the output stream - 输出流
- toJson
  
  public static void toJson(Object obj, Writer writer)
  
  Serializes an object to a Writer. 将对象序列化到 Writer。
  
  Parameters:
  
  obj - the object to serialize - 要序列化的对象
  
  writer - the writer - Writer
- toPrettyJson
  
  public static String toPrettyJson(Object obj)
  
  Serializes an object to pretty-printed JSON. 将对象序列化为美化的 JSON。
  
  Parameters:
  
  obj - the object to serialize - 要序列化的对象
  
  Returns:
  
  the pretty JSON string - 美化的 JSON 字符串
- fromJson
  
  public static <T> T fromJson(String json, Class<T> clazz)
  
  Deserializes JSON string to an object. 将 JSON 字符串反序列化为对象。
  
  Type Parameters:
  
  T - the target type - 目标类型
  
  Parameters:
  
  json - the JSON string - JSON 字符串
  
  clazz - the target class - 目标类
  
  Returns:
  
  the deserialized object - 反序列化的对象
- fromJson
  
  public static <T> T fromJson(String json, TypeReference<T> typeReference)
  
  Deserializes JSON string using TypeReference. 使用 TypeReference 反序列化 JSON 字符串。
  
  Type Parameters:
  
  T - the target type - 目标类型
  
  Parameters:
  
  json - the JSON string - JSON 字符串
  
  typeReference - the type reference - 类型引用
  
  Returns:
  
  the deserialized object - 反序列化的对象
- fromJson
  
  public static <T> T fromJson(byte[] json, Class<T> clazz)
  
  Deserializes JSON bytes to an object. 将 JSON 字节数组反序列化为对象。
  
  Type Parameters:
  
  T - the target type - 目标类型
  
  Parameters:
  
  json - the JSON bytes - JSON 字节数组
  
  clazz - the target class - 目标类
  
  Returns:
  
  the deserialized object - 反序列化的对象
- fromJson
  
  public static <T> T fromJson(InputStream input, Class<T> clazz)
  
  Deserializes from InputStream. 从输入流反序列化。
  
  Type Parameters:
  
  T - the target type - 目标类型
  
  Parameters:
  
  input - the input stream - 输入流
  
  clazz - the target class - 目标类
  
  Returns:
  
  the deserialized object - 反序列化的对象
- fromJson
  
  public static <T> T fromJson(Reader reader, Class<T> clazz)
  
  Deserializes from Reader. 从 Reader 反序列化。
  
  Type Parameters:
  
  T - the target type - 目标类型
  
  Parameters:
  
  reader - the reader - Reader
  
  clazz - the target class - 目标类
  
  Returns:
  
  the deserialized object - 反序列化的对象
- fromJsonArray
  
  public static <T> List<T> fromJsonArray(String json, Class<T> elementType)
  
  Deserializes JSON array to List. 将 JSON 数组反序列化为 List。
  
  Type Parameters:
  
  T - the element type - 元素类型
  
  Parameters:
  
  json - the JSON string - JSON 字符串
  
  elementType - the element type - 元素类型
  
  Returns:
  
  the list - 列表
- fromJsonMap
  
  public static <K,V> Map<K,V> fromJsonMap(String json, Class<K> keyType, Class<V> valueType)
  
  Deserializes JSON object to Map. 将 JSON 对象反序列化为 Map。
  
  Type Parameters:
  
  K - the key type - 键类型
  
  V - the value type - 值类型
  
  Parameters:
  
  json - the JSON string - JSON 字符串
  
  keyType - the key type - 键类型
  
  valueType - the value type - 值类型
  
  Returns:
  
  the map - Map
- parse
  
  public static JsonNode parse(String json)
  
  Parses JSON string to JsonNode tree. 将 JSON 字符串解析为 JsonNode 树。
  
  Parameters:
  
  json - the JSON string - JSON 字符串
  
  Returns:
  
  the root node - 根节点
- parse
  
  public static JsonNode parse(byte[] json)
  
  Parses JSON bytes to JsonNode tree. 将 JSON 字节数组解析为 JsonNode 树。
  
  Parameters:
  
  json - the JSON bytes - JSON 字节数组
  
  Returns:
  
  the root node - 根节点
- toTree
  
  public static JsonNode toTree(Object obj)
  
  Converts object to JsonNode tree. 将对象转换为 JsonNode 树。
  
  Parameters:
  
  obj - the object - 对象
  
  Returns:
  
  the JSON node - JSON 节点
- treeToValue
  
  public static <T> T treeToValue(JsonNode node, Class<T> clazz)
  
  Converts JsonNode to object. 将 JsonNode 转换为对象。
  
  Type Parameters:
  
  T - the target type - 目标类型
  
  Parameters:
  
  node - the JSON node - JSON 节点
  
  clazz - the target class - 目标类
  
  Returns:
  
  the object - 对象
- at
  
  public static JsonNode at(JsonNode node, String pointer)
  
  Evaluates a JSON Pointer against a node. 对节点求值 JSON Pointer。
  
  Parameters:
  
  node - the JSON node - JSON 节点
  
  pointer - the JSON Pointer string - JSON Pointer 字符串
  
  Returns:
  
  the value at the pointer location - 指针位置的值
- select
  
  public static List<JsonNode> select(JsonNode node, String path)
  
  Selects nodes using JSONPath. 使用 JSONPath 选择节点。
  
  Parameters:
  
  node - the JSON node - JSON 节点
  
  path - the JSONPath expression - JSONPath 表达式
  
  Returns:
  
  matching nodes - 匹配的节点
- selectFirst
  
  public static JsonNode selectFirst(JsonNode node, String path)
  
  Selects first matching node using JSONPath. 使用 JSONPath 选择第一个匹配的节点。
  
  Parameters:
  
  node - the JSON node - JSON 节点
  
  path - the JSONPath expression - JSONPath 表达式
  
  Returns:
  
  the first match, or null - 第一个匹配，或 null
- diff
  
  public static JsonDiff.DiffResult diff(JsonNode source, JsonNode target)
  
  Computes diff between two JSON documents. 计算两个 JSON 文档之间的差异。
  
  Parameters:
  
  source - the source document - 源文档
  
  target - the target document - 目标文档
  
  Returns:
  
  the diff result - 差异结果
- patch
  
  public static JsonNode patch(JsonNode target, JsonPatch patch)
  
  Applies a JSON Patch to a document. 将 JSON Patch 应用于文档。
  
  Parameters:
  
  target - the target document - 目标文档
  
  patch - the patch - 补丁
  
  Returns:
  
  the patched document - 打补丁后的文档
- mergePatch
  
  public static JsonNode mergePatch(JsonNode target, JsonNode patch)
  
  Applies a JSON Merge Patch to a document. 将 JSON Merge Patch 应用于文档。
  
  Parameters:
  
  target - the target document - 目标文档
  
  patch - the merge patch document - 合并补丁文档
  
  Returns:
  
  the merged document - 合并后的文档
- validate
  
  public static JsonSchemaValidator.ValidationResult validate(JsonNode data, JsonNode schema)
  
  Validates JSON against a schema. 根据 schema 验证 JSON。
  
  Parameters:
  
  data - the data to validate - 要验证的数据
  
  schema - the JSON Schema - JSON Schema
  
  Returns:
  
  the validation result - 验证结果
- validateOrThrow
  
  public static void validateOrThrow(JsonNode data, JsonNode schema)
  
  Validates and throws if invalid. 验证，如果无效则抛出异常。
  
  Parameters:
  
  data - the data to validate - 要验证的数据
  
  schema - the JSON Schema - JSON Schema
- createReader
  
  public static JsonReader createReader(InputStream input)
  
  Creates a JsonReader for an InputStream. 为输入流创建 JsonReader。
  
  Parameters:
  
  input - the input stream - 输入流
  
  Returns:
  
  the JSON reader - JSON 读取器
- createReader
  
  public static JsonReader createReader(Reader reader)
  
  Creates a JsonReader for a Reader. 为 Reader 创建 JsonReader。
  
  Parameters:
  
  reader - the reader - Reader
  
  Returns:
  
  the JSON reader - JSON 读取器
- createWriter
  
  public static JsonWriter createWriter(OutputStream output)
  
  Creates a JsonWriter for an OutputStream. 为输出流创建 JsonWriter。
  
  Parameters:
  
  output - the output stream - 输出流
  
  Returns:
  
  the JSON writer - JSON 写入器
- createWriter
  
  public static JsonWriter createWriter(Writer writer)
  
  Creates a JsonWriter for a Writer. 为 Writer 创建 JsonWriter。
  
  Parameters:
  
  writer - the writer - Writer
  
  Returns:
  
  the JSON writer - JSON 写入器
- serialize
  
  public String serialize(Object obj)
  
  Serializes an object to JSON string. 将对象序列化为 JSON 字符串。
  
  Parameters:
  
  obj - the object - 对象
  
  Returns:
  
  the JSON string - JSON 字符串
- serializeToBytes
  
  public byte[] serializeToBytes(Object obj)
  
  Serializes an object to JSON bytes. 将对象序列化为 JSON 字节数组。
  
  Parameters:
  
  obj - the object - 对象
  
  Returns:
  
  the JSON bytes - JSON 字节数组
- serialize
  
  public void serialize(Object obj, OutputStream output)
  
  Serializes an object to an OutputStream. 将对象序列化到输出流。
  
  Parameters:
  
  obj - the object - 对象
  
  output - the output stream - 输出流
- serialize
  
  public void serialize(Object obj, Writer writer)
  
  Serializes an object to a Writer. 将对象序列化到 Writer。
  
  Parameters:
  
  obj - the object - 对象
  
  writer - the writer - Writer
- deserialize
  
  public <T> T deserialize(String json, Class<T> clazz)
  
  Deserializes JSON to an object. 将 JSON 反序列化为对象。
  
  Type Parameters:
  
  T - the target type - 目标类型
  
  Parameters:
  
  json - the JSON string - JSON 字符串
  
  clazz - the target class - 目标类
  
  Returns:
  
  the object - 对象
- deserialize
  
  public <T> T deserialize(String json, TypeReference<T> typeReference)
  
  Deserializes JSON using TypeReference. 使用 TypeReference 反序列化 JSON。
  
  Type Parameters:
  
  T - the target type - 目标类型
  
  Parameters:
  
  json - the JSON string - JSON 字符串
  
  typeReference - the type reference - 类型引用
  
  Returns:
  
  the object - 对象
- deserialize
  
  public <T> T deserialize(byte[] json, Class<T> clazz)
  
  Deserializes JSON bytes. 反序列化 JSON 字节数组。
  
  Type Parameters:
  
  T - the target type - 目标类型
  
  Parameters:
  
  json - the JSON bytes - JSON 字节数组
  
  clazz - the target class - 目标类
  
  Returns:
  
  the object - 对象
- deserialize
  
  public <T> T deserialize(InputStream input, Class<T> clazz)
  
  Deserializes from InputStream. 从输入流反序列化。
  
  Type Parameters:
  
  T - the target type - 目标类型
  
  Parameters:
  
  input - the input stream - 输入流
  
  clazz - the target class - 目标类
  
  Returns:
  
  the object - 对象
- deserialize
  
  public <T> T deserialize(Reader reader, Class<T> clazz)
  
  Deserializes from Reader. 从 Reader 反序列化。
  
  Type Parameters:
  
  T - the target type - 目标类型
  
  Parameters:
  
  reader - the reader - Reader
  
  clazz - the target class - 目标类
  
  Returns:
  
  the object - 对象
- deserializeArray
  
  public <T> List<T> deserializeArray(String json, Class<T> elementType)
  
  Deserializes JSON array to List. 将 JSON 数组反序列化为 List。
  
  Type Parameters:
  
  T - the element type - 元素类型
  
  Parameters:
  
  json - the JSON string - JSON 字符串
  
  elementType - the element type - 元素类型
  
  Returns:
  
  the list - 列表
- deserializeMap
  
  public <K,V> Map<K,V> deserializeMap(String json, Class<K> keyType, Class<V> valueType)
  
  Deserializes JSON object to Map. 将 JSON 对象反序列化为 Map。
  
  Type Parameters:
  
  K - the key type - 键类型
  
  V - the value type - 值类型
  
  Parameters:
  
  json - the JSON string - JSON 字符串
  
  keyType - the key type - 键类型
  
  valueType - the value type - 值类型
  
  Returns:
  
  the map - Map
- parseTree
  
  public JsonNode parseTree(String json)
  
  Parses JSON to tree. 将 JSON 解析为树。
  
  Parameters:
  
  json - the JSON string - JSON 字符串
  
  Returns:
  
  the root node - 根节点
- parseTree
  
  public JsonNode parseTree(byte[] json)
  
  Parses JSON bytes to tree. 将 JSON 字节数组解析为树。
  
  Parameters:
  
  json - the JSON bytes - JSON 字节数组
  
  Returns:
  
  the root node - 根节点
- valueToTree
  
  public JsonNode valueToTree(Object obj)
  
  Converts object to tree. 将对象转换为树。
  
  Parameters:
  
  obj - the object - 对象
  
  Returns:
  
  the JSON node - JSON 节点
- treeToObject
  
  public <T> T treeToObject(JsonNode node, Class<T> clazz)
  
  Converts tree to object. 将树转换为对象。
  
  Type Parameters:
  
  T - the target type - 目标类型
  
  Parameters:
  
  node - the JSON node - JSON 节点
  
  clazz - the target class - 目标类
  
  Returns:
  
  the object - 对象
- getConfig
  
  public JsonConfig getConfig()
  
  Returns the configuration. 返回配置。
  
  Returns:
  
  the config - 配置
- getProvider
  
  public JsonProvider getProvider()
  
  Returns the provider. 返回提供者。
  
  Returns:
  
  the provider - 提供者

Class OpenJson

Method Summary

Methods inherited from class Object

Method Details

withConfig

withProvider

withConfigAndProvider

toJson

toJsonBytes

toJson

toJson

toPrettyJson

fromJson

fromJson

fromJson

fromJson

fromJson

fromJsonArray

fromJsonMap

parse

parse

toTree

treeToValue

at

select

selectFirst

diff

patch

mergePatch

validate

validateOrThrow

createReader

createReader

createWriter

createWriter

serialize

serializeToBytes

serialize

serialize

deserialize

deserialize

deserialize

deserialize

deserialize

deserializeArray

deserializeMap

parseTree

parseTree

valueToTree

treeToObject

getConfig

getProvider