java.lang.Object
- org.msgpack.core.MessageUnpacker

All Implemented Interfaces:: java.io.Closeable, java.lang.AutoCloseable

public class MessageUnpacker
extends java.lang.Object
implements java.io.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 MessageFormat.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;
             }
         }
     }

 
 Following methods correspond to the MessagePack types:

 

   MessagePack type Unpacker method Java type
   Nil unpackNil() null
   Boolean unpackBoolean() boolean
   Integer unpackByte() byte
   Integer unpackShort() short
   Integer unpackInt() int
   Integer unpackLong() long
   Integer unpackBigInteger() BigInteger
   Float unpackFloat() float
   Float unpackDouble() double
   Binary unpackBinaryHeader() byte array
   String unpackRawStringHeader() String
   String unpackString() String
   Array unpackArrayHeader() Array
   Map unpackMapHeader() Map
   Extension unpackExtensionTypeHeader() ExtensionTypeHeader
 

 
 To read a byte array, first call unpackBinaryHeader() method to get length of the byte array. Then,
 call readPayload(int) or readPayloadAsReference(int) method to read the the contents.

 

 To read an Array type, first call unpackArrayHeader() method to get number of elements. Then,
 call unpacker methods for each element.

 

 To read a Map, first call unpackMapHeader() method to get number of pairs of the map. Then,
 for each pair, call unpacker methods for key first, and then value. will call unpacker methods twice
 as many time as the returned count.











Constructor Summary

Constructors 

Modifier
Constructor
Description


protected 
MessageUnpacker(MessageBufferInput in,
               MessagePack.UnpackerConfig config)

Create an MessageUnpacker that reads data from the given MessageBufferInput.












Method Summary

All Methods Instance Methods Concrete Methods 

Modifier and Type
Method
Description


void
close()

Closes underlying input.



MessageFormat
getNextFormat()

Returns format of the next value.



long
getTotalReadBytes()

Returns total number of read bytes.



boolean
hasNext()

Returns true true if this unpacker has more elements.



void
readPayload(byte[] dst)

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



void
readPayload(byte[] dst,
           int off,
           int len)

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



byte[]
readPayload(int length)

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



void
readPayload(java.nio.ByteBuffer dst)

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



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

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



MessageBuffer
readPayloadAsReference(int length)

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



MessageBufferInput
reset(MessageBufferInput in)

Replaces underlying input.



void
skipValue()

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



void
skipValue(int count)

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



boolean
tryUnpackNil()

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



int
unpackArrayHeader()

Reads header of an array.



java.math.BigInteger
unpackBigInteger()

Reads a BigInteger.



int
unpackBinaryHeader()

Reads header of a binary.



boolean
unpackBoolean()

Reads true or false.



byte
unpackByte()

Reads a byte.



double
unpackDouble()

Reads a double.



ExtensionTypeHeader
unpackExtensionTypeHeader()
 


float
unpackFloat()

Reads a float.



int
unpackInt()

Reads a int.



long
unpackLong()

Reads a long.



int
unpackMapHeader()

Reads header of a map.



void
unpackNil()

Reads a Nil byte.



int
unpackRawStringHeader()
 


short
unpackShort()

Reads a short.



java.lang.String
unpackString()
 


ImmutableValue
unpackValue()
 


Variable
unpackValue(Variable var)
 






Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
















Constructor Detail





MessageUnpacker
protected MessageUnpacker(MessageBufferInput in,
                          MessagePack.UnpackerConfig config)
Create an MessageUnpacker that reads data from the given MessageBufferInput.
 This method is available for subclasses to override. Use MessagePack.UnpackerConfig.newUnpacker method to instantiate this implementation.

Parameters:
in - 












Method Detail





reset
public MessageBufferInput reset(MessageBufferInput in)
                         throws java.io.IOException
Replaces underlying input.
 
 This method clears internal buffer, swaps the underlying input with the new given input, then returns
 the old input.

 

 This method doesn't close the old input.

Parameters:
in - new input
Returns:
the old input
Throws:
java.io.IOException - never happens unless a subclass overrides this method
java.lang.NullPointerException - the given input is null








getTotalReadBytes
public long getTotalReadBytes()
Returns total number of read bytes.
 
 This method returns total of amount of data consumed from the underlying input minus size of data
 remained still unused in the current internal buffer.

 

 Calling reset(MessageBufferInput) resets this number to 0.







hasNext
public boolean hasNext()
                throws java.io.IOException
Returns true true if this unpacker has more elements.
 When this returns true, subsequent call to getNextFormat() returns an
 MessageFormat instance. If false, next getNextFormat() call will throw an MessageInsufficientBufferException.

Returns:
true if this unpacker has more elements to read
Throws:
java.io.IOException








getNextFormat
public MessageFormat getNextFormat()
                            throws java.io.IOException
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.

Returns:
the next MessageFormat
Throws:
java.io.IOException - when underlying input throws IOException
MessageInsufficientBufferException - when the end of file reached, i.e. hasNext() == false.








skipValue
public void skipValue()
               throws java.io.IOException
Skip the next value, then move the cursor at the end of the value

Throws:
java.io.IOException








skipValue
public void skipValue(int count)
               throws java.io.IOException
Skip next values, then move the cursor at the end of the value

Parameters:
count - number of values to skip
Throws:
java.io.IOException








unpackValue
public ImmutableValue unpackValue()
                           throws java.io.IOException

Throws:
java.io.IOException








unpackValue
public Variable unpackValue(Variable var)
                     throws java.io.IOException

Throws:
java.io.IOException








unpackNil
public void unpackNil()
               throws java.io.IOException
Reads a Nil byte.

Throws:
MessageTypeException - when value is not MessagePack Nil type
java.io.IOException - when underlying input throws IOException








tryUnpackNil
public boolean tryUnpackNil()
                     throws java.io.IOException
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 value
 while this tryUnpackNil method returns false without changing position.

Returns:
true if a nil value is read
Throws:
MessageInsufficientBufferException - when the end of file reached
java.io.IOException - when underlying input throws IOException








unpackBoolean
public boolean unpackBoolean()
                      throws java.io.IOException
Reads true or false.

Returns:
the read value
Throws:
MessageTypeException - when value is not MessagePack Boolean type
java.io.IOException - when underlying input throws IOException








unpackByte
public byte unpackByte()
                throws java.io.IOException
Reads a byte.

 This method throws MessageIntegerOverflowException if the value doesn't fit in the range of byte. This may happen when getNextFormat() returns UINT8, INT16, or larger integer formats.

Returns:
the read value
Throws:
MessageIntegerOverflowException - when value doesn't fit in the range of byte
MessageTypeException - when value is not MessagePack Integer type
java.io.IOException - when underlying input throws IOException








unpackShort
public short unpackShort()
                  throws java.io.IOException
Reads a short.

 This method throws MessageIntegerOverflowException if the value doesn't fit in the range of short. This may happen when getNextFormat() returns UINT16, INT32, or larger integer formats.

Returns:
the read value
Throws:
MessageIntegerOverflowException - when value doesn't fit in the range of short
MessageTypeException - when value is not MessagePack Integer type
java.io.IOException - when underlying input throws IOException








unpackInt
public int unpackInt()
              throws java.io.IOException
Reads a int.

 This method throws MessageIntegerOverflowException if the value doesn't fit in the range of int. This may happen when getNextFormat() returns UINT32, INT64, or larger integer formats.

Returns:
the read value
Throws:
MessageIntegerOverflowException - when value doesn't fit in the range of int
MessageTypeException - when value is not MessagePack Integer type
java.io.IOException - when underlying input throws IOException








unpackLong
public long unpackLong()
                throws java.io.IOException
Reads a long.

 This method throws MessageIntegerOverflowException if the value doesn't fit in the range of long. This may happen when getNextFormat() returns UINT64.

Returns:
the read value
Throws:
MessageIntegerOverflowException - when value doesn't fit in the range of long
MessageTypeException - when value is not MessagePack Integer type
java.io.IOException - when underlying input throws IOException








unpackBigInteger
public java.math.BigInteger unpackBigInteger()
                                      throws java.io.IOException
Reads a BigInteger.

Returns:
the read value
Throws:
MessageTypeException - when value is not MessagePack Integer type
java.io.IOException - when underlying input throws IOException








unpackFloat
public float unpackFloat()
                  throws java.io.IOException
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.

Returns:
the read value
Throws:
MessageTypeException - when value is not MessagePack Float type
java.io.IOException - when underlying input throws IOException








unpackDouble
public double unpackDouble()
                    throws java.io.IOException
Reads a double.

Returns:
the read value
Throws:
MessageTypeException - when value is not MessagePack Float type
java.io.IOException - when underlying input throws IOException








unpackString
public java.lang.String unpackString()
                              throws java.io.IOException

Throws:
java.io.IOException








unpackArrayHeader
public int unpackArrayHeader()
                      throws java.io.IOException
Reads header of an array.

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

Returns:
the size of the array to be read
Throws:
MessageTypeException - when value is not MessagePack Array type
MessageSizeException - when size of the array is larger than 2^31 - 1
java.io.IOException - when underlying input throws IOException








unpackMapHeader
public int unpackMapHeader()
                    throws java.io.IOException
Reads header of a map.

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

Returns:
the size of the map to be read
Throws:
MessageTypeException - when value is not MessagePack Map type
MessageSizeException - when size of the map is larger than 2^31 - 1
java.io.IOException - when underlying input throws IOException








unpackExtensionTypeHeader
public ExtensionTypeHeader unpackExtensionTypeHeader()
                                              throws java.io.IOException

Throws:
java.io.IOException








unpackRawStringHeader
public int unpackRawStringHeader()
                          throws java.io.IOException

Throws:
java.io.IOException








unpackBinaryHeader
public int unpackBinaryHeader()
                       throws java.io.IOException
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(int) with the returned count.

 

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

Returns:
the size of the map to be read
Throws:
MessageTypeException - when value is not MessagePack Map type
MessageSizeException - when size of the map is larger than 2^31 - 1
java.io.IOException - when underlying input throws IOException








readPayload
public void readPayload(java.nio.ByteBuffer dst)
                 throws java.io.IOException
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 buffer
 until ByteBuffer.remaining() returns 0.

Parameters:
dst - the byte buffer into which the data is read
Throws:
java.io.IOException - when underlying input throws IOException








readPayload
public void readPayload(MessageBuffer dst,
                        int off,
                        int len)
                 throws java.io.IOException
Reads payload bytes of binary, extension, or raw string types.

 
 This consumes bytes, copies them to the specified buffer
 This 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
Throws:
java.io.IOException - when underlying input throws IOException








readPayload
public void readPayload(byte[] dst)
                 throws java.io.IOException
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
Throws:
java.io.IOException - when underlying input throws IOException








readPayload
public byte[] readPayload(int length)
                   throws java.io.IOException
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
Returns:
the new byte array
Throws:
java.io.IOException - when underlying input throws IOException








readPayload
public void readPayload(byte[] dst,
                        int off,
                        int len)
                 throws java.io.IOException
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
Throws:
java.io.IOException - when underlying input throws IOException








readPayloadAsReference
public MessageBuffer readPayloadAsReference(int length)
                                     throws java.io.IOException
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 to
 return reference as much as possible because it is faster. However, it may copy data to a newly
 allocated buffer if reference is not applicable.

Parameters:
length - number of bytes to be read
Throws:
java.io.IOException - when underlying input throws IOException








close
public void close()
           throws java.io.IOException
Closes underlying input.

Specified by:
close in interface java.lang.AutoCloseable
Specified by:
close in interface java.io.Closeable
Throws:
java.io.IOException

Modifier and Type	Method	Description
`void`	`close()`	Closes underlying input.
`MessageFormat`	`getNextFormat()`	Returns format of the next value.
`long`	`getTotalReadBytes()`	Returns total number of read bytes.
`boolean`	`hasNext()`	Returns true true if this unpacker has more elements.
`void`	`readPayload(byte[] dst)`	Reads payload bytes of binary, extension, or raw string types.
`void`	`readPayload(byte[] dst, int off, int len)`	Reads payload bytes of binary, extension, or raw string types.
`byte[]`	`readPayload(int length)`	Reads payload bytes of binary, extension, or raw string types.
`void`	`readPayload(java.nio.ByteBuffer dst)`	Reads payload bytes of binary, extension, or raw string types.
`void`	`readPayload(MessageBuffer dst, int off, int len)`	Reads payload bytes of binary, extension, or raw string types.
`MessageBuffer`	`readPayloadAsReference(int length)`	Reads payload bytes of binary, extension, or raw string types as a reference to internal buffer.
`MessageBufferInput`	`reset(MessageBufferInput in)`	Replaces underlying input.
`void`	`skipValue()`	Skip the next value, then move the cursor at the end of the value
`void`	`skipValue(int count)`	Skip next values, then move the cursor at the end of the value
`boolean`	`tryUnpackNil()`	Peeks a Nil byte and reads it if next byte is a nil value.
`int`	`unpackArrayHeader()`	Reads header of an array.
`java.math.BigInteger`	`unpackBigInteger()`	Reads a BigInteger.
`int`	`unpackBinaryHeader()`	Reads header of a binary.
`boolean`	`unpackBoolean()`	Reads true or false.
`byte`	`unpackByte()`	Reads a byte.
`double`	`unpackDouble()`	Reads a double.
`ExtensionTypeHeader`	`unpackExtensionTypeHeader()`
`float`	`unpackFloat()`	Reads a float.
`int`	`unpackInt()`	Reads a int.
`long`	`unpackLong()`	Reads a long.
`int`	`unpackMapHeader()`	Reads header of a map.
`void`	`unpackNil()`	Reads a Nil byte.
`int`	`unpackRawStringHeader()`
`short`	`unpackShort()`	Reads a short.
`java.lang.String`	`unpackString()`
`ImmutableValue`	`unpackValue()`
`Variable`	`unpackValue(Variable var)`

MessagePack type	Unpacker method	Java type
Nil	`unpackNil()`	null
Boolean	`unpackBoolean()`	boolean
Integer	`unpackByte()`	byte
Integer	`unpackShort()`	short
Integer	`unpackInt()`	int
Integer	`unpackLong()`	long
Integer	`unpackBigInteger()`	BigInteger
Float	`unpackFloat()`	float
Float	`unpackDouble()`	double
Binary	`unpackBinaryHeader()`	byte array
String	`unpackRawStringHeader()`	String
String	`unpackString()`	String
Array	`unpackArrayHeader()`	Array
Map	`unpackMapHeader()`	Map
Extension	`unpackExtensionTypeHeader()`	`ExtensionTypeHeader`

Class MessageUnpacker

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MessageUnpacker

Method Detail

reset

getTotalReadBytes

hasNext

getNextFormat

skipValue

skipValue

unpackValue

unpackValue

unpackNil

tryUnpackNil

unpackBoolean

unpackByte

unpackShort

unpackInt

unpackLong

unpackBigInteger

unpackFloat

unpackDouble

unpackString

unpackArrayHeader

unpackMapHeader

unpackExtensionTypeHeader

unpackRawStringHeader

unpackBinaryHeader

readPayload

readPayload

readPayload

readPayload

readPayload

readPayloadAsReference

close