MessagePacker

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

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

Direct Known Subclasses:: MessageBufferPacker

public class MessagePacker
extends java.lang.Object
implements java.io.Closeable, java.io.Flushable

MessagePack serializer that converts objects into binary. You can use factory methods of MessagePack class or MessagePack.PackerConfig class to create an instance.

This class provides following primitive methods to write MessagePack values. These primitive methods write short bytes (1 to 7 bytes) to the internal buffer at once. There are also some utility methods for convenience.

Primitive methods:

Java type	Packer method	MessagePack type
null	`packNil()`	Nil
boolean	`packBoolean(boolean)`	Boolean
byte	`packByte(byte)`	Integer
short	`packShort(short)`	Integer
int	`packInt(int)`	Integer
long	`packLong(long)`	Integer
BigInteger	`packBigInteger(BigInteger)`	Integer
float	`packFloat(float)`	Float
double	`packDouble(double)`	Float
byte[]	`packBinaryHeader(int)`	Binary
String	`packRawStringHeader(int)`	String
List	`packArrayHeader(int)`	Array
Map	`packMapHeader(int)`	Map
custom user type	`packExtensionTypeHeader(byte, int)`	Extension

Utility methods:

Java type	Packer method	MessagePack type
String	`packString(String)`	String
`Value`	`packValue(Value)`

To write a byte array, first you call packBinaryHeader(int) method with length of the byte array. Then, you call writePayload(byte[], int, int) or addPayload(byte[], int, int) method to write the contents.

To write a List, Collection or array, first you call packArrayHeader(int) method with the number of elements. Then, you call packer methods for each element. iteration.

To write a Map, first you call packMapHeader(int) method with size of the map. Then, for each pair, you call packer methods for key first, and then value. You will call packer methods twice as many time as the size of the map.

Note that packXxxHeader methods don't validate number of elements. You must call packer methods for correct number of times to produce valid MessagePack data.

When IOException is thrown, primitive methods guarantee that all data is written to the internal buffer or no data is written. This is convenient behavior when you use a non-blocking output channel that may not be writable immediately.

Field Summary

Fields
Modifier and Type Field and Description

protected MessageBufferOutput out
Current internal buffer.

Fields
Modifier and Type	Field and Description
`protected MessageBufferOutput`	`out` Current internal buffer.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`MessagePacker(MessageBufferOutput out, MessagePack.PackerConfig config)` Create an MessagePacker that outputs the packed data to the given `MessageBufferOutput`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`MessagePacker`	`addPayload(byte[] src)` Writes a byte array to the output.
`MessagePacker`	`addPayload(byte[] src, int off, int len)` Writes a byte array to the output.
`void`	`close()` Closes underlying output.
`void`	`flush()` Flushes internal buffer to the underlying output.
`long`	`getTotalWrittenBytes()` Returns total number of written bytes.
`MessagePacker`	`packArrayHeader(int arraySize)` Writes header of an Array value.
`MessagePacker`	`packBigInteger(java.math.BigInteger bi)` Writes an Integer value.
`MessagePacker`	`packBinaryHeader(int len)` Writes header of a Binary value.
`MessagePacker`	`packBoolean(boolean b)` Writes a Boolean value.
`MessagePacker`	`packByte(byte b)` Writes an Integer value.
`MessagePacker`	`packDouble(double v)` Writes a Float value.
`MessagePacker`	`packExtensionTypeHeader(byte extType, int payloadLen)` Writes header of an Extension value.
`MessagePacker`	`packFloat(float v)` Writes a Float value.
`MessagePacker`	`packInt(int r)` Writes an Integer value.
`MessagePacker`	`packLong(long v)` Writes an Integer value.
`MessagePacker`	`packMapHeader(int mapSize)` Writes header of a Map value.
`MessagePacker`	`packNil()` Writes a Nil value.
`MessagePacker`	`packRawStringHeader(int len)` Writes header of a String value.
`MessagePacker`	`packShort(short v)` Writes an Integer value.
`MessagePacker`	`packString(java.lang.String s)` Writes a String vlaue in UTF-8 encoding.
`MessagePacker`	`packValue(Value v)` Writes a dynamically typed value.
`MessageBufferOutput`	`reset(MessageBufferOutput out)` Replaces underlying output.
`MessagePacker`	`writePayload(byte[] src)` Writes a byte array to the output.
`MessagePacker`	`writePayload(byte[] src, int off, int len)` Writes a byte array to the output.

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

- Field Detail
  - out
```
protected MessageBufferOutput out
```
    Current internal buffer.
- Constructor Detail
  - MessagePacker
```
protected MessagePacker(MessageBufferOutput out,
                        MessagePack.PackerConfig config)
```
    Create an MessagePacker that outputs the packed data to the given MessageBufferOutput. This method is available for subclasses to override. Use MessagePack.PackerConfig.newPacker method to instanciate this implementation.
    
    Parameters:
    
    out - MessageBufferOutput. Use OutputStreamBufferOutput, ChannelBufferOutput or your own implementation of MessageBufferOutput interface.
- Method Detail
  - reset
```
public MessageBufferOutput reset(MessageBufferOutput out)
                          throws java.io.IOException
```
    Replaces underlying output.
    This method flushes current internal buffer to the output, swaps it with the new given output, then returns the old output.
    This method doesn't close the old output.
    
    Parameters:
    
    out - new output
    
    Returns:
    
    the old output
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
    
    java.lang.NullPointerException - the given output is null
  - getTotalWrittenBytes
```
public long getTotalWrittenBytes()
```
    Returns total number of written bytes.
    This method returns total of amount of data flushed to the underlying output plus size of current internal buffer.
    Calling reset(MessageBufferOutput) resets this number to 0.
  - flush
```
public void flush()
           throws java.io.IOException
```
    Flushes internal buffer to the underlying output.
    This method also calls flush method of the underlying output after writing internal buffer.
    
    Specified by:
    
    flush in interface java.io.Flushable
    
    Throws:
    
    java.io.IOException
  - close
```
public void close()
           throws java.io.IOException
```
    Closes underlying output.
    This method flushes internal buffer before closing.
    
    Specified by:
    
    close in interface java.io.Closeable
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
    
    Throws:
    
    java.io.IOException
  - packNil
```
public MessagePacker packNil()
                      throws java.io.IOException
```
    Writes a Nil value. This method writes a nil byte.
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packBoolean
```
public MessagePacker packBoolean(boolean b)
                          throws java.io.IOException
```
    Writes a Boolean value. This method writes a true byte or a false byte.
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packByte
```
public MessagePacker packByte(byte b)
                       throws java.io.IOException
```
    Writes an Integer value.
    This method writes an integer using the smallest format from the int format family.
    
    Parameters:
    
    b - the integer to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packShort
```
public MessagePacker packShort(short v)
                        throws java.io.IOException
```
    Writes an Integer value.
    This method writes an integer using the smallest format from the int format family.
    
    Parameters:
    
    v - the integer to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packInt
```
public MessagePacker packInt(int r)
                      throws java.io.IOException
```
    Writes an Integer value.
    This method writes an integer using the smallest format from the int format family.
    
    Parameters:
    
    r - the integer to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packLong
```
public MessagePacker packLong(long v)
                       throws java.io.IOException
```
    Writes an Integer value.
    This method writes an integer using the smallest format from the int format family.
    
    Parameters:
    
    v - the integer to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packBigInteger
```
public MessagePacker packBigInteger(java.math.BigInteger bi)
                             throws java.io.IOException
```
    Writes an Integer value.
    This method writes an integer using the smallest format from the int format family.
    
    Parameters:
    
    bi - the integer to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packFloat
```
public MessagePacker packFloat(float v)
                        throws java.io.IOException
```
    Writes a Float value.
    This method writes a float value using float format family.
    
    Parameters:
    
    v - the value to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packDouble
```
public MessagePacker packDouble(double v)
                         throws java.io.IOException
```
    Writes a Float value.
    This method writes a float value using float format family.
    
    Parameters:
    
    v - the value to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packString
```
public MessagePacker packString(java.lang.String s)
                         throws java.io.IOException
```
    Writes a String vlaue in UTF-8 encoding.
    This method writes a UTF-8 string using the smallest format from the str format family by default. If MessagePack.PackerConfig.withStr8FormatSupport(boolean) is set to false, smallest format from the str format family excepting str8 format.
    
    Parameters:
    
    s - the string to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packArrayHeader
```
public MessagePacker packArrayHeader(int arraySize)
                              throws java.io.IOException
```
    Writes header of an Array value.
    You will call other packer methods for each element after this method call.
    You don't have to call anything at the end of iteration.
    
    Parameters:
    
    arraySize - number of elements to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packMapHeader
```
public MessagePacker packMapHeader(int mapSize)
                            throws java.io.IOException
```
    Writes header of a Map value.
    After this method call, for each key-value pair, you will call packer methods for key first, and then value. You will call packer methods twice as many time as the size of the map.
    You don't have to call anything at the end of iteration.
    
    Parameters:
    
    mapSize - number of pairs to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packValue
```
public MessagePacker packValue(Value v)
                        throws java.io.IOException
```
    Writes a dynamically typed value.
    
    Parameters:
    
    v - the value to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packExtensionTypeHeader
```
public MessagePacker packExtensionTypeHeader(byte extType,
                                             int payloadLen)
                                      throws java.io.IOException
```
    Writes header of an Extension value.
    You MUST call writePayload(byte[]) or addPayload(byte[]) method to write body binary.
    
    Parameters:
    
    extType - the extension type tag to be written
    
    payloadLen - number of bytes of a payload binary to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packBinaryHeader
```
public MessagePacker packBinaryHeader(int len)
                               throws java.io.IOException
```
    Writes header of a Binary value.
    You MUST call writePayload(byte[]) or addPayload(byte[]) method to write body binary.
    
    Parameters:
    
    len - number of bytes of a binary to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - packRawStringHeader
```
public MessagePacker packRawStringHeader(int len)
                                  throws java.io.IOException
```
    Writes header of a String value.
    Length must be number of bytes of a string in UTF-8 encoding.
    You MUST call writePayload(byte[]) or addPayload(byte[]) method to write body of the UTF-8 encoded string.
    
    Parameters:
    
    len - number of bytes of a UTF-8 string to be written
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - writePayload
```
public MessagePacker writePayload(byte[] src)
                           throws java.io.IOException
```
    Writes a byte array to the output.
    This method is used with packRawStringHeader(int) or packBinaryHeader(int) methods.
    
    Parameters:
    
    src - the data to add
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - writePayload
```
public MessagePacker writePayload(byte[] src,
                                  int off,
                                  int len)
                           throws java.io.IOException
```
    Writes a byte array to the output.
    This method is used with packRawStringHeader(int) or packBinaryHeader(int) methods.
    
    Parameters:
    
    src - the data to add
    
    off - the start offset in the data
    
    len - the number of bytes to add
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - addPayload
```
public MessagePacker addPayload(byte[] src)
                         throws java.io.IOException
```
    Writes a byte array to the output.
    Unlike writePayload(byte[]) method, this method doesn't copy the byte array even when given byte array is shorter than MessagePack.PackerConfig.withBufferFlushThreshold(int). This is faster than writePayload(byte[]) method but caller must not modify the byte array after calling this method.
    
    Parameters:
    
    src - the data to add
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException
  - addPayload
```
public MessagePacker addPayload(byte[] src,
                                int off,
                                int len)
                         throws java.io.IOException
```
    Writes a byte array to the output.
    Unlike writePayload(byte[], int, int) method, this method doesn't copy the byte array even when given byte array is shorter than MessagePack.PackerConfig.withBufferFlushThreshold(int). This is faster than writePayload(byte[], int, int) method but caller must not modify the byte array after calling this method.
    
    Parameters:
    
    src - the data to add
    
    off - the start offset in the data
    
    len - the number of bytes to add
    
    Returns:
    
    this
    
    Throws:
    
    java.io.IOException - when underlying output throws IOException

Class MessagePacker

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

out

Constructor Detail

MessagePacker

Method Detail

reset

getTotalWrittenBytes

flush

close

packNil

packBoolean

packByte

packShort

packInt

packLong

packBigInteger

packFloat

packDouble

packString

packArrayHeader

packMapHeader

packValue

packExtensionTypeHeader

packBinaryHeader

packRawStringHeader

writePayload

writePayload

addPayload

addPayload