Interface JsonProvider

public interface JsonProvider
JSON Provider - SPI Interface for JSON Processing Engines JSON 提供者 - JSON 处理引擎的 SPI 接口

This interface defines the contract for JSON processing implementations. Implementations can wrap Jackson, Gson, Fastjson2, or other JSON libraries.

此接口定义 JSON 处理实现的契约。实现可以包装 Jackson、Gson、Fastjson2 或其他 JSON 库。

Implementation Notes | 实现注意事项:

  • Implementations must be thread-safe - 实现必须是线程安全的
  • All methods should respect the provided JsonConfig - 所有方法应遵循提供的 JsonConfig
  • Implementations should register via ServiceLoader - 实现应通过 ServiceLoader 注册

Features | 主要功能:

  • SPI interface for pluggable JSON engines - 可插拔JSON引擎的SPI接口
  • Full serialization, deserialization, tree model, and streaming API - 完整的序列化、反序列化、树模型和流式API
  • Provider priority and availability management - 提供者优先级和可用性管理

Usage Examples | 使用示例:

// Implement the JsonProvider interface
// 实现 JsonProvider 接口

Security | 安全性:

  • Thread-safe: Implementation-dependent - 线程安全: 取决于实现
  • Null-safe: No - 空值安全: 否
Since:
JDK 25, opencode-base-json V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • getName

      String getName()
      Returns the provider name (e.g., "jackson", "gson", "fastjson2"). 返回提供者名称（如 "jackson"、"gson"、"fastjson2"）。
      Returns:
      the provider name - 提供者名称

    • getVersion

      String getVersion()
      Returns the provider version. 返回提供者版本。
      Returns:
      the version string - 版本字符串

    • getPriority

      default int getPriority()
      Returns the priority of this provider (higher = preferred). 返回此提供者的优先级（越高越优先）。
      Returns:
      the priority (default 0) - 优先级（默认0）

    • isAvailable

      default boolean isAvailable()
      Returns whether this provider is available. 返回此提供者是否可用。
      Returns:
      true if available - 如果可用则返回 true

    • configure

      void configure(JsonConfig config)
      Configures this provider with the given configuration. 使用给定配置配置此提供者。
      Parameters:
      config - the configuration - 配置

    • supportsFeature

      boolean supportsFeature(JsonFeature feature)
      Returns whether a feature is supported by this provider. 返回此提供者是否支持某特性。
      Parameters:
      feature - the feature to check - 要检查的特性
      Returns:
      true if supported - 如果支持则返回 true

    • toJson

      String toJson(Object obj)
      Serializes an object to a JSON string. 将对象序列化为 JSON 字符串。
      Parameters:
      obj - the object to serialize - 要序列化的对象
      Returns:
      the JSON string - JSON 字符串

    • toJsonBytes

      byte[] toJsonBytes(Object obj)
      Serializes an object to a JSON byte array. 将对象序列化为 JSON 字节数组。
      Parameters:
      obj - the object to serialize - 要序列化的对象
      Returns:
      the JSON bytes - JSON 字节数组

    • toJson

      void toJson(Object obj, OutputStream output)
      Serializes an object to an OutputStream. 将对象序列化到输出流。
      Parameters:
      obj - the object to serialize - 要序列化的对象
      output - the output stream - 输出流

    • toJson

      void toJson(Object obj, Writer writer)
      Serializes an object to a Writer. 将对象序列化到 Writer。
      Parameters:
      obj - the object to serialize - 要序列化的对象
      writer - the writer - Writer

    • fromJson

      <T> T fromJson(String json, Class<T> clazz)
      Deserializes a JSON string to an object of the specified class. 将 JSON 字符串反序列化为指定类的对象。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON string - JSON 字符串
      clazz - the target class - 目标类
      Returns:
      the deserialized object - 反序列化的对象

    • fromJson

      <T> T fromJson(String json, Type type)
      Deserializes a JSON string to an object of the specified type. 将 JSON 字符串反序列化为指定类型的对象。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON string - JSON 字符串
      type - the target type - 目标类型
      Returns:
      the deserialized object - 反序列化的对象

    • fromJson

      <T> T fromJson(String json, TypeReference<T> typeReference)
      Deserializes a JSON string using a TypeReference. 使用 TypeReference 反序列化 JSON 字符串。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON string - JSON 字符串
      typeReference - the type reference - 类型引用
      Returns:
      the deserialized object - 反序列化的对象

    • fromJson

      <T> T fromJson(byte[] json, Class<T> clazz)
      Deserializes JSON bytes to an object of the specified class. 将 JSON 字节数组反序列化为指定类的对象。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON bytes - JSON 字节数组
      clazz - the target class - 目标类
      Returns:
      the deserialized object - 反序列化的对象

    • fromJson

      <T> T fromJson(byte[] json, TypeReference<T> typeReference)
      Deserializes JSON bytes using a TypeReference. 使用 TypeReference 反序列化 JSON 字节数组。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON bytes - JSON 字节数组
      typeReference - the type reference - 类型引用
      Returns:
      the deserialized object - 反序列化的对象

    • fromJson

      <T> T fromJson(InputStream input, Class<T> clazz)
      Deserializes from an InputStream to an object of the specified class. 从输入流反序列化为指定类的对象。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      input - the input stream - 输入流
      clazz - the target class - 目标类
      Returns:
      the deserialized object - 反序列化的对象

    • fromJson

      <T> T fromJson(Reader reader, Class<T> clazz)
      Deserializes from a Reader to an object of the specified class. 从 Reader 反序列化为指定类的对象。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      reader - the reader - Reader
      clazz - the target class - 目标类
      Returns:
      the deserialized object - 反序列化的对象

    • fromJsonArray

      <T> List<T> fromJsonArray(String json, Class<T> elementType)
      Deserializes a JSON array to a List. 将 JSON 数组反序列化为 List。
      Type Parameters:
      T - the element type - 元素类型
      Parameters:
      json - the JSON string - JSON 字符串
      elementType - the element type - 元素类型
      Returns:
      the list - 列表

    • fromJsonMap

      <K,V> Map<K,V> fromJsonMap(String json, Class<K> keyType, Class<V> valueType)
      Deserializes a JSON object to a 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

      JsonNode parseTree(String json)
      Parses a JSON string to a JsonNode tree. 将 JSON 字符串解析为 JsonNode 树。
      Parameters:
      json - the JSON string - JSON 字符串
      Returns:
      the root node - 根节点

    • parseTree

      JsonNode parseTree(byte[] json)
      Parses JSON bytes to a JsonNode tree. 将 JSON 字节数组解析为 JsonNode 树。
      Parameters:
      json - the JSON bytes - JSON 字节数组
      Returns:
      the root node - 根节点

    • treeToValue

      <T> T treeToValue(JsonNode node, Class<T> clazz)
      Converts a JsonNode to an object of the specified class. 将 JsonNode 转换为指定类的对象。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      node - the JSON node - JSON 节点
      clazz - the target class - 目标类
      Returns:
      the converted object - 转换后的对象

    • valueToTree

      JsonNode valueToTree(Object obj)
      Converts an object to a JsonNode tree. 将对象转换为 JsonNode 树。
      Parameters:
      obj - the object - 对象
      Returns:
      the JSON node - JSON 节点

    • createReader

      JsonReader createReader(InputStream input)
      Creates a JsonReader for the given input stream. 为给定输入流创建 JsonReader。
      Parameters:
      input - the input stream - 输入流
      Returns:
      the JSON reader - JSON 读取器

    • createReader

      JsonReader createReader(Reader reader)
      Creates a JsonReader for the given reader. 为给定 Reader 创建 JsonReader。
      Parameters:
      reader - the reader - Reader
      Returns:
      the JSON reader - JSON 读取器

    • createWriter

      JsonWriter createWriter(OutputStream output)
      Creates a JsonWriter for the given output stream. 为给定输出流创建 JsonWriter。
      Parameters:
      output - the output stream - 输出流
      Returns:
      the JSON writer - JSON 写入器

    • createWriter

      JsonWriter createWriter(Writer writer)
      Creates a JsonWriter for the given writer. 为给定 Writer 创建 JsonWriter。
      Parameters:
      writer - the writer - Writer
      Returns:
      the JSON writer - JSON 写入器

    • convertValue

      <T> T convertValue(Object obj, Class<T> clazz)
      Converts an object to another type. 将对象转换为另一种类型。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      obj - the source object - 源对象
      clazz - the target class - 目标类
      Returns:
      the converted object - 转换后的对象

    • convertValue

      <T> T convertValue(Object obj, TypeReference<T> typeReference)
      Converts an object to another type using a TypeReference. 使用 TypeReference 将对象转换为另一种类型。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      obj - the source object - 源对象
      typeReference - the type reference - 类型引用
      Returns:
      the converted object - 转换后的对象

    • getUnderlyingProvider

      <T> T getUnderlyingProvider()
      Returns the underlying JSON library object (e.g., ObjectMapper for Jackson). 返回底层 JSON 库对象（如 Jackson 的 ObjectMapper）。
      Type Parameters:
      T - the expected type - 预期类型
      Returns:
      the underlying object - 底层对象

    • copy

      JsonProvider copy()
      Creates a copy of this provider with independent configuration. 创建具有独立配置的此提供者的副本。
      Returns:
      a new provider instance - 新提供者实例