Framework-Docsify/src/docs/asciidoc/mgspack_0.6.x.adoc

= MessagePack Java 0.6.X QuickStart
YuCheng Hu <yhu@ossez.com>
:doctype: book
:page-layout: docs
:page-description: Protocol Buffers
:page-keywords: Protocol Buffers

:imagesdir: images
:includedir: _includes

中文标题【MessagePack Java 0.6.X 快速开始指南】

WARNING: 0.6.x 版本的 MessagePack 已经过期被淘汰了。如果你现在开始使用 MessagePack 话，请不要使用这个版本。
我们再这里保留 0.6.x 版本的内容主要用于参考用途。

最新的 MessagePack 版本请参考: https://github.com/msgpack/msgpack-java 中的项目源代码。

TIP: MessagePack 中文文档请参考： http://docs.ossez.com/messagepack-docs/index.html

TIP: MessagePack 测试和示例源代码： https://github.com/cwiki-us-demo/serialize-deserialize-demo-java


这个指南提供了使用 msgpack-java 的快速指南。在开始的时候，我们将会介绍如何安装 msgpack-java，然后将会运行如何使用 msgpack 来对对象序列化/反序列化（serialize/deserizalize）对象。

== 安装
你可以使用下面 2 种方法来安装 msgpack-java —— 从 maven 下载或者直接构建 jar 包。

=== 从 Maven2 仓库中进行安装
MessagePack 针对 Java 的使用已经发布到 Maven 的中央仓库中（Maven Central Repository）。你可以使用下面的参数来配置你项目的 pom.xml 文件。

[source,xml]
----
<dependency>
    <groupId>org.msgpack</groupId>
    <artifactId>msgpack</artifactId>
    <version>${msgpack.version}</version>
</dependency>
----
你需要将 ${msgpack.version} 替换为当前的 MessagePack 版本，有关可以使用的具体版本你可以访问 http://repo1.maven.org/maven2/org/msgpack/msgpack/ 中的版本。

请注意，在 0.6.x 版本中最新的版本只更新到 0.6.12。

=== 从 git 仓库中进行安装
你可以从代码仓库中获得最新的代码。

[source]
----
$ git clone git@github.com:msgpack/msgpack-java.git
$ cd msgpack-java
$ mvn package
----

使用上面的代码进行编译后u，你将会在 msgpack-java/target 目录中得到 msgpack.jar 包。

同时你也需要 https://code.google.com/p/json-simple/ 和 https://github.com/jboss-javassist/javassist 来让 msgpack.jar 可以在项目中使用。否则你将会收到  NoClassDefFoundError 错误。

== 如何使用
下面是如何使用的示例代码。

=== 使用一个消息打包（message-packable）类
使用注解 '_@Message_' 来让你可以序列化你自己类中对象的 public 字段。

本代码可以在 https://github.com/cwiki-us-demo/messagepack-6-demo-java/blob/master/src/test/java/com/insight/demo/msgpack/MessagePack6Object.java 中下载到本地后进行编译测试。

[source,java]
----
package com.insight.demo.msgpack;

import org.junit.Test;
import org.msgpack.MessagePack;
import org.msgpack.annotation.Message;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.UUID;

import static org.junit.Assert.assertEquals;

/**
 * MessagePack6Objects
 *
 * @author yhu
 */
public class MessagePack6Object {
    final Logger logger = LoggerFactory.getLogger(MessagePack6Object.class);

    /**
     * MessageData Message Object
     */
    @Message // Annotation
    public static class MessageData {
        // public fields are serialized.
        public String uuid;
        public String name;
        public double version;
    }


    /**
     * Test MessagePack6Objects
     */
    @Test
    public void testMessagePack6Objects() {
        logger.debug("MessagePack6Objects for Objects");

        String uuid = UUID.randomUUID().toString();

        // INIT OBJ
        MessageData src = new MessageData();
        src.uuid = uuid;
        src.name = "MessagePack6";
        src.version = 0.6;

        try {
            MessagePack msgPack = new MessagePack();

            // Serialization
            logger.debug("------ Serialization ------");
            byte[] bytes = msgPack.write(src);
            logger.debug("Bytes Array Length: [{}]", bytes.length);

            // Deserialization
            logger.debug("------ Deserialization ------");
            MessageData dst = msgPack.read(bytes, MessageData.class);
            logger.debug("Check Object for UUID: [{}]", dst.uuid);

            assertEquals(uuid, dst.uuid);

        } catch (Exception ex) {
            logger.error("MessagePack Serialization And Deserialization error", ex);
        }
    }
}
----

如果你希望按照顺序序列化多个对象的话，你可以使用  '_Packer_' 和  '_Unpacker_' 多个对象。

这是因为 '_MessagePack.write(Object)_' 和 '_read(byte[])_' 实际上每次都调用创建了 '_Packer_' 和 '_Unpacker_' 对象。

为了使用 '_Packer_' 和  '_Unpacker_' 对象，请调用 '_createPacker(OutputStream)_' 和  '_createUnpacker(InputStream)_'。

本代码可以 https://github.com/cwiki-us-demo/messagepack-6-demo-java/blob/master/src/test/java/com/insight/demo/msgpack/MessagePack6Objects.java 中查看。

[source,java]
----
package com.insight.demo.msgpack;

import org.junit.Test;
import org.msgpack.MessagePack;
import org.msgpack.annotation.Message;
import org.msgpack.packer.Packer;
import org.msgpack.unpacker.Unpacker;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.util.UUID;

import static org.junit.Assert.assertEquals;

/**
 * MessagePack6Objects
 *
 * @author yhu
 */
public class MessagePack6Objects {
    final Logger logger = LoggerFactory.getLogger(MessagePack6Objects.class);

    /**
     * MessageData Message Objects
     */
    @Message // Annotation
    public static class MessageData {
        // public fields are serialized.
        public String uuid;
        public String name;
        public double version;
    }


    /**
     * Test MessagePack6Objects
     */
    @Test
    public void testMessagePack6Objects() {
        logger.debug("MessagePack6Objects for Objects");

        String uuid = UUID.randomUUID().toString();

        // INIT OBJ
        MessageData src1 = new MessageData();
        src1.uuid = uuid;
        src1.name = "MessagePack6-src1";
        src1.version = 0.6;

        MessageData src2 = new MessageData();
        src2.uuid = uuid;
        src2.name = "MessagePack6-src2";
        src2.version = 10.6;

        MessageData src3 = new MessageData();
        src3.uuid = uuid;
        src3.name = "MessagePack6-src3";
        src3.version = 1.6;

        try {
            MessagePack msgPack = new MessagePack();

            // Serialization
            logger.debug("------ Serialization ------");
            ByteArrayOutputStream out = new ByteArrayOutputStream();
            Packer packer = msgPack.createPacker(out);
            packer.write(src1);
            packer.write(src2);
            packer.write(src3);

            byte[] bytes = out.toByteArray();
            logger.debug("Bytes Array Length: [{}]", bytes.length);

            // Deserialization
            logger.debug("------ Deserialization ------");
            ByteArrayInputStream in = new ByteArrayInputStream(bytes);
            Unpacker unpacker = msgPack.createUnpacker(in);

            MessageData dst1 = unpacker.read(MessageData.class);
            MessageData dst2 = unpacker.read(MessageData.class);
            MessageData dst3 = unpacker.read(MessageData.class);

            logger.debug("Check Object for UUID: [{}]", dst1.uuid);

            assertEquals(uuid, dst1.uuid);

        } catch (Exception ex) {
            logger.error("MessagePack Serialization And Deserialization error", ex);
        }
    }
}
----

=== 多种类型变量的序列化和反序列化（serialization/deserialization）

类 '_Packer/Unpacker_' 允许序列化和反序列化多种类型的变量，如后续程序所示。这个类启用序列化和反序列化多种类型的变量和序列化主要类型变量以及包装类，'_String_' 对象，
'_byte[]_' 对象，'_ByteBuffer 对象等的方法相似。

如上面提示的，你可以序列化和反序列化你自己的对象，前提是你自己的对象需要使用 '_@Message_' 注解。

本代码可以在： https://github.com/cwiki-us-demo/messagepack-6-demo-java/blob/master/src/test/java/com/insight/demo/msgpack/MessagePack6Types.java 中找到。

[source,java]
----
package com.insight.demo.msgpack;

import org.junit.Test;
import org.msgpack.MessagePack;
import org.msgpack.packer.Packer;
import org.msgpack.unpacker.Unpacker;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.math.BigInteger;
import java.nio.ByteBuffer;

/**
 * MessagePack6Types
 *
 * @author yhu
 */
public class MessagePack6Types {
    final Logger logger = LoggerFactory.getLogger(MessagePack6Types.class);


    /**
     * Test MessagePack6Types
     */
    @Test
    public void testMessagePack6Types() {
        logger.debug("testMessagePack6Types for Types");

        MessagePack msgpack = new MessagePack();
        try {

            //
            // Serialization
            //
            ByteArrayOutputStream out = new ByteArrayOutputStream();
            Packer packer = msgpack.createPacker(out);

            // Serialize values of primitive types
            packer.write(true); // boolean value
            packer.write(10); // int value
            packer.write(10.5); // double value

            // Serialize objects of primitive wrapper types
            packer.write(Boolean.TRUE);
            packer.write(new Integer(10));
            packer.write(new Double(10.5));

            // Serialize various types of arrays
            packer.write(new int[]{1, 2, 3, 4});
            packer.write(new Double[]{10.5, 20.5});
            packer.write(new String[]{"msg", "pack", "for", "java"});
            packer.write(new byte[]{0x30, 0x31, 0x32}); // byte array

            // Serialize various types of other reference values
            packer.write("MessagePack"); // String object
            packer.write(ByteBuffer.wrap(new byte[]{0x30, 0x31, 0x32})); // ByteBuffer object
            packer.write(BigInteger.ONE); // BigInteger object

            //
            // Deserialization
            //
            byte[] bytes = out.toByteArray();
            ByteArrayInputStream in = new ByteArrayInputStream(bytes);
            Unpacker unpacker = msgpack.createUnpacker(in);

            // to primitive values
            boolean b = unpacker.readBoolean(); // boolean value
            int i = unpacker.readInt(); // int value
            double d = unpacker.readDouble(); // double value

            // to primitive wrapper value
            Boolean wb = unpacker.read(Boolean.class);
            Integer wi = unpacker.read(Integer.class);
            Double wd = unpacker.read(Double.class);

            // to arrays
            int[] ia = unpacker.read(int[].class);
            Double[] da = unpacker.read(Double[].class);
            String[] sa = unpacker.read(String[].class);
            byte[] ba = unpacker.read(byte[].class);

            // to String object, ByteBuffer object, BigInteger object, List object and Map object
            String ws = unpacker.read(String.class);
            ByteBuffer buf = unpacker.read(ByteBuffer.class);
            BigInteger bi = unpacker.read(BigInteger.class);

        } catch (Exception ex) {
            logger.error("MessagePack Serialization And Deserialization error", ex);
        }
    }
}
----

方法 '_Packer#write()_' 允许序列化多种类型的数据。

类 '_Unpacker_' 针对反序列化二进制数据为主要变量，提供了一个反序列化方法。例如，你希望将二进制数据反序列化为 '_boolean_' (或者 '_int_') 数据类型，你可以使用 '_Unpacker_' 中的 '_readBoolean_' (或者 '_readInt_') 方法。

'_Unpacker_' 同时也为参考变量提供了一个读取的方法。这个方法允许为一个参考变量从二进制数据中进行反序列化。参考变量的定义为你将类型指定为一个参数。
例如，你希望反序列化二进制数据到 '_String_' (或者 '_byte[]_') 对象，你必须在调用 '_read(String.class)_' (或者 '_read(byte[].class)_') 方法的时候定义描述。