Hprose 序列化

概述

Hprose 提供了一套自己的序列化格式用来实现高效的跨语言跨平台的数据存储和交换。该序列化格式，在 hprose for Java 中被实现为以下几个对象：

• HproseTags
• HproseMode
• HproseClassManager
• HproseWriter
• HproseReader
• HproseFormatter

HproseTags 对象中包含了所有的 Hprose 序列化和 RPC 标记定义。Hprose 的使用者通常不需要关心该对象，因此这里不对该对象做详细介绍。

HproseMode 是一个枚举类型，表示序列化模式。其中包含了三个值：

• FieldMode
• PropertyMode
• MemberMode

FieldMode 模式下只序列化 Java 类中的字段，包括私有字段，但是静态字段和 transient 字段不会序列化。

PropertyMode 模式下只序列化 Java 类中的 public 可读写属性。

MemberMode 模式下序列化 Java 类中的 public 可读写属性和字段，但不包括静态字段和 transient 字段。

HproseClassManager 用于管理自定义类型与其它语言之间的映射关系。

HproseWriter 用于进行细粒度的 Hprose 序列化操作。

HproseReader 用于进行细粒度的 Hprose 反序列化操作。

HproseFormatter 用于进行粗粒度的 Hprose 序列化和反序列化操作。

这些类都包含在 hprose.io 包中。下面我们将对这几个类进行详细的介绍。

HproseClassManager 类

register 方法

HproseClassManager.register(class, alias);

当 Hprose 序列化对象时，需要知道对象的类名，但有时候，我们在不同的语言中定义的类名可能不同，但结构相同或相近，我们希望这些定义不同的类的对象可以相互传递。那么就需要使用该方法来进行注册，注册成统一的别名之后，就可以相互传递了。

其中 class 表示要注册的类，alias 表示注册的别名。例如：

package hprose.example.io;

public class User {
    public String name;
    public int age;
}
...
HproseClassManager.register(User.class, "User");

在很多语言中，类名是有名称空间（NameSpace）的，例如上面的代码中，就是这样一个类：hprose.example.io.User，但也有写没有名称空间的概念，或者名称空间和类之间的分隔符不是用 .，而是用 : 或者 \ 等符号。比如假设我们在 PHP 中定义了一个 My\Model\User 类，但是并没有执行这个注册，我们又希望能够跟它交互，我们可以这样注册：

HproseClassManager.register(User.class, "My_Model_User");

注意上面的别名中，不是使用 . 做分隔符的，而是使用 _，Hprose 会自动将 _ 转换为对应语言的分隔符，对于不支持名称空间的语言，则直接对应 My_Model_User 这个名字，这样既可以支持没有名称空间的语言，也可以支持具有名称空间的语言。

getClassAlias 方法

HproseClassManager.getClassAlias(class);

通过类来查找别名，

getClass 方法

HproseClassManager.getClass(alias);

通过别名来查找注册的类。

containsClass 方法

HproseClassManager.containsClass(alias);

返回别名是否已注册，已注册返回 true，否则返回 false。

下面来举一个完整的例子，来看一下上面几个方法是如何工作的：

package hprose.example.io;

import hprose.io.HproseClassManager;

public class ClassManagerExam {
    public static void main(String[] args) {
        HproseClassManager.register(User.class, "my_package_User");
        System.out.println(HproseClassManager.getClassAlias(User.class));
        System.out.println(HproseClassManager.getClass("my_package_User"));
        System.out.println(HproseClassManager.getClass("User"));
        System.out.println(HproseClassManager.containsClass("my_package_User"));
        System.out.println(HproseClassManager.containsClass("User"));
    }
}

输出结果为：

my_package_User
class hprose.example.io.User
null
true
false

HproseWriter 类

构造器

public HproseWriter(OutputStream stream);
public HproseWriter(OutputStream stream, boolean simple);
public HproseWriter(OutputStream stream, HproseMode mode);
public HproseWriter(OutputStream stream, HproseMode mode, boolean simple);

stream 参数是一个 OutputStream 的实例对象，序列化数据将会写入到该对象中。

mode 参数表示序列化对象的方式，三种方式在上面介绍 HproseMode 时大致上已经介绍过了。

simple 参数如果为 true，则不使用引用方式序列化，通常在序列化的数据中不包含引用类型数据时，设置为 true 可以加快速度。当包含引用类型数据时，需要设置为 false（即默认值），尤其是当引用数据中包括递归数据时，如果不使用引用方式，会陷入死循环导致堆栈溢出的错误。

stream 字段

只读字段，返回当前用于写入序列化数据的 OutputStream 实例对象。该字段的值即上面构造器中的第一个参数。

serialize 方法

public final void serialize(Object obj) throws IOException;

该方法是 HproseWriter 的核心方法，功能是将任意对象序列化到 HproseWriter 所写入的流中。这里来举几个例子：

package hprose.example.io;

import hprose.io.ByteBufferStream;
import hprose.io.HproseClassManager;
import hprose.io.HproseWriter;
import hprose.util.StrUtil;
import java.io.IOException;

public class WriterExam {
    public static void main(String[] args) throws IOException {
        HproseClassManager.register(User.class, "my_package_User");
        ByteBufferStream stream = new ByteBufferStream();
        HproseWriter writer = new HproseWriter(stream.getOutputStream());
        writer.serialize(0);
        writer.serialize(1);
        writer.serialize(2);
        writer.serialize(3);
        writer.serialize(123);
        writer.serialize(3.14);
        writer.serialize("hello");
        writer.serialize("你好🇨🇳");
        writer.serialize(new char[] {'x', 'y', 'z'});
        writer.serialize(new Object[] {"x", "y", "z"});
        System.out.println(StrUtil.toString(stream));
        stream.rewind();
        User user = new User();
        user.name = "Tom";
        user.age = 18;
        writer.serialize(user);
        System.out.println(StrUtil.toString(stream));
    }
}

输出结果如下：

0123i123;d3.14;s5"hello"s6"你好🇨🇳"s3"xyz"a3{uxuyuz}
c15"my_package_User"2{s4"name"s3"age"}o0{s3"Tom"i18;}

writeInteger 方法

public final void writeInteger(int i) throws IOException;

序列化 int 类型数据 i。

writeLong 方法

public final void writeLong(long l) throws IOException;

序列化 long 类型数据 l。

writeBigInteger 方法

public final void writeBigInteger(BigInteger bi) throws IOException;

序列化 BigInteger 类型数据 bi。

writeFloat 方法

public final void writeFloat(float f) throws IOException;

序列化 float 类型数据 f。

writeDouble 方法

public final void writeDouble(double d) throws IOException;

序列化 double 类型数据 d。

writeBigDecimal 方法

public final void writeBigDecimal(BigDecimal bd) throws IOException;

序列化 BigDecimal 类型数据 bd。

writeNaN 方法

public final void writeNaN() throws IOException;

序列化 NaN。

writeInfinity 方法

public final void writeInfinity(boolean positive) throws IOException;

序列化正负无穷大。

writeNull 方法

public final void writeNull() throws IOException;

序列化 null。

writeEmpty 方法

public final void writeEmpty() throws IOException;

序列化空串。

writeBoolean 方法

public final void writeBoolean(boolean b) throws IOException;

序列化 boolean 类型数据 b。

writeDate 方法

public final void writeDate(Date date) throws IOException;
public final void writeDate(Time time) throws IOException;
public final void writeDate(Timestamp time) throws IOException;
public final void writeDate(java.util.Date date) throws IOException;
public final void writeDate(Calendar calendar) throws IOException;

序列化日期时间类型数据。

public final void writeDateWithRef(Date date) throws IOException;
public final void writeDateWithRef(Time time) throws IOException;
public final void writeDateWithRef(Timestamp time) throws IOException;
public final void writeDateWithRef(java.util.Date date) throws IOException;
public final void writeDateWithRef(Calendar calendar) throws IOException;

序列化日期时间类型数据。如果该值之前被序列化过，则作为引用序列化。

public final void writeTime(Time time) throws IOException;
public final void writeTimeWithRef(Time time) throws IOException;

这俩方法仅仅是 writeDate 和 writeDateWithRef 方法的别名。

writeBytes 方法

public final void writeBytes(byte[] bytes) throws IOException;

序列化 byte[] 类型数据。

public final void writeBytesWithRef(byte[] bytes) throws IOException;

序列化 byte[] 类型数据。如果该值之前被序列化过，则作为引用序列化。

writeUTF8Char 方法

public final void writeUTF8Char(char c) throws IOException;

序列化字符类型 c。

writeString 方法

public final void writeString(String s) throws IOException;
public final void writeString(StringBuilder s) throws IOException;
public final void writeString(StringBuffer s) throws IOException;
public final void writeString(char[] s) throws IOException;

序列化字符串类型数据。

public final void writeStringWithRef(String s) throws IOException;
public final void writeStringWithRef(StringBuilder s) throws IOException;
public final void writeStringWithRef(StringBuffer s) throws IOException;
public final void writeStringWithRef(char[] s) throws IOException;

序列化字符串类型数据。如果该值之前被序列化过，则作为引用序列化。

writeUUID 方法

public final void writeUUID(UUID uuid) throws IOException;

序列化 UUID 类型数据。

public final void writeUUIDWithRef(UUID uuid) throws IOException;

序列化 UUID 类型数据。如果该值之前被序列化过，则作为引用序列化。

writeArray 方法

public final void writeArray(short[] array) throws IOException;
public final void writeArray(int[] array) throws IOException;
public final void writeArray(long[] array) throws IOException;
public final void writeArray(float[] array) throws IOException;
public final void writeArray(double[] array) throws IOException;
public final void writeArray(boolean[] array) throws IOException;
public final void writeArray(Date[] array) throws IOException;
public final void writeArray(Time[] array) throws IOException;
public final void writeArray(Timestamp[] array) throws IOException;
public final void writeArray(java.util.Date[] array) throws IOException;
public final void writeArray(Calendar[] array) throws IOException;
public final void writeArray(String[] array) throws IOException;
public final void writeArray(StringBuilder[] array) throws IOException;
public final void writeArray(StringBuffer[] array) throws IOException;
public final void writeArray(UUID[] array) throws IOException;
public final void writeArray(char[][] array) throws IOException;
public final void writeArray(byte[][] array) throws IOException;
public final void writeArray(BigInteger[] array) throws IOException;
public final void writeArray(BigDecimal[] array) throws IOException;
public final void writeArray(Object[] array) throws IOException;
public final void writeArray(AtomicIntegerArray array) throws IOException;
public final void writeArray(AtomicLongArray array) throws IOException;
public final void writeArray(AtomicReferenceArray array) throws IOException;
public final void writeArray(Object array) throws IOException;

序列化各种数组类型数据。

public final void writeArrayWithRef(short[] array) throws IOException;
public final void writeArrayWithRef(int[] array) throws IOException;
public final void writeArrayWithRef(long[] array) throws IOException;
public final void writeArrayWithRef(float[] array) throws IOException;
public final void writeArrayWithRef(double[] array) throws IOException;
public final void writeArrayWithRef(boolean[] array) throws IOException;
public final void writeArrayWithRef(Date[] array) throws IOException;
public final void writeArrayWithRef(Time[] array) throws IOException;
public final void writeArrayWithRef(Timestamp[] array) throws IOException;
public final void writeArrayWithRef(java.util.Date[] array) throws IOException;
public final void writeArrayWithRef(Calendar[] array) throws IOException;
public final void writeArrayWithRef(String[] array) throws IOException;
public final void writeArrayWithRef(StringBuilder[] array) throws IOException;
public final void writeArrayWithRef(StringBuffer[] array) throws IOException;
public final void writeArrayWithRef(UUID[] array) throws IOException;
public final void writeArrayWithRef(char[][] array) throws IOException;
public final void writeArrayWithRef(byte[][] array) throws IOException;
public final void writeArrayWithRef(BigInteger[] array) throws IOException;
public final void writeArrayWithRef(BigDecimal[] array) throws IOException;
public final void writeArrayWithRef(Object[] array) throws IOException;
public final void writeArrayWithRef(AtomicIntegerArray array) throws IOException;
public final void writeArrayWithRef(AtomicLongArray array) throws IOException;
public final void writeArrayWithRef(AtomicReferenceArray array) throws IOException;
public final void writeArrayWithRef(Object array) throws IOException;

序列化各种数组类型数据。如果该值之前被序列化过，则作为引用序列化。

writeCollection 方法

public final void writeCollection(Collection<?> collection) throws IOException;

序列化各种 Collection 类型。

public final void writeCollectionWithRef(Collection<?> collection) throws IOException;

序列化各种 Collection 类型。如果该值之前被序列化过，则作为引用序列化。

writeList 方法

public final void writeList(List<?> list) throws IOException;

序列化各种 List 类型。

public final void writeListWithRef(List<?> list) throws IOException;

序列化各种 List 类型。如果该值之前被序列化过，则作为引用序列化。

writeMap 方法

public final void writeMap(Map<?, ?> map) throws IOException;

序列化各种 Map 类型。

public final void writeMapWithRef(Map<?, ?> map) throws IOException;

序列化各种 Map 类型。如果该值之前被序列化过，则作为引用序列化。

writeObject 方法

public final void writeObject(Object object) throws IOException;

序列化自定义类型对象类型。

public final void writeObjectWithRef(Object object) throws IOException;

序列化自定义类型对象类型。如果该值之前被序列化过，则作为引用序列化。

reset 方法

public final void reset();

将序列化的引用计数器重置。

HproseReader 类

构造器

public HproseReader(InputStream stream);
public HproseReader(InputStream stream, boolean simple);
public HproseReader(InputStream stream, HproseMode mode);
public HproseReader(InputStream stream, HproseMode mode, boolean simple);
public HproseReader(ByteBuffer buffer);
public HproseReader(ByteBuffer buffer, boolean simple);
public HproseReader(ByteBuffer buffer, HproseMode mode);
public HproseReader(ByteBuffer buffer, HproseMode mode, boolean simple);
public HproseReader(byte[] bytes);
public HproseReader(byte[] bytes, boolean simple);
public HproseReader(byte[] bytes, HproseMode mode);
public HproseReader(byte[] bytes, HproseMode mode, boolean simple)

stream、buffer 或 bytes 是数据源，反序列化的数据将会从该对象中读取。

mode 参数表示序列化对象的方式，三种方式在上面介绍 HproseMode 时大致上已经介绍过了。

simple 如果为 true，则不使用引用方式反序列化，通常在反序列化的数据中不包含引用类型数据时，设置为 true 可以加快速度。当包含引用类型数据时，需要设置为 false（即默认值），否则会抛出异常。

stream 字段

只读字段，返回当前用于读取反序列化数据的 InputStream 实例对象。

checkTag 方法

public final void checkTag(int tag, int expectTag) throws HproseException;
public final void checkTag(int expectTag) throws IOException;

如果 tag 参数不存在，则自动读取当前流中的一个字符作为 tag 值。如果 expectTag 和 tag 不一致，则抛出异常。

该方法没有返回值。

checkTags 方法

public final int checkTags(int tag, String expectTags) throws IOException;
public final int checkTags(String expectTags) throws IOException;

如果 tag 参数不存在，则自动读取当前流中的一个字符作为 tag 值。如果 expectTags 中不包含 tag，则抛出异常。

expectTags 是一个字符串，该字符串中包含一个或多个 HproseTags 中的枚举值，但通常不会用其它取值。

如果该方法执行成功，返回 tag 值。

unserialize 方法

public final Object unserialize() throws IOException;
public final Object unserialize(Type type) throws IOException;
public final <T> T unserialize(Class<T> type) throws IOException;

从当前数据流中读取数据并返回反序列化结果。如果当前数据流中包含有多个序列化数据，则一次只返回一个结果。

如果反序列化过程中发生错误，则会抛出异常。

参数为要反序列化的数据类型，如果未指定，则按照数据的默认类型返回。

下面我们来举一个例子：

package hprose.example.io;

import hprose.io.ByteBufferStream;
import hprose.io.HproseClassManager;
import hprose.io.HproseReader;
import hprose.io.HproseWriter;
import java.io.IOException;
import java.util.Arrays;

public class ReaderExam {
    public static void main(String[] args) throws IOException {
        HproseClassManager.register(User.class, "my_package_User");
        ByteBufferStream stream = new ByteBufferStream();
        HproseWriter writer = new HproseWriter(stream.getOutputStream());
        writer.serialize(0);
        writer.serialize(1);
        writer.serialize(2);
        writer.serialize(3);
        writer.serialize(123);
        writer.serialize(3.14);
        writer.serialize("hello");
        writer.serialize("你好🇨🇳");
        writer.serialize(new char[] {'x', 'y', 'z'});
        writer.serialize(new Object[] {"x", "y", "z"});
        User user = new User();
        user.name = "Tom";
        user.age = 18;
        writer.serialize(user);
        stream.flip();
        HproseReader reader = new HproseReader(stream.getInputStream());
        System.out.println(reader.unserialize());
        System.out.println(reader.unserialize());
        System.out.println(reader.unserialize());
        System.out.println(reader.unserialize());
        System.out.println(reader.unserialize());
        System.out.println(reader.unserialize());
        System.out.println(reader.unserialize());
        System.out.println(reader.unserialize());
        System.out.println(Arrays.toString(reader.unserialize(char[].class)));
        System.out.println(reader.unserialize());
        User user2 = reader.unserialize(User.class);
        System.out.println(user2.name);
        System.out.println(user2.age);
    }
}

该程序运行结果为：

0
1
2
3
123
3.14
hello
你好🇨🇳
[x, y, z]
[x, y, z]
Tom
18

reset 方法

public final void reset();

将反序列化的引用计数器重置。

readInt 方法

public final byte readByte(int tag) throws IOException;
public final short readShort(int tag) throws IOException;
public final int readInt(int tag) throws IOException;
public final long readLong(int tag) throws IOException;

从当前位置开始读取，直到遇到 tag 为止。并将读取的字符串转换为整数。该方法主要用于服务协议解析，用户通常用不到该方法。

readIntWithoutTag 方法

public final int readIntWithoutTag() throws IOException

从当前数据流中反序列化一个 int 结果并返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagInteger。

如果反序列化过程中发生错误，则会抛出异常。

readBigIntegerWithoutTag 方法

public final BigInteger readBigIntegerWithoutTag() throws IOException

从当前数据流中反序列化一个 BigInteger 结果并返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagInteger 或 HproseTags.TagLong。

如果反序列化过程中发生错误，则会抛出异常。

readLongWithoutTag 方法

public final long readLongWithoutTag() throws IOException;

从当前数据流中反序列化一个 long 结果并返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagInteger 或 HproseTags.TagLong。

如果反序列化过程中发生错误，则会抛出异常。

readDoubleWithoutTag 方法

public final double readDoubleWithoutTag() throws IOException;

从当前数据流中反序列化一个 double 结果并返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagInteger, HproseTags.TagLong 或 HproseTags.TagDouble。

readInfinityWithoutTag 方法

public final double readInfinityWithoutTag() throws IOException;

从当前数据流中反序列化一个无穷大结果并返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagInfinity。

readDateWithoutTag 方法

public final Calendar readDateWithoutTag()throws IOException;

从当前数据流中反序列化一个日期（日期时间）型数据并以 Calendar 类型返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagDate。

readTimeWithoutTag 方法

public final Calendar readTimeWithoutTag() throws IOException;

从当前数据流中反序列化一个时间型数据并以 Calendar 类型返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagTime。

readBytesWithoutTag 方法

public final byte[] readBytesWithoutTag() throws IOException;

从当前数据流中反序列化一个 byte[] 结果并返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagBytes。

readUTF8CharWithoutTag 方法

public final String readUTF8CharWithoutTag() throws IOException;

从当前数据流中反序列化一个 UTF8Char 类型的数据，并以 String 结果返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagUTF8Char。

readStringWithoutTag 方法

public final String readStringWithoutTag() throws IOException;

从当前数据流中反序列化一个 String 结果并返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagString。

readCharsWithoutTag 方法

public final char[] readCharsWithoutTag() throws IOException;

从当前数据流中反序列化一个 char[] 结果并返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagString。

readUUIDWithoutTag 方法

public final UUID readUUIDWithoutTag() throws IOException;

从当前数据流中反序列化一个 UUID 结果并返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagGuid。

readListWithoutTag 方法

public final ArrayList readListWithoutTag() throws IOException;

从当前数据流中反序列化一个 ArrayList 结果并返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagList。

readMapWithoutTag 方法

public final HashMap readMapWithoutTag() throws IOException

从当前数据流中反序列化一个 HashMap 结果并返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagMap。

readObjectWithoutTag 方法

public final Object readObjectWithoutTag(Class<?> type) throws IOException;

从当前数据流中反序列化一个 Object 结果并返回，该方法假设序列化标记已被读取，并且其值为 HproseTags.TagObject。