com.neeve.pkt
Class PktBuffer

java.lang.Object
  com.neeve.pkt.PktBuffer

public final class PktBuffer
extends Object

Implements the buffer that backs a packet header or body.

A packet buffer serves as the backing buffer of a packet header or body. It maintains a view into an underlying PktIOBuffer. It holds an instance of a PktIOBuffer object and an offset and length that defines its window into the underlying buffer. It support 'copy on write' and 'fail on write' semantics.

A user supplied an instance of PktSerializable when creating a new packet buffer. The serializable entity is queried by the buffer for the entity's serialized length when it needs to create a new IO buffer. This is done implicitly by getBufferForRead(), by getBufferForWrite() and the putXXX/getXXX methods if an IO buffer has not already been created or supplied by the user via wrapIOBuffer(com.neeve.pkt.PktIOBuffer, int, int). Once created/set, the user requests for the contained buffer by specifying the intended use (read/write) of the buffer. The getBufferForRead() method requests for the buffer for reading and getBufferForWrite() requests for the buffer for writing.

The reason why a user needs to specify whether the underlying buffer is being obtained for read or write is to to support 'copy on write' and 'fail on write' semantics. The setCopyOnWrite() and setFailOnWrite() methods mark the packet buffer as 'copy on write' and 'fail on write' respectively. A buffer marked as 'copy on write' will cause the next call to getBufferForWrite() to 'clone' the contained buffer before returning it to the caller. A 'clonee' buffer's markers and content are independent of the cloned buffer (see UtlBuffer.clone(java.nio.ByteBuffer)). A buffer marked as 'fail on write' will cause the next call to getBufferForWrite() to fail.

Threading:

As with the contained PktIOBuffer object, a packet buffer is not thread safe i.e. only one thread can be executing the packet buffer methods at any point in time.

Nested Class Summary

static interface

PktBuffer.Initializer Used to initialize the buffer The user registers an instance of this interface with a packet buffer to initialize the contents of the backing IO buffer when first created by the packet buffer.

Method Summary

static int	calculateUTFLength(char c) Calculates the length of the character encoded as UTF-8.
static int	calculateUTFLength(CharSequence str) Calculates the length of the character sequence encoded as UTF-8.
PktBuffer	clearCopyOnWrite() Clear a buffer's 'copy on write' flag.
PktBuffer	clearFailOnWrite() Clear a buffer's 'fail on write' flag.
static PktBuffer	create(PktSerializable owner, int bufferLength, boolean isNative) Create a new packet buffer
PktBuffer	fork() Fork a packet buffer This method creates a new packet buffer, associates it with the same underlying IO buffer as this one and mark *both* buffers as copy on write (to make sure changes to one don't corrupt the other)
byte	get(int index) Get a byte value at a specified index into the buffer
ByteBuffer	getBufferForRead() Get the buffer for read.
ByteBuffer	getBufferForWrite() Get the buffer for write.
ByteOrder	getByteOrder() Get a packet buffer's byte order
char	getChar(int index) Get a char value at a specified index into the buffer
double	getDouble(int index) Get a double value at a specified index into the buffer
float	getFloat(int index) Get a float value at a specified index into the buffer
PktBuffer.Initializer	getInitializer() Get the buffer initializer
int	getInt(int index) Get a int value at a specified index into the buffer
PktIOBuffer	getIOBuffer() Get backing IO buffer
int	getLength() Get a packet buffer's length
long	getLong(int index) Get a long value at a specified index into the buffer
int	getOffset() Get a packet's buffer's offset into the underlying buffer.
short	getShort(int index) Get a short value at a specified index into the buffer
String	getString(int index, int length) Get a string value at a specified index into the buffer
PktBuffer	getTo(int index, byte[] array, int arrayOffset, int length) Copy contents from a packet buffer to a supplied byte array
PktBuffer	getTo(int index, ByteBuffer buffer, int length) Copy contents from a packet buffer to a supplied byte buffer
PktBuffer	getTo(int index, char[] array, int arrayOffset, int length) Copy contents from a packet buffer to a supplied char array
PktBuffer	getTo(int index, double[] array, int arrayOffset, int length) Copy contents from a packet buffer to a supplied double array
PktBuffer	getTo(int index, float[] array, int arrayOffset, int length) Copy contents from a packet buffer to a supplied float array
PktBuffer	getTo(int index, int[] array, int arrayOffset, int length) Copy contents from a packet buffer to a supplied int array
PktBuffer	getTo(int index, long[] array, int arrayOffset, int length) Copy contents from a packet buffer to a supplied long array
PktBuffer	getTo(int index, short[] array, int arrayOffset, int length) Copy contents from a packet buffer to a supplied short array
PktBuffer	getToNative(int index, long address, int addressOffset, int length) Copy contents from a packet buffer to native memory
int	getUnsignedByte(int index) Get a byte value at a specified index into the buffer
long	getUnsignedInt(int index) Get a byte value at a specified index into the buffer
int	getUnsignedShort(int index) Get a byte value at a specified index into the buffer
InputStream	inputStream(int index) Get an input stream to read the contents of a packet buffer
boolean	isCopyOnWrite() Get whether the buffer is marked 'copy on write'.
boolean	isFailOnWrite() Get whether the buffer is marked 'fail on write'.
boolean	isNative() Get if a buffer is backed by a native or heap IO buffer
PktBuffer	put(int index, byte value) Put a byte value at a specified index into the buffer
PktBuffer	putChar(int index, char value) Put a char value at a specified index into the buffer
int	putCharSequenceUTF(int index, CharSequence str) Puts the char sequence endoded as UTF-8 into the buffer
int	putCharUTF8(int index, char c) Puts a character encoded in UTF8 at the specified index.
PktBuffer	putDouble(int index, double value) Put a double value at a specified index into the buffer
PktBuffer	putFloat(int index, float value) Put a float value at a specified index into the buffer
PktBuffer	putFrom(int index, byte[] array, int arrayOffset, int length) Copy contents from a supplied byte array to a packet buffer
PktBuffer	putFrom(int index, ByteBuffer buffer, int length) Copy contents from a supplied byte buffer to a packet buffer
PktBuffer	putFrom(int index, char[] array, int arrayOffset, int length) Copy contents from a supplied char array to a packet buffer
PktBuffer	putFrom(int index, double[] array, int arrayOffset, int length) Copy contents from a supplied double array to a packet buffer
PktBuffer	putFrom(int index, float[] array, int arrayOffset, int length) Copy contents from a supplied float array to a packet buffer
PktBuffer	putFrom(int index, int[] array, int arrayOffset, int length) Copy contents from a supplied int array to a packet buffer
PktBuffer	putFrom(int index, long[] array, int arrayOffset, int length) Copy contents from a supplied long array to a packet buffer
void	putFrom(int index, PktBuffer buffer, int bufferOffset, int length) Copy contents from a supplied PktBuffer to this PktBuffer.
PktBuffer	putFrom(int index, short[] array, int arrayOffset, int length) Copy contents from a supplied short array to a packet buffer
void	putFromNative(int index, long address, int addressOffset, int length) Copy contents from supplied native memory address to this buffer.
PktBuffer	putInt(int index, int value) Put an integer value at a specified index into the buffer
PktBuffer	putLong(int index, long value) Put a long value at a specified index into the buffer
PktBuffer	putShort(int index, short value) Put a short value at a specified index into the buffer
int	putString(int index, String value) Put a string value at a specified index into the buffer
void	reset() Reset a packet buffer.
PktBuffer	setByteOrder(ByteOrder order) Set a packet buffer's byte order
PktBuffer	setCopyOnWrite() Mark the buffer as 'copy on write'.
PktBuffer	setFailOnWrite() Mark a buffer as 'fail on write'.
PktBuffer	setInitializer(PktBuffer.Initializer initializer) Set the buffer initializer
PktBuffer	setLength(int newLength) Set a packet buffer's length
String	toString() Return a string representation of a buffer
void	wrapIOBuffer(PktIOBuffer ioBuffer, int offset, int length) Set the underlying IO buffer

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

create

public static PktBuffer create(PktSerializable owner,
                               int bufferLength,
                               boolean isNative)

Create a new packet buffer

Parameters:

owner - The owner of the packet buffer

bufferLength - The length of the backing buffer. If <=0, the packet buffer will query the owner for the size.

isNative - Whether the backing IO buffer should be native or not

Returns:

Returns the created packet buffer.

Threading:

This method is safe for concurrent access by multiple threads

setInitializer

public final PktBuffer setInitializer(PktBuffer.Initializer initializer)

Set the buffer initializer

getInitializer

public final PktBuffer.Initializer getInitializer()

Get the buffer initializer

isNative

public final boolean isNative()

Get if a buffer is backed by a native or heap IO buffer

setByteOrder

public final PktBuffer setByteOrder(ByteOrder order)

Set a packet buffer's byte order

getByteOrder

public final ByteOrder getByteOrder()

Get a packet buffer's byte order

reset

public final void reset()

Reset a packet buffer.

This method resets the contents of a packet buffer. Upon return from this method, the packet buffer is reset to the same state as when it was first created.

wrapIOBuffer

public final void wrapIOBuffer(PktIOBuffer ioBuffer,
                               int offset,
                               int length)

Set the underlying IO buffer

getIOBuffer

public final PktIOBuffer getIOBuffer()

Get backing IO buffer

getBufferForRead

public final ByteBuffer getBufferForRead()

Get the buffer for read.

This method returns the underlying byte buffer for read purposes.

Note: The buffer returned in the raw underlying byte buffer that can be shared by many packet buffers (without intersecting windows). Therefore, the caller needs to take the offset into account when reading contents to ensure the right contents are read.

Threading:

This method is not safe for concurrent access by multiple threads

setFailOnWrite

public final PktBuffer setFailOnWrite()

Mark a buffer as 'fail on write'.

Returns:

Returns this packet buffer for invocation chaining.

This method marks the buffer as 'fail on write'. Any attempt to invoke getBufferForWrite() on a buffer marked as 'fail to write' will thrown an exception.

Marking a buffer as 'fail on write' clears the 'copy on write' flag if set.

Threading:

This method is not safe for concurrent access by multiple threads

clearFailOnWrite

public final PktBuffer clearFailOnWrite()

Clear a buffer's 'fail on write' flag.

Returns:

Returns this packet buffer for invocation chaining.

This method clear's the buffer 'fail on write' flag.

Threading:

This method is not safe for concurrent access by multiple threads

isFailOnWrite

public final boolean isFailOnWrite()

Get whether the buffer is marked 'fail on write'.

Returns:

Returns true in case the buffer is marked as fail on write and false otherwise.

Threading:

This method is not safe for concurrent access by multiple threads

setCopyOnWrite

public final PktBuffer setCopyOnWrite()

Mark the buffer as 'copy on write'.

Returns:

Returns this packet buffer for invocation chaining.

This method marks the buffer as 'copy on write'. The next call to getBufferForWrite() will cause the contained buffer to be cloned.

Throws:

IllegalStateException - Thrown if method is invoked on a packet buffer marked as 'fail on write'.

Threading:

This method is not safe for concurrent access by multiple threads

clearCopyOnWrite

public final PktBuffer clearCopyOnWrite()

Clear a buffer's 'copy on write' flag.

Returns:

Returns this packet buffer for invocation chaining.

This method clear's the buffer 'copy on write' flag.

Threading:

This method is not safe for concurrent access by multiple threads

isCopyOnWrite

public final boolean isCopyOnWrite()

Get whether the buffer is marked 'copy on write'.

Returns:

Returns true in case the buffer is marked as copy on write and false otherwise.

Threading:

This method is not safe for concurrent access by multiple threads

getBufferForWrite

public final ByteBuffer getBufferForWrite()

Get the buffer for write.

This method returns the raw underlyig byte buffer for write purposes. Writing to a buffer implies a change to the contents of the buffer. In case the 'copy on write' flag is set, the method will clone and and returns the clonee to the caller.

Note: The buffer returned in the raw underlying byte buffer that can be shared by many packet buffers (without intersecting windows). Therefore, the caller needs to take the offset into account when reading contents to ensure the right contents are read.

Threading:

This method is not safe for concurrent access by multiple threads

getOffset

public final int getOffset()

Get a packet's buffer's offset into the underlying buffer.

Threading:

This method is not safe for concurrent access by multiple threads

setLength

public final PktBuffer setLength(int newLength)

Set a packet buffer's length

Threading:

This method is not safe for concurrent access by multiple threads

getLength

public final int getLength()

Get a packet buffer's length

Threading:

This method is not safe for concurrent access by multiple threads

put

public final PktBuffer put(int index,
                           byte value)

Put a byte value at a specified index into the buffer

putChar

public final PktBuffer putChar(int index,
                               char value)

Put a char value at a specified index into the buffer

putShort

public final PktBuffer putShort(int index,
                                short value)

Put a short value at a specified index into the buffer

putInt

public final PktBuffer putInt(int index,
                              int value)

Put an integer value at a specified index into the buffer

putFloat

public final PktBuffer putFloat(int index,
                                float value)

Put a float value at a specified index into the buffer

putLong

public final PktBuffer putLong(int index,
                               long value)

Put a long value at a specified index into the buffer

putDouble

public final PktBuffer putDouble(int index,
                                 double value)

Put a double value at a specified index into the buffer

putString

public final int putString(int index,
                           String value)

Put a string value at a specified index into the buffer

putCharUTF8

public final int putCharUTF8(int index,
                             char c)

Puts a character encoded in UTF8 at the specified index.

Parameters:

c - The character

Returns:

the number of bytes written.

calculateUTFLength

public static final int calculateUTFLength(CharSequence str)

Calculates the length of the character sequence encoded as UTF-8.

Parameters:

str - The str whose UTF-8 length to calculate.

Returns:

The number of bytes needed to encode the string.

calculateUTFLength

public static final int calculateUTFLength(char c)

Calculates the length of the character encoded as UTF-8.

Parameters:

c - The character whose UTF-8 length to calculate.

Returns:

The number of bytes needed to encode the character.

putCharSequenceUTF

public final int putCharSequenceUTF(int index,
                                    CharSequence str)

Puts the char sequence endoded as UTF-8 into the buffer

Parameters:

index - The index into the buffer.

str - The char sequence

Returns:

the number of bytes written.

putFrom

public final PktBuffer putFrom(int index,
                               ByteBuffer buffer,
                               int length)

Copy contents from a supplied byte buffer to a packet buffer

Parameters:

index - The index relative to the packet buffer offset to copy to

buffer - The byte buffer to put from. The contents are copied from the supplied buffer's position marker.

length - The number of bytes to copy

putFrom

public final void putFrom(int index,
                          PktBuffer buffer,
                          int bufferOffset,
                          int length)

Copy contents from a supplied PktBuffer to this PktBuffer. The source's underlying buffer positions are left unchanged.

Parameters:

index - The index relative to the packet buffer offset to copy to

buffer - The packet buffer to put from. The contents are copied from the offset = bufferOffset into the packet buffer i.e. offset equal to bufferOffset + offset of the packet buffer into its backing byte buffer.

bufferOffset - The offset relative to the source's offset from which to copy.

length - The number of bytes to copy

putFrom

public final PktBuffer putFrom(int index,
                               byte[] array,
                               int arrayOffset,
                               int length)

Copy contents from a supplied byte array to a packet buffer

Parameters:

index - The index relative to the packet buffer offset to copy to

array - The byte array to put from.

arrayOffset - The offset into the byte array to copy from

length - The number of bytes to copy

putFrom

public final PktBuffer putFrom(int index,
                               char[] array,
                               int arrayOffset,
                               int length)

Copy contents from a supplied char array to a packet buffer

Parameters:

index - The index relative to the packet buffer offset to copy to

array - The char array to put from.

arrayOffset - The offset into the char array to copy from

length - The number of bytes to copy

putFrom

public final PktBuffer putFrom(int index,
                               short[] array,
                               int arrayOffset,
                               int length)

Copy contents from a supplied short array to a packet buffer

Parameters:

index - The index relative to the packet buffer offset to copy to

array - The short array to put from.

arrayOffset - The offset into the short array to copy from

length - The number of bytes to copy

putFrom

public final PktBuffer putFrom(int index,
                               int[] array,
                               int arrayOffset,
                               int length)

Copy contents from a supplied int array to a packet buffer

Parameters:

index - The index relative to the packet buffer offset to copy to

array - The int array to put from.

arrayOffset - The offset into the int array to copy from

length - The number of bytes to copy

putFrom

public final PktBuffer putFrom(int index,
                               float[] array,
                               int arrayOffset,
                               int length)

Copy contents from a supplied float array to a packet buffer

Parameters:

index - The index relative to the packet buffer offset to copy to

array - The float array to put from.

arrayOffset - The offset into the float array to copy from

length - The number of bytes to copy

putFrom

public final PktBuffer putFrom(int index,
                               long[] array,
                               int arrayOffset,
                               int length)

Copy contents from a supplied long array to a packet buffer

Parameters:

index - The index relative to the packet buffer offset to copy to

array - The long array to put from.

arrayOffset - The offset into the long array to copy from

length - The number of bytes to copy

putFrom

public final PktBuffer putFrom(int index,
                               double[] array,
                               int arrayOffset,
                               int length)

Copy contents from a supplied double array to a packet buffer

Parameters:

index - The index relative to the packet buffer offset to copy to

array - The double array to put from.

arrayOffset - The offset into the double array to copy from

length - The number of bytes to copy

putFromNative

public final void putFromNative(int index,
                                long address,
                                int addressOffset,
                                int length)

Copy contents from supplied native memory address to this buffer.

Parameters:

index - The index into this buffer at which to copy the bytes.

address - The address of the native memory to copy.

addressOffset - The offset from the native address to copy from

length - The number of bytes to copy.

get

public final byte get(int index)

Get a byte value at a specified index into the buffer

getUnsignedByte

public final int getUnsignedByte(int index)

Get a byte value at a specified index into the buffer

getChar

public final char getChar(int index)

Get a char value at a specified index into the buffer

getShort

public final short getShort(int index)

Get a short value at a specified index into the buffer

getUnsignedShort

public final int getUnsignedShort(int index)

Get a byte value at a specified index into the buffer

getInt

public final int getInt(int index)

Get a int value at a specified index into the buffer

getUnsignedInt

public final long getUnsignedInt(int index)

Get a byte value at a specified index into the buffer

getFloat

public final float getFloat(int index)

Get a float value at a specified index into the buffer

getLong

public final long getLong(int index)

Get a long value at a specified index into the buffer

getDouble

public final double getDouble(int index)

Get a double value at a specified index into the buffer

getString

public final String getString(int index,
                              int length)

Get a string value at a specified index into the buffer

getTo

public final PktBuffer getTo(int index,
                             ByteBuffer buffer,
                             int length)

Copy contents from a packet buffer to a supplied byte buffer

Parameters:

index - The index relative to the packet buffer offset to copy from

buffer - The byte buffer to copy to. Data is copied starting at the buffer's position marker.

length - The number of bytes to copy

getTo

public final PktBuffer getTo(int index,
                             byte[] array,
                             int arrayOffset,
                             int length)

Copy contents from a packet buffer to a supplied byte array

Parameters:

index - The index relative to the packet buffer offset to copy from

array - The array to copy to.

arrayOffset - The offset into the byte array to copy from

length - The number of bytes to copy

getTo

public final PktBuffer getTo(int index,
                             char[] array,
                             int arrayOffset,
                             int length)

Copy contents from a packet buffer to a supplied char array

Parameters:

index - The index relative to the packet buffer offset to copy from

array - The array to copy to.

arrayOffset - The offset into the byte array to copy from

length - The number of bytes to copy

getTo

public final PktBuffer getTo(int index,
                             short[] array,
                             int arrayOffset,
                             int length)

Copy contents from a packet buffer to a supplied short array

Parameters:

index - The index relative to the packet buffer offset to copy from

array - The array to copy to.

arrayOffset - The offset into the byte array to copy from

length - The number of bytes to copy

getTo

public final PktBuffer getTo(int index,
                             int[] array,
                             int arrayOffset,
                             int length)

Copy contents from a packet buffer to a supplied int array

Parameters:

index - The index relative to the packet buffer offset to copy from

array - The array to copy to.

arrayOffset - The offset into the byte array to copy from

length - The number of bytes to copy

getTo

public final PktBuffer getTo(int index,
                             float[] array,
                             int arrayOffset,
                             int length)

Copy contents from a packet buffer to a supplied float array

Parameters:

index - The index relative to the packet buffer offset to copy from

array - The array to copy to.

arrayOffset - The offset into the byte array to copy from

length - The number of bytes to copy

getTo

public final PktBuffer getTo(int index,
                             long[] array,
                             int arrayOffset,
                             int length)

Copy contents from a packet buffer to a supplied long array

Parameters:

index - The index relative to the packet buffer offset to copy from

array - The array to copy to.

arrayOffset - The offset into the byte array to copy from

length - The number of bytes to copy

getTo

public final PktBuffer getTo(int index,
                             double[] array,
                             int arrayOffset,
                             int length)

Copy contents from a packet buffer to a supplied double array

Parameters:

index - The index relative to the packet buffer offset to copy from

array - The array to copy to.

arrayOffset - The offset into the byte array to copy from

length - The number of bytes to copy

getToNative

public final PktBuffer getToNative(int index,
                                   long address,
                                   int addressOffset,
                                   int length)

Copy contents from a packet buffer to native memory

Parameters:

index - The index relative to the packet buffer offset to copy from

address - The address of the native memory to copy to.

length - The number of bytes to copy.

inputStream

public final InputStream inputStream(int index)

Get an input stream to read the contents of a packet buffer

Parameters:

index - The index relative to the packet buffer offset from where the input stream will start reading.

Threading:

The iput stream returned by this method is not safe for concurrent access by multiple threads

fork

public final PktBuffer fork()

Fork a packet buffer

This method creates a new packet buffer, associates it with the same underlying IO buffer as this one and mark *both* buffers as copy on write (to make sure changes to one don't corrupt the other)

toString

public final String toString()

Return a string representation of a buffer

Overrides:

toString in class Object