org.agrona

Interface DirectBuffer

All Superinterfaces:

java.lang.Comparable<DirectBuffer>

All Known Subinterfaces:

AtomicBuffer, MutableDirectBuffer

All Known Implementing Classes:

ExpandableArrayBuffer, ExpandableDirectByteBuffer, UnsafeBuffer

public interface DirectBuffer
extends java.lang.Comparable<DirectBuffer>

Abstraction over a range of buffer types that allows fields to be read in native typed fashion.

ByteOrder of a wrapped buffer is not applied to the DirectBuffer; To control ByteOrder use the appropriate method with the ByteOrder overload.

Method Summary

Modifier and Type	Method and Description
long	addressOffset() Reads the underlying offset to to the memory address.
void	boundsCheck(int index, int length) Check that a given length of bytes is within the bounds from a given index.
byte[]	byteArray() Get the underlying byte[] if one exists.
java.nio.ByteBuffer	byteBuffer() Get the underlying ByteBuffer if one exists.
int	capacity() Get the capacity of the underlying buffer.
void	checkLimit(int limit) Check that a given limit is not greater than the capacity of a buffer from a given offset.
byte	getByte(int index) Get the value at a given index.
void	getBytes(int index, byte[] dst) Get from the underlying buffer into a supplied byte array.
void	getBytes(int index, byte[] dst, int offset, int length) Get bytes from the underlying buffer into a supplied byte array.
void	getBytes(int index, java.nio.ByteBuffer dstBuffer, int length) Get from the underlying buffer into a supplied ByteBuffer current Buffer.position().
void	getBytes(int index, java.nio.ByteBuffer dstBuffer, int dstOffset, int length) Get from the underlying buffer into a supplied ByteBuffer at a offset.
void	getBytes(int index, MutableDirectBuffer dstBuffer, int dstIndex, int length) Get bytes from this DirectBuffer into the provided MutableDirectBuffer at given indices.
char	getChar(int index) Get the value at a given index.
char	getChar(int index, java.nio.ByteOrder byteOrder) Get the value at a given index.
double	getDouble(int index) Get the value at a given index.
double	getDouble(int index, java.nio.ByteOrder byteOrder) Get the value at a given index.
float	getFloat(int index) Get the value at a given index.
float	getFloat(int index, java.nio.ByteOrder byteOrder) Get the value at a given index.
int	getInt(int index) Get the value at a given index.
int	getInt(int index, java.nio.ByteOrder byteOrder) Get the value at a given index.
long	getLong(int index) Get the value at a given index.
long	getLong(int index, java.nio.ByteOrder byteOrder) Get the value at a given index.
short	getShort(int index) Get the value at a given index.
short	getShort(int index, java.nio.ByteOrder byteOrder) Get the value at a given index.
java.lang.String	getStringAscii(int index) Get a String from bytes encoded in ASCII format that is length prefixed.
java.lang.String	getStringAscii(int index, java.nio.ByteOrder byteOrder) Get a String from bytes encoded in ASCII format that is length prefixed.
java.lang.String	getStringAscii(int index, int length) Get part of String from bytes encoded in ASCII format that is length prefixed.
java.lang.String	getStringUtf8(int index) Get a String from bytes encoded in UTF-8 format that is length prefixed.
java.lang.String	getStringUtf8(int index, java.nio.ByteOrder byteOrder) Get a String from bytes encoded in UTF-8 format that is length prefixed.
java.lang.String	getStringUtf8(int index, int length) Get part of String from bytes encoded in UTF-8 format that is length prefixed.
java.lang.String	getStringWithoutLengthAscii(int index, int length) Get an encoded ASCII String from the buffer that does not have a length prefix.
java.lang.String	getStringWithoutLengthUtf8(int index, int length) Get an encoded UTF-8 String from the buffer that does not have a length prefix.
int	parseIntAscii(int index, int length) Get the ASCII encoded integer value at a given index.
long	parseLongAscii(int index, int length) Get the ASCII encoded long integer value at a given index.
int	parseNaturalIntAscii(int index, int length) Get the ASCII encoded int sized natural value at a given index.
long	parseNaturalLongAscii(int index, int length) Get the ASCII encoded long sized natural value at a given index.
void	wrap(byte[] buffer) Attach a view to a byte[] for providing direct access.
void	wrap(byte[] buffer, int offset, int length) Attach a view to a byte[] for providing direct access.
void	wrap(java.nio.ByteBuffer buffer) Attach a view to a ByteBuffer for providing direct access, the ByteBuffer can be heap based or direct.
void	wrap(java.nio.ByteBuffer buffer, int offset, int length) Attach a view to a ByteBuffer for providing direct access.
void	wrap(DirectBuffer buffer) Attach a view to an existing DirectBuffer
void	wrap(DirectBuffer buffer, int offset, int length) Attach a view to a DirectBuffer for providing direct access.
void	wrap(long address, int length) Attach a view to an off-heap memory region by address.
int	wrapAdjustment() Get the adjustment in indices between an index in this buffer and the wrapped object.

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

wrap

void wrap(byte[] buffer)

Attach a view to a byte[] for providing direct access.

Parameters:

buffer - to which the view is attached.

wrap

void wrap(byte[] buffer,
          int offset,
          int length)

Attach a view to a byte[] for providing direct access.

Parameters:

buffer - to which the view is attached.

offset - at which the view begins.

length - of the buffer included in the view

wrap

void wrap(java.nio.ByteBuffer buffer)

Attach a view to a ByteBuffer for providing direct access, the ByteBuffer can be heap based or direct. The ByteBuffer.order() is not relevant for accessing the wrapped buffer.

When using this method to wrap the view of the ByteBuffer the entire ByteBuffer gets wrapped between index 0 and capacity. If you want to just wrap the ByteBuffer between the position and the limit then you should use the wrap(ByteBuffer, int, int) method, eg: directBuffer.wrap(byteBuffer, byteBuffer.position(), byteBuffer.remaining());

Parameters:

buffer - to which the view is attached.

wrap

void wrap(java.nio.ByteBuffer buffer,
          int offset,
          int length)

Attach a view to a ByteBuffer for providing direct access.

The ByteBuffer.order() is not relevant for accessing the wrapped buffer.

Parameters:

buffer - to which the view is attached.

offset - at which the view begins.

length - of the buffer included in the view

wrap

void wrap(DirectBuffer buffer)

Attach a view to an existing DirectBuffer

Parameters:

buffer - to which the view is attached.

wrap

void wrap(DirectBuffer buffer,
          int offset,
          int length)

Attach a view to a DirectBuffer for providing direct access.

Parameters:

buffer - to which the view is attached.

offset - at which the view begins.

length - of the buffer included in the view

wrap

void wrap(long address,
          int length)

Attach a view to an off-heap memory region by address.

Parameters:

address - where the memory begins off-heap

length - of the buffer from the given address

addressOffset

long addressOffset()

Reads the underlying offset to to the memory address.

Returns:

the underlying offset to to the memory address.

byteArray

byte[] byteArray()

Get the underlying byte[] if one exists.

NB: there may not be a one-to-one mapping between indices on this buffer and the underlying byte[], see wrapAdjustment().

Returns:

the underlying byte[] if one exists.

byteBuffer

java.nio.ByteBuffer byteBuffer()

Get the underlying ByteBuffer if one exists.

NB: there may not be a one-to-one mapping between indices on this buffer and the underlying byte[], see wrapAdjustment().

Returns:

the underlying ByteBuffer if one exists.

capacity

int capacity()

Get the capacity of the underlying buffer.

Returns:

the capacity of the underlying buffer in bytes.

checkLimit

void checkLimit(int limit)

Check that a given limit is not greater than the capacity of a buffer from a given offset.

Can be overridden in a DirectBuffer subclass to enable an extensible buffer or handle retry after a flush.

Parameters:

limit - up to which access is required.

Throws:

java.lang.IndexOutOfBoundsException - if limit is beyond buffer capacity.

getLong

long getLong(int index,
             java.nio.ByteOrder byteOrder)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

byteOrder - of the value to be read.

Returns:

the value for at a given index

getLong

long getLong(int index)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

Returns:

the value for at a given index

getInt

int getInt(int index,
           java.nio.ByteOrder byteOrder)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

byteOrder - of the value to be read.

Returns:

the value at a given index.

getInt

int getInt(int index)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

Returns:

the value for a given index

parseNaturalIntAscii

int parseNaturalIntAscii(int index,
                         int length)

Get the ASCII encoded int sized natural value at a given index.

Parameters:

index - in bytes from which to get.

length - the length in bytes to parse

Returns:

the value at a given index

parseNaturalLongAscii

long parseNaturalLongAscii(int index,
                           int length)

Get the ASCII encoded long sized natural value at a given index.

Parameters:

index - in bytes from which to get.

length - the length in bytes to parse

Returns:

the value at a given index

parseIntAscii

int parseIntAscii(int index,
                  int length)

Get the ASCII encoded integer value at a given index.

Parameters:

index - in bytes from which to get.

length - the length in bytes to parse

Returns:

the value at a given index

parseLongAscii

long parseLongAscii(int index,
                    int length)

Get the ASCII encoded long integer value at a given index.

Parameters:

index - in bytes from which to get.

length - the length in bytes to parse

Returns:

the value at a given index

getDouble

double getDouble(int index,
                 java.nio.ByteOrder byteOrder)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

byteOrder - of the value to be read.

Returns:

the value at a given index.

getDouble

double getDouble(int index)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

Returns:

the value at a given index.

getFloat

float getFloat(int index,
               java.nio.ByteOrder byteOrder)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

byteOrder - of the value to be read.

Returns:

the value at a given index.

getFloat

float getFloat(int index)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

Returns:

the value at a given index.

getShort

short getShort(int index,
               java.nio.ByteOrder byteOrder)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

byteOrder - of the value to be read.

Returns:

the value at a given index.

getShort

short getShort(int index)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

Returns:

the value at a given index.

getChar

char getChar(int index,
             java.nio.ByteOrder byteOrder)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

byteOrder - of the value to be read.

Returns:

the value at a given index.

getChar

char getChar(int index)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

Returns:

the value at a given index.

getByte

byte getByte(int index)

Get the value at a given index.

Parameters:

index - in bytes from which to get.

Returns:

the value at a given index.

getBytes

void getBytes(int index,
              byte[] dst)

Get from the underlying buffer into a supplied byte array. This method will try to fill the supplied byte array.

Parameters:

index - in the underlying buffer to start from.

dst - into which the dst will be copied.

getBytes

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

Get bytes from the underlying buffer into a supplied byte array.

Parameters:

index - in the underlying buffer to start from.

dst - into which the bytes will be copied.

offset - in the supplied buffer to start the copy

length - of the supplied buffer to use.

getBytes

void getBytes(int index,
              MutableDirectBuffer dstBuffer,
              int dstIndex,
              int length)

Get bytes from this DirectBuffer into the provided MutableDirectBuffer at given indices.

Parameters:

index - in this buffer to begin getting the bytes.

dstBuffer - to which the bytes will be copied.

dstIndex - in the channel buffer to which the byte copy will begin.

length - of the bytes to be copied.

getBytes

void getBytes(int index,
              java.nio.ByteBuffer dstBuffer,
              int length)

Get from the underlying buffer into a supplied ByteBuffer current Buffer.position().

The destination buffer will have its Buffer.position() advanced as a result.

Parameters:

index - in the underlying buffer to start from.

dstBuffer - into which the bytes will be copied.

length - of the supplied buffer to use.

getBytes

void getBytes(int index,
              java.nio.ByteBuffer dstBuffer,
              int dstOffset,
              int length)

Get from the underlying buffer into a supplied ByteBuffer at a offset.

The destination buffer will not have its Buffer.position() advanced as a result.

Parameters:

index - in the underlying buffer to start from.

dstBuffer - into which the bytes will be copied.

dstOffset - in the target buffer.

length - of the supplied buffer to use.

getStringAscii

java.lang.String getStringAscii(int index)

Get a String from bytes encoded in ASCII format that is length prefixed.

Parameters:

index - at which the String begins.

Returns:

the String as represented by the ASCII encoded bytes.

getStringAscii

java.lang.String getStringAscii(int index,
                                java.nio.ByteOrder byteOrder)

Get a String from bytes encoded in ASCII format that is length prefixed.

Parameters:

index - at which the String begins.

byteOrder - for the length at the beginning of the String.

Returns:

the String as represented by the ASCII encoded bytes.

getStringAscii

java.lang.String getStringAscii(int index,
                                int length)

Get part of String from bytes encoded in ASCII format that is length prefixed.

Parameters:

index - at which the String begins.

length - of the String in bytes to decode.

Returns:

the String as represented by the ASCII encoded bytes.

getStringWithoutLengthAscii

java.lang.String getStringWithoutLengthAscii(int index,
                                             int length)

Get an encoded ASCII String from the buffer that does not have a length prefix.

Parameters:

index - at which the String begins.

length - of the String in bytes to decode.

Returns:

the String as represented by the Ascii encoded bytes.

getStringUtf8

java.lang.String getStringUtf8(int index)

Get a String from bytes encoded in UTF-8 format that is length prefixed.

Parameters:

index - at which the String begins.

Returns:

the String as represented by the UTF-8 encoded bytes.

getStringUtf8

java.lang.String getStringUtf8(int index,
                               java.nio.ByteOrder byteOrder)

Get a String from bytes encoded in UTF-8 format that is length prefixed.

Parameters:

index - at which the String begins.

byteOrder - for the length at the beginning of the String.

Returns:

the String as represented by the UTF-8 encoded bytes.

getStringUtf8

java.lang.String getStringUtf8(int index,
                               int length)

Get part of String from bytes encoded in UTF-8 format that is length prefixed.

Parameters:

index - at which the String begins.

length - of the String in bytes to decode.

Returns:

the String as represented by the UTF-8 encoded bytes.

getStringWithoutLengthUtf8

java.lang.String getStringWithoutLengthUtf8(int index,
                                            int length)

Get an encoded UTF-8 String from the buffer that does not have a length prefix.

Parameters:

index - at which the String begins.

length - of the String in bytes to decode.

Returns:

the String as represented by the UTF-8 encoded bytes.

boundsCheck

void boundsCheck(int index,
                 int length)

Check that a given length of bytes is within the bounds from a given index.

Parameters:

index - from which to check.

length - in bytes of the range to check.

Throws:

java.lang.IndexOutOfBoundsException - if the length goes outside of the capacity range.

wrapAdjustment

int wrapAdjustment()

Get the adjustment in indices between an index in this buffer and the wrapped object. The wrapped object might be a ByteBuffer or a byte[].

You only need to use this adjustment if you plan to perform operations on the underlying byte array or byte buffer that rely on their indices.

Returns:

the adjustment in indices between an index in this buffer and the wrapped object.

See Also:

byteArray(), byteBuffer()