org.msgpack.core.buffer

Class MessageBuffer

java.lang.Object

org.msgpack.core.buffer.MessageBuffer

Direct Known Subclasses:

MessageBufferBE, MessageBufferU

public class MessageBuffer
extends java.lang.Object

MessageBuffer class is an abstraction of memory with fast methods to serialize and deserialize primitive values to/from the memory. All MessageBuffer implementations ensure short/int/float/long/double values are written in big-endian order.

Applications can allocate a new buffer using allocate(int) method, or wrap an byte array or ByteBuffer using wrap(byte[], int, int) methods. wrap(ByteBuffer) method supports both direct buffers and array-backed buffers.

MessageBuffer class itself is optimized for little-endian CPU archtectures so that JVM (HotSpot) can take advantage of the fastest JIT format which skips TypeProfile checking. To ensure this performance, applications must not import unnecessary classes such as MessagePackBE. On big-endian CPU archtectures, it automatically uses a subclass that includes TypeProfile overhead but still faster than stndard ByteBuffer class. On JVMs older than Java 7 and JVMs without Unsafe API (such as Android), implementation falls back to an universal implementation that uses ByteBuffer internally.

Field Summary

Fields

Modifier and Type	Field and Description
protected long	address Head address of the underlying memory.
protected java.lang.Object	base Base object for resolving the relative address of the raw byte array.
protected java.nio.ByteBuffer	reference Reference is used to hold a reference to an object that holds the underlying memory so that it cannot be released by the garbage collector.
protected int	size Size of the underlying memory

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MessageBuffer(java.lang.Object base, long address, int length)

Method Summary

Modifier and Type	Method and Description
static MessageBuffer	allocate(int size) Allocates a new MessageBuffer backed by a byte array.
byte[]	array()
int	arrayOffset()
void	copyTo(int index, MessageBuffer dst, int offset, int length) Copy this buffer contents to another MessageBuffer
boolean	getBoolean(int index)
byte	getByte(int index)
void	getBytes(int index, byte[] dst, int dstOffset, int length)
void	getBytes(int index, int len, java.nio.ByteBuffer dst)
double	getDouble(int index)
float	getFloat(int index)
int	getInt(int index) Read a big-endian int value at the specified index
long	getLong(int index)
short	getShort(int index)
boolean	hasArray()
void	putBoolean(int index, boolean v)
void	putByte(int index, byte v)
void	putByteBuffer(int index, java.nio.ByteBuffer src, int len)
void	putBytes(int index, byte[] src, int srcOffset, int length)
void	putDouble(int index, double v)
void	putFloat(int index, float v)
void	putInt(int index, int v) Write a big-endian integer value to the memory
void	putLong(int index, long l)
void	putMessageBuffer(int index, MessageBuffer src, int srcOffset, int len)
void	putShort(int index, short v)
static void	releaseBuffer(MessageBuffer buffer)
int	size() Gets the size of the buffer.
MessageBuffer	slice(int offset, int length)
java.nio.ByteBuffer	sliceAsByteBuffer() Get a ByteBuffer view of this buffer
java.nio.ByteBuffer	sliceAsByteBuffer(int index, int length) Create a ByteBuffer view of the range [index, index+length) of this memory
byte[]	toByteArray() Get a copy of this buffer
java.lang.String	toHexString(int offset, int length)
static MessageBuffer	wrap(byte[] array) Wraps a byte array into a MessageBuffer.
static MessageBuffer	wrap(byte[] array, int offset, int length) Wraps a byte array into a MessageBuffer.
static MessageBuffer	wrap(java.nio.ByteBuffer bb) Wraps a ByteBuffer into a MessageBuffer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

base

protected final java.lang.Object base

Base object for resolving the relative address of the raw byte array. If base == null, the address value is a raw memory address

address

protected final long address

Head address of the underlying memory. If base is null, the address is a direct memory address, and if not, it is the relative address within an array object (base)

size

protected final int size

Size of the underlying memory

reference

protected final java.nio.ByteBuffer reference

Reference is used to hold a reference to an object that holds the underlying memory so that it cannot be released by the garbage collector.

Constructor Detail

MessageBuffer

protected MessageBuffer(java.lang.Object base,
                        long address,
                        int length)

Method Detail

allocate

public static MessageBuffer allocate(int size)

Allocates a new MessageBuffer backed by a byte array.

Throws:

java.lang.IllegalArgumentException - If the capacity is a negative integer

wrap

public static MessageBuffer wrap(byte[] array)

Wraps a byte array into a MessageBuffer. The new MessageBuffer will be backed by the given byte array. Modifications to the new MessageBuffer will cause the byte array to be modified and vice versa. The new buffer's size will be array.length. hasArray() will return true.

Parameters:

array - the byte array that will gack this MessageBuffer

Returns:

a new MessageBuffer that wraps the given byte array

wrap

public static MessageBuffer wrap(byte[] array,
                                 int offset,
                                 int length)

Wraps a byte array into a MessageBuffer. The new MessageBuffer will be backed by the given byte array. Modifications to the new MessageBuffer will cause the byte array to be modified and vice versa. The new buffer's size will be length. hasArray() will return true.

Parameters:

array - the byte array that will gack this MessageBuffer

offset - The offset of the subarray to be used; must be non-negative and no larger than array.length

length - The length of the subarray to be used; must be non-negative and no larger than array.length - offset

Returns:

a new MessageBuffer that wraps the given byte array

wrap

public static MessageBuffer wrap(java.nio.ByteBuffer bb)

Wraps a ByteBuffer into a MessageBuffer. The new MessageBuffer will be backed by the given byte buffer. Modifications to the new MessageBuffer will cause the byte buffer to be modified and vice versa. However, change of position, limit, or mark of given byte buffer doesn't affect MessageBuffer. The new buffer's size will be bb.remaining(). hasArray() will return the same result with bb.hasArray().

Parameters:

bb - the byte buffer that will gack this MessageBuffer

Returns:

a new MessageBuffer that wraps the given byte array

Throws:

java.lang.IllegalArgumentException - given byte buffer returns false both from hasArray() and isDirect()

java.lang.UnsupportedOperationException - given byte buffer is a direct buffer and this platform doesn't support Unsafe API

releaseBuffer

public static void releaseBuffer(MessageBuffer buffer)

size

public int size()

Gets the size of the buffer. MessageBuffer doesn't have limit unlike ByteBuffer. Instead, you can use slice(int, int) to get a part of the buffer.

Returns:

number of bytes

slice

public MessageBuffer slice(int offset,
                           int length)

getByte

public byte getByte(int index)

getBoolean

public boolean getBoolean(int index)

getShort

public short getShort(int index)

getInt

public int getInt(int index)

Read a big-endian int value at the specified index

Parameters:

index -

Returns:

getFloat

public float getFloat(int index)

getLong

public long getLong(int index)

getDouble

public double getDouble(int index)

getBytes

public void getBytes(int index,
                     byte[] dst,
                     int dstOffset,
                     int length)

getBytes

public void getBytes(int index,
                     int len,
                     java.nio.ByteBuffer dst)

putByte

public void putByte(int index,
                    byte v)

putBoolean

public void putBoolean(int index,
                       boolean v)

putShort

public void putShort(int index,
                     short v)

putInt

public void putInt(int index,
                   int v)

Write a big-endian integer value to the memory

Parameters:

index -

v -

putFloat

public void putFloat(int index,
                     float v)

putLong

public void putLong(int index,
                    long l)

putDouble

public void putDouble(int index,
                      double v)

putBytes

public void putBytes(int index,
                     byte[] src,
                     int srcOffset,
                     int length)

putByteBuffer

public void putByteBuffer(int index,
                          java.nio.ByteBuffer src,
                          int len)

putMessageBuffer

public void putMessageBuffer(int index,
                             MessageBuffer src,
                             int srcOffset,
                             int len)

sliceAsByteBuffer

public java.nio.ByteBuffer sliceAsByteBuffer(int index,
                                             int length)

Create a ByteBuffer view of the range [index, index+length) of this memory

Parameters:

index -

length -

Returns:

sliceAsByteBuffer

public java.nio.ByteBuffer sliceAsByteBuffer()

Get a ByteBuffer view of this buffer

Returns:

hasArray

public boolean hasArray()

toByteArray

public byte[] toByteArray()

Get a copy of this buffer

Returns:

array

public byte[] array()

arrayOffset

public int arrayOffset()

copyTo

public void copyTo(int index,
                   MessageBuffer dst,
                   int offset,
                   int length)

Copy this buffer contents to another MessageBuffer

Parameters:

index -

dst -

offset -

length -

toHexString

public java.lang.String toHexString(int offset,
                                    int length)