io.nadron.communication

Interface MessageBuffer<T>

All Known Implementing Classes:

NettyMessageBuffer

public interface MessageBuffer<T>

A message buffer can be used for communicating complex messages between server and client or between sessions. It is a read-destroy buffer meaning, that once a value is read off it, it cannot be read again as the internal pointers would have moved to the post-read position. This buffer could hold almost any sort of data in binary form int, String, other native types, byte[] of serialized objects and so on. It contains helper methods for writing and reading back the data. If a Netty implementation is used, then it would be a wrapper over the ByteBuf. For Java api, it would be probably be wrapper over a nio ByteBuffer.

Author:

Abraham Menacherry

Method Summary

Methods

Modifier and Type	Method and Description
byte[]	array() Returns the backing byte array of this buffer.
void	clear() Clears the contents of this buffer.
T	getNativeBuffer() Returns the actual buffer implementation that is wrapped in this MessageBuffer instance.
boolean	isReadable()
int	readableBytes() Gets the number of readable bytes left in the buffer.
int	readByte() Read a single signed byte from the current readerIndex position of the buffer.
void	readBytes(byte[] dst) Transfers this buffer's data to the specified destination starting at the current readerIndex and increases the readerIndex by the number of the transferred bytes (= dst.length).
void	readBytes(byte[] dst, int dstIndex, int length) Transfers this buffer's data to the specified destination starting at the current readerIndex and increases the readerIndex by the number of the transferred bytes (= length).
byte[]	readBytes(int length)
char	readChar() Gets a 2-byte UTF-16 character at the current readerIndex and increases the readerIndex by 2 in this buffer.
double	readDouble() Gets a 64-bit floating point number at the current readerIndex and increases the readerIndex by 8 in this buffer.
float	readFloat() Gets a 32-bit floating point number at the current readerIndex and increases the readerIndex by 4 in this buffer.
int	readInt() Gets a 32-bit integer at the current readerIndex and increases the readerIndex by 4 in this buffer.
long	readLong() Gets a 64-bit integer at the current readerIndex and increases the readerIndex by 8 in this buffer.
int	readMedium() Gets a 24-bit medium integer at the current readerIndex and increases the readerIndex by 3 in this buffer.
<V> V	readObject(Transform<T,V> converter) Reads an object from the underlying buffer and transform the bytes using the supplied transformer to any desired object.
int	readShort() Gets a 16-bit short integer at the current readerIndex and increases the readerIndex by 2 in this buffer.
String	readString()
String[]	readStrings(int numOfStrings)
int	readUnsignedByte() Gets an unsigned byte at the current readerIndex and increases the readerIndex by 1 in this buffer.
long	readUnsignedInt() Gets an unsigned 32-bit integer at the current readerIndex and increases the readerIndex by 4 in this buffer.
int	readUnsignedMedium() Gets an unsigned 24-bit medium integer at the current readerIndex and increases the readerIndex by 3 in this buffer.
int	readUnsignedShort() Gets an unsigned 16-bit short integer at the current readerIndex and increases the readerIndex by 2 in this buffer.
MessageBuffer<T>	writeByte(byte b)
MessageBuffer<T>	writeBytes(byte[] src) Transfers the specified source array's data to this buffer starting at the current writerIndex and increases the writerIndex by the number of the transferred bytes (= src.length).
MessageBuffer<T>	writeChar(int value) Sets the specified 2-byte UTF-16 character at the current writerIndex and increases the writerIndex by 2 in this buffer.
MessageBuffer<T>	writeDouble(double value) Sets the specified 64-bit floating point number at the current writerIndex and increases the writerIndex by 8 in this buffer.
MessageBuffer<T>	writeFloat(float value) Sets the specified 32-bit floating point number at the current writerIndex and increases the writerIndex by 4 in this buffer.
MessageBuffer<T>	writeInt(int value) Sets the specified 32-bit integer at the current writerIndex and increases the writerIndex by 4 in this buffer.
MessageBuffer<T>	writeLong(long value) Sets the specified 64-bit long integer at the current writerIndex and increases the writerIndex by 8 in this buffer.
MessageBuffer<T>	writeMedium(int value) Sets the specified 24-bit medium integer at the current writerIndex and increases the writerIndex by 3 in this buffer.
<V> MessageBuffer<T>	writeObject(Transform<V,T> converter, V object) Most implementations will write an object to the underlying buffer after converting the incoming object using the transformer into a byte array.
MessageBuffer<T>	writeShort(int value) Sets the specified 16-bit short integer at the current writerIndex and increases the writerIndex by 2 in this buffer.
MessageBuffer<T>	writeString(String message)
MessageBuffer<T>	writeStrings(String... message)

Method Detail

isReadable

boolean isReadable()

Returns:

Returns true if something can be read from this buffer, else false.

readableBytes

int readableBytes()

Gets the number of readable bytes left in the buffer.

Returns:

an integer containing the remaining readable bytes.

readByte

int readByte()

Read a single signed byte from the current readerIndex position of the buffer. It will increment the readerIndex after doing this operation.

Returns:

Returns the byte that is read

Throws:

IndexOutOfBoundsException - if isReadable() returns false.

readBytes

byte[] readBytes(int length)

readBytes

void readBytes(byte[] dst)

Transfers this buffer's data to the specified destination starting at the current readerIndex and increases the readerIndex by the number of the transferred bytes (= dst.length).

Throws:

IndexOutOfBoundsException - if dst.length is greater than this.readableBytes

readBytes

void readBytes(byte[] dst,
             int dstIndex,
             int length)

Transfers this buffer's data to the specified destination starting at the current readerIndex and increases the readerIndex by the number of the transferred bytes (= length).

Parameters:

dstIndex - the first index of the destination

length - the number of bytes to transfer

Throws:

IndexOutOfBoundsException - if the specified dstIndex is less than 0, if length is greater than this.readableBytes, or if dstIndex + length is greater than dst.length

readUnsignedByte

int readUnsignedByte()

Gets an unsigned byte at the current readerIndex and increases the readerIndex by 1 in this buffer.

Throws:

IndexOutOfBoundsException - if this.readableBytes is less than 1

readShort

int readShort()

Gets a 16-bit short integer at the current readerIndex and increases the readerIndex by 2 in this buffer.

Throws:

IndexOutOfBoundsException - if this.readableBytes is less than 2

readUnsignedShort

int readUnsignedShort()

Gets an unsigned 16-bit short integer at the current readerIndex and increases the readerIndex by 2 in this buffer.

Throws:

IndexOutOfBoundsException - if this.readableBytes is less than 2

readMedium

int readMedium()

Gets a 24-bit medium integer at the current readerIndex and increases the readerIndex by 3 in this buffer.

Throws:

IndexOutOfBoundsException - if this.readableBytes is less than 3

readUnsignedMedium

int readUnsignedMedium()

Gets an unsigned 24-bit medium integer at the current readerIndex and increases the readerIndex by 3 in this buffer.

Throws:

IndexOutOfBoundsException - if this.readableBytes is less than 3

readInt

int readInt()

Gets a 32-bit integer at the current readerIndex and increases the readerIndex by 4 in this buffer.

Throws:

IndexOutOfBoundsException - if this.readableBytes is less than 4

readUnsignedInt

long readUnsignedInt()

Gets an unsigned 32-bit integer at the current readerIndex and increases the readerIndex by 4 in this buffer.

Throws:

IndexOutOfBoundsException - if this.readableBytes is less than 4

readLong

long readLong()

Gets a 64-bit integer at the current readerIndex and increases the readerIndex by 8 in this buffer.

Throws:

IndexOutOfBoundsException - if this.readableBytes is less than 8

readChar

char readChar()

Gets a 2-byte UTF-16 character at the current readerIndex and increases the readerIndex by 2 in this buffer.

Throws:

IndexOutOfBoundsException - if this.readableBytes is less than 2

readFloat

float readFloat()

Gets a 32-bit floating point number at the current readerIndex and increases the readerIndex by 4 in this buffer.

Throws:

IndexOutOfBoundsException - if this.readableBytes is less than 4

readDouble

double readDouble()

Gets a 64-bit floating point number at the current readerIndex and increases the readerIndex by 8 in this buffer.

Throws:

IndexOutOfBoundsException - if this.readableBytes is less than 8

readString

String readString()

readStrings

String[] readStrings(int numOfStrings)

readObject

<V> V readObject(Transform<T,V> converter)

Reads an object from the underlying buffer and transform the bytes using the supplied transformer to any desired object. This method provide the flexibility to decode the bytes to any type of object.

Parameters:

converter - The converter which will transform the bytes to relevant object.

Returns:

The object of type V, or null if the underlying buffer is null or empty.

writeByte

MessageBuffer<T> writeByte(byte b)

writeBytes

MessageBuffer<T> writeBytes(byte[] src)

Transfers the specified source array's data to this buffer starting at the current writerIndex and increases the writerIndex by the number of the transferred bytes (= src.length).

Throws:

IndexOutOfBoundsException - if src.length is greater than this.writableBytes

writeShort

MessageBuffer<T> writeShort(int value)

Sets the specified 16-bit short integer at the current writerIndex and increases the writerIndex by 2 in this buffer. The 16 high-order bits of the specified value are ignored.

Throws:

IndexOutOfBoundsException - if this.writableBytes is less than 2

writeMedium

MessageBuffer<T> writeMedium(int value)

Sets the specified 24-bit medium integer at the current writerIndex and increases the writerIndex by 3 in this buffer.

Throws:

IndexOutOfBoundsException - if this.writableBytes is less than 3

writeInt

MessageBuffer<T> writeInt(int value)

Sets the specified 32-bit integer at the current writerIndex and increases the writerIndex by 4 in this buffer.

Throws:

IndexOutOfBoundsException - if this.writableBytes is less than 4

writeLong

MessageBuffer<T> writeLong(long value)

Sets the specified 64-bit long integer at the current writerIndex and increases the writerIndex by 8 in this buffer.

Throws:

IndexOutOfBoundsException - if this.writableBytes is less than 8

writeChar

MessageBuffer<T> writeChar(int value)

Sets the specified 2-byte UTF-16 character at the current writerIndex and increases the writerIndex by 2 in this buffer. The 16 high-order bits of the specified value are ignored.

Throws:

IndexOutOfBoundsException - if this.writableBytes is less than 2

writeFloat

MessageBuffer<T> writeFloat(float value)

Sets the specified 32-bit floating point number at the current writerIndex and increases the writerIndex by 4 in this buffer.

Throws:

IndexOutOfBoundsException - if this.writableBytes is less than 4

writeDouble

MessageBuffer<T> writeDouble(double value)

Sets the specified 64-bit floating point number at the current writerIndex and increases the writerIndex by 8 in this buffer.

Throws:

IndexOutOfBoundsException - if this.writableBytes is less than 8

writeString

MessageBuffer<T> writeString(String message)

writeStrings

MessageBuffer<T> writeStrings(String... message)

writeObject

<V> MessageBuffer<T> writeObject(Transform<V,T> converter,
                               V object)

Most implementations will write an object to the underlying buffer after converting the incoming object using the transformer into a byte array. This method provides the flexibility to encode any type of object, to a byte array or buffer(mostly).

Type Parameters:

V - The object to be converted, mostly to a byte array or relevant buffer implementation.

Parameters:

converter - For most implementations, the converter which will transform the object to byte array.

Returns:

Instance of this class itself.

getNativeBuffer

T getNativeBuffer()

Returns the actual buffer implementation that is wrapped in this MessageBuffer instance.

Returns:

This method will return the underlying buffer. For Netty that would be a ByteBuf, for a core java implementation it could be ByteBuffer

array

byte[] array()

Returns the backing byte array of this buffer.

Throws:

UnsupportedOperationException - if there no accessible backing byte array

clear

void clear()

Clears the contents of this buffer.