Interface Serializer

All Known Implementing Classes:
CompressedSerializer, JdkSerializer, JsonSerializer
public interface Serializer
Serializer - Core Serialization Interface 序列化器 - 核心序列化接口

This interface defines the contract for all serializers in the OpenCode serialization framework. Implementations should provide serialization and deserialization capabilities for specific formats.

此接口定义了 OpenCode 序列化框架中所有序列化器的契约。 实现类应为特定格式提供序列化和反序列化能力。

Features | 主要功能:

  • Serialize objects to byte arrays - 将对象序列化为字节数组
  • Deserialize byte arrays to objects - 将字节数组反序列化为对象
  • Support for generic types via TypeReference - 通过 TypeReference 支持泛型类型
  • Format and MIME type identification - 格式和 MIME 类型标识

Usage Examples | 使用示例:

Serializer serializer = new JsonSerializer();

// Serialize
byte[] data = serializer.serialize(user);

// Deserialize
User restored = serializer.deserialize(data, User.class);

// Deserialize generic type
List<User> users = serializer.deserialize(data, new TypeReference<List<User>>() {});

Security | 安全性:

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

  • Method Summary

    Modifier and Type
    Method
    Description
    <T> T
    deserialize(byte[] data, TypeReference<T> typeRef)
    Deserializes byte array to a generic type using TypeReference.
    <T> T
    deserialize(byte[] data, Class<T> type)
    Deserializes byte array to an object of the specified class.
    <T> T
    deserialize(byte[] data, Type type)
    Deserializes byte array using a Type.
    default <T> T
    deserialize(InputStream in, TypeReference<T> typeRef)
    Deserializes a generic type from an input stream.
    default <T> T
    deserialize(InputStream in, Class<T> type)
    Deserializes from an input stream.
    String
    getFormat()
    Returns the format name of this serializer.
    default String
    getMimeType()
    Returns the MIME type for this serializer.
    default SerializerInfo
    info()
    Returns metadata information about this serializer.
    default boolean
    isTextBased()
    Returns whether this serializer produces text output.
    byte[]
    serialize(Object obj)
    Serializes an object to byte array.
    default void
    serialize(Object obj, OutputStream out)
    Serializes an object to an output stream.
    default boolean
    supports(Class<?> type)
    Checks if this serializer supports the given type.

  • Method Details

    • serialize

      byte[] serialize(Object obj)
      Serializes an object to byte array. 将对象序列化为字节数组。
      Parameters:
      obj - the object to serialize - 要序列化的对象
      Returns:
      the serialized bytes - 序列化后的字节数组
      Throws:
      OpenSerializationException - if serialization fails - 如果序列化失败

    • deserialize

      <T> T deserialize(byte[] data, Class<T> type)
      Deserializes byte array to an object of the specified class. 将字节数组反序列化为指定类的对象。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      data - the serialized data - 序列化的数据
      type - the target class - 目标类
      Returns:
      the deserialized object - 反序列化后的对象
      Throws:
      OpenSerializationException - if deserialization fails - 如果反序列化失败

    • deserialize

      <T> T deserialize(byte[] data, TypeReference<T> typeRef)
      Deserializes byte array to a generic type using TypeReference. 使用 TypeReference 将字节数组反序列化为泛型类型。

      This method preserves generic type information that would otherwise be lost due to type erasure.

      此方法保留了由于类型擦除而丢失的泛型类型信息。

      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      data - the serialized data - 序列化的数据
      typeRef - the type reference - 类型引用
      Returns:
      the deserialized object - 反序列化后的对象
      Throws:
      OpenSerializationException - if deserialization fails - 如果反序列化失败

    • deserialize

      <T> T deserialize(byte[] data, Type type)
      Deserializes byte array using a Type. 使用 Type 反序列化字节数组。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      data - the serialized data - 序列化的数据
      type - the target type - 目标类型
      Returns:
      the deserialized object - 反序列化后的对象
      Throws:
      OpenSerializationException - if deserialization fails - 如果反序列化失败

    • getFormat

      String getFormat()
      Returns the format name of this serializer. 返回此序列化器的格式名称。

      Examples: "json", "xml", "kryo", "protobuf", "jdk"

      示例: "json", "xml", "kryo", "protobuf", "jdk"

      Returns:
      the format name - 格式名称

    • getMimeType

      default String getMimeType()
      Returns the MIME type for this serializer. 返回此序列化器的 MIME 类型。
      Returns:
      the MIME type (default: "application/octet-stream") - MIME 类型

    • supports

      default boolean supports(Class<?> type)
      Checks if this serializer supports the given type. 检查此序列化器是否支持给定类型。

      Some serializers have specific type requirements.

      某些序列化器有特定的类型要求。

      Parameters:
      type - the type to check - 要检查的类型
      Returns:
      true if supported - 如果支持则返回 true

    • isTextBased

      default boolean isTextBased()
      Returns whether this serializer produces text output. 返回此序列化器是否产生文本输出。

      Text-based serializers (JSON, XML) can be converted to String without data loss.

      基于文本的序列化器（JSON、XML）可以无损转换为字符串。

      Returns:
      true if text-based - 如果是基于文本的则返回 true

    • serialize

      default void serialize(Object obj, OutputStream out)
      Serializes an object to an output stream. 将对象序列化到输出流。

      Default implementation serializes to byte array then writes to stream.

      默认实现先序列化为字节数组再写入流。

      Parameters:
      obj - the object to serialize | 要序列化的对象
      out - the output stream | 输出流
      Throws:
      OpenSerializationException - if serialization fails | 序列化失败时抛出
      Since:
      JDK 25, opencode-base-serialization V1.0.3

    • deserialize

      default <T> T deserialize(InputStream in, Class<T> type)
      Deserializes from an input stream. 从输入流反序列化。

      Default implementation reads all bytes then deserializes.

      默认实现先读取所有字节再反序列化。

      Type Parameters:
      T - the target type | 目标类型
      Parameters:
      in - the input stream | 输入流
      type - the target class | 目标类
      Returns:
      the deserialized object | 反序列化后的对象
      Throws:
      OpenSerializationException - if deserialization fails | 反序列化失败时抛出
      Since:
      JDK 25, opencode-base-serialization V1.0.3

    • deserialize

      default <T> T deserialize(InputStream in, TypeReference<T> typeRef)
      Deserializes a generic type from an input stream. 从输入流反序列化泛型类型。
      Type Parameters:
      T - the target type | 目标类型
      Parameters:
      in - the input stream | 输入流
      typeRef - the type reference | 类型引用
      Returns:
      the deserialized object | 反序列化后的对象
      Throws:
      OpenSerializationException - if deserialization fails | 反序列化失败时抛出
      Since:
      JDK 25, opencode-base-serialization V1.0.3

    • info

      default SerializerInfo info()
      Returns metadata information about this serializer. 返回此序列化器的元数据信息。
      Returns:
      the serializer info | 序列化器信息
      Since:
      JDK 25, opencode-base-serialization V1.0.3