Package 

Class MessageUnpacker

  • All Implemented Interfaces:
    java.io.Closeable , java.lang.AutoCloseable 
    
public class MessageUnpacker
 implements Closeable

    MessagePack deserializer that converts binary into objects. You can use factory methods of MessagePack class or MessagePack.UnpackerConfig class to create an instance. To read values as statically-typed Java objects, there are two typical use cases.

    One use case is to read objects as Value using unpackValue method. A Value object contains type of the deserialized value as well as the value itself so that you can inspect type of the deserialized values later. You can repeat unpackValue until hasNext method returns false so that you can deserialize sequence of MessagePack values.

    The other use case is to use getNextFormat and getValueType methods followed by unpackXxx methods corresponding to returned type. Following code snipet is a typical application code: 

     MessageUnpacker unpacker = MessagePack.newDefaultUnpacker(...); while(unpacker.hasNext()) { MessageFormat format = unpacker.getNextFormat(); ValueType type = format.getValueType(); int length; ExtensionTypeHeader extension; switch(type) { case NIL: unpacker.unpackNil(); break; case BOOLEAN: unpacker.unpackBoolean(); break; case INTEGER: switch (format) { case UINT64: unpacker.unpackBigInteger(); break; case INT64: case UINT32: unpacker.unpackLong(); break; default: unpacker.unpackInt(); break; } break; case FLOAT: unpacker.unpackDouble(); break; case STRING: unpacker.unpackString(); break; case BINARY: length = unpacker.unpackBinaryHeader(); unpacker.readPayload(new byte[length]); break; case ARRAY: length = unpacker.unpackArrayHeader(); for (int i = 0; i < length; i++) { readRecursively(unpacker); } break; case MAP: length = unpacker.unpackMapHeader(); for (int i = 0; i < length; i++) { readRecursively(unpacker); // key readRecursively(unpacker); // value } break; case EXTENSION: extension = unpacker.unpackExtensionTypeHeader(); unpacker.readPayload(new byte[extension.getLength()]); break; } } }

    • Method Detail

      • getTotalReadBytes

         long getTotalReadBytes()

        Returns total number of read bytes.

        This method returns total of amount of data consumed from the underlying input minus size of dataremained still unused in the current internal buffer.

        Calling reset resets this number to 0.

      • reset

         MessageBufferInput reset(MessageBufferInput in)

        Replaces underlying input.

        This method clears internal buffer, swaps the underlying input with the new given input, then returnsthe old input.

        This method doesn't close the old input.

        Parameters:
        in - new input

      • hasNext

         boolean hasNext()

        Returns true true if this unpacker has more elements.When this returns true, subsequent call to getNextFormat returns anMessageFormat instance. If false, next getNextFormat call will throw an MessageInsufficientBufferException.

      • getNextFormat

         MessageFormat getNextFormat()

        Returns format of the next value.

        Note that this method doesn't consume data from the internal buffer unlike the other unpack methods.Calling this method twice will return the same value.

        To not throw MessageInsufficientBufferException, this method should be called only when hasNext returns true.

      • skipValue

         void skipValue()

        Skip the next value, then move the cursor at the end of the value

      • skipValue

         void skipValue(int count)

        Skip next values, then move the cursor at the end of the value

        Parameters:
        count - number of values to skip

      • unpackNil

         void unpackNil()

        Reads a Nil byte.

      • tryUnpackNil

         boolean tryUnpackNil()

        Peeks a Nil byte and reads it if next byte is a nil value.

        The difference from unpackNil is that unpackNil throws an exception if the next byte is not nil valuewhile this tryUnpackNil method returns false without changing position.

      • unpackFloat

         float unpackFloat()

        Reads a float.

        This method rounds value to the range of float when precision of the read value is larger than the range of float. This may happen when getNextFormat returns FLOAT64.

      • unpackArrayHeader

         int unpackArrayHeader()

        Reads header of an array.

        This method returns number of elements to be read. After this method call, you call unpacker methods foreach element. You don't have to call anything at the end of iteration.

      • unpackMapHeader

         int unpackMapHeader()

        Reads header of a map.

        This method returns number of pairs to be read. After this method call, for each pair, you call unpackermethods for key first, and then value. You will call unpacker methods twice as many time as the returnedcount. You don't have to call anything at the end of iteration.

      • unpackBinaryHeader

         int unpackBinaryHeader()

        Reads header of a binary.

        This method returns number of bytes to be read. After this method call, you call a readPayload method such as readPayload with the returned count.

        You can divide readPayload method into multiple calls. In this case, you must repeat readPayload methodsuntil total amount of bytes becomes equal to the returned count.

      • readPayload

         void readPayload(ByteBuffer dst)

        Reads payload bytes of binary, extension, or raw string types.

        This consumes bytes, copies them to the specified buffer, and moves forward position of the byte bufferuntil ByteBuffer.remaining() returns 0.

        Parameters:
        dst - the byte buffer into which the data is read

      • readPayload

         void readPayload(MessageBuffer dst, int off, int len)

        Reads payload bytes of binary, extension, or raw string types.

        This consumes bytes, copies them to the specified bufferThis is usually faster than readPayload(ByteBuffer) by using unsafe.copyMemory

        Parameters:
        dst - the Message buffer into which the data is read
        off - the offset in the Message buffer
        len - the number of bytes to read

      • readPayload

         void readPayload(Array<byte> dst)

        Reads payload bytes of binary, extension, or raw string types.

        This consumes specified amount of bytes into the specified byte array.

        This method is equivalent to readPayload(dst, 0, dst.length).

        Parameters:
        dst - the byte array into which the data is read

      • readPayload

         Array<byte> readPayload(int length)

        Reads payload bytes of binary, extension, or raw string types.

        This method allocates a new byte array and consumes specified amount of bytes into the byte array.

        This method is equivalent to readPayload(new byte[length]).

        Parameters:
        length - number of bytes to be read

      • readPayload

         void readPayload(Array<byte> dst, int off, int len)

        Reads payload bytes of binary, extension, or raw string types.

        This consumes specified amount of bytes into the specified byte array.

        Parameters:
        dst - the byte array into which the data is read
        off - the offset in the dst array
        len - the number of bytes to read

      • readPayloadAsReference

         MessageBuffer readPayloadAsReference(int length)

        Reads payload bytes of binary, extension, or raw string types as a reference to internal buffer.

        This consumes specified amount of bytes and returns its reference or copy. This method tries toreturn reference as much as possible because it is faster. However, it may copy data to a newlyallocated buffer if reference is not applicable.

        Parameters:
        length - number of bytes to be read

      • close

         void close()

        Closes underlying input.