Package org.agrona

Class ExpandableDirectByteBuffer

java.lang.Object

org.agrona.AbstractMutableDirectBuffer

org.agrona.ExpandableDirectByteBuffer

All Implemented Interfaces:

Comparable<DirectBuffer>, DirectBuffer, MutableDirectBuffer

public class ExpandableDirectByteBuffer
extends AbstractMutableDirectBuffer

Expandable MutableDirectBuffer that is backed by a direct ByteBuffer. When values are put into the buffer beyond its current length, then it will be expanded to accommodate the resulting position for the value.

Put operations will expand the capacity as necessary up to MAX_BUFFER_LENGTH. Get operations will throw a IndexOutOfBoundsException if past current capacity.

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

Note: this class has a natural ordering that is inconsistent with equals. Types may be different but equal on buffer contents.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	INITIAL_CAPACITY	Initial capacity of the buffer from which it will expand.
static final int	MAX_BUFFER_LENGTH	Maximum length to which the underlying buffer can grow.

Fields inherited from class org.agrona.AbstractMutableDirectBuffer

addressOffset, byteArray, capacity

Fields inherited from interface org.agrona.DirectBuffer

DISABLE_ARRAY_CONTENT_PRINTOUT_PROP_NAME, DISABLE_BOUNDS_CHECKS_PROP_NAME, SHOULD_BOUNDS_CHECK, STR_HEADER_LEN

Constructor Summary

Constructors

Constructor	Description
ExpandableDirectByteBuffer()	Create an ExpandableDirectByteBuffer with an initial length of INITIAL_CAPACITY.
ExpandableDirectByteBuffer(int initialCapacity)	Create an ExpandableDirectByteBuffer with a provided initial capacity.

Method Summary

Modifier and Type	Method	Description
byte[]	byteArray()	Get the underlying byte[] if one exists.
ByteBuffer	byteBuffer()	Get the underlying ByteBuffer if one exists.
void	checkLimit(int limit)	Check that a given limit is not greater than the capacity of a buffer from a given offset.
protected final void	ensureCapacity(int index, int length)	A hook to ensure the underlying buffer has enough capacity for writing data into the buffer.
boolean	isExpandable()	Is this buffer expandable to accommodate putting data into it beyond the current capacity?
String	toString()
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(long address, int length)	Attach a view to an off-heap memory region by address.
void	wrap(ByteBuffer buffer)	Attach a view to a ByteBuffer for providing direct access, the ByteBuffer can be heap based or direct.
void	wrap(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.
int	wrapAdjustment()	Get the adjustment in indices between an index in this buffer and the wrapped object.

Methods inherited from class org.agrona.AbstractMutableDirectBuffer

addressOffset, boundsCheck, boundsCheck0, capacity, compareTo, equals, getByte, getBytes, getBytes, getBytes, getBytes, getBytes, getChar, getChar, getDouble, getDouble, getFloat, getFloat, getInt, getInt, getLong, getLong, getShort, getShort, getStringAscii, getStringAscii, getStringAscii, getStringAscii, getStringAscii, getStringAscii, getStringUtf8, getStringUtf8, getStringUtf8, getStringWithoutLengthAscii, getStringWithoutLengthAscii, getStringWithoutLengthUtf8, hashCode, parseIntAscii, parseLongAscii, parseNaturalIntAscii, parseNaturalLongAscii, putByte, putBytes, putBytes, putBytes, putBytes, putBytes, putChar, putChar, putDouble, putDouble, putFloat, putFloat, putInt, putInt, putIntAscii, putLong, putLong, putLongAscii, putNaturalIntAscii, putNaturalIntAsciiFromEnd, putNaturalLongAscii, putNaturalPaddedIntAscii, putShort, putShort, putStringAscii, putStringAscii, putStringAscii, putStringAscii, putStringUtf8, putStringUtf8, putStringUtf8, putStringUtf8, putStringWithoutLengthAscii, putStringWithoutLengthAscii, putStringWithoutLengthAscii, putStringWithoutLengthAscii, putStringWithoutLengthUtf8, setMemory

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

MAX_BUFFER_LENGTH

public static final int MAX_BUFFER_LENGTH

Maximum length to which the underlying buffer can grow.

See Also:

• Constant Field Values

INITIAL_CAPACITY

public static final int INITIAL_CAPACITY

Initial capacity of the buffer from which it will expand.

See Also:

• Constant Field Values

Constructor Details

ExpandableDirectByteBuffer

public ExpandableDirectByteBuffer()

Create an ExpandableDirectByteBuffer with an initial length of INITIAL_CAPACITY.

ExpandableDirectByteBuffer

public ExpandableDirectByteBuffer(int initialCapacity)

Create an ExpandableDirectByteBuffer with a provided initial capacity.

Parameters:

initialCapacity - of the backing array.

Method Details

wrap

public void wrap(byte[] buffer)

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

Parameters:

buffer - to which the view is attached.

wrap

public 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 - in bytes at which the view begins.

length - in bytes of the buffer included in the view.

wrap

public void wrap(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 DirectBuffer.wrap(ByteBuffer, int, int) method, eg:

directBuffer.wrap(byteBuffer, byteBuffer.position(), byteBuffer.remaining());

Parameters:

buffer - to which the view is attached.

wrap

public void wrap(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 - in bytes at which the view begins.

length - in bytes of the buffer included in the view.

wrap

public void wrap(DirectBuffer buffer)

Attach a view to an existing DirectBuffer.

Parameters:

buffer - to which the view is attached.

wrap

public 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 - in bytes at which the view begins.

length - in bytes of the buffer included in the view.

wrap

public 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.

byteArray

public 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 DirectBuffer.wrapAdjustment().

Specified by:

byteArray in interface DirectBuffer

Overrides:

byteArray in class AbstractMutableDirectBuffer

Returns:

the underlying byte[] if one exists.

See Also:

• DirectBuffer.wrap(byte[])
• DirectBuffer.wrap(byte[], int, int)
• DirectBuffer.wrap(ByteBuffer)
• DirectBuffer.wrap(ByteBuffer, int, int)

byteBuffer

public 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 DirectBuffer.wrapAdjustment().

Returns:

the underlying ByteBuffer if one exists.

isExpandable

public boolean isExpandable()

Is this buffer expandable to accommodate putting data into it beyond the current capacity?

Returns:

true is the underlying storage can expand otherwise false.

wrapAdjustment

public 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:

• DirectBuffer.byteArray()
• DirectBuffer.byteBuffer()

checkLimit

public 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.

Specified by:

checkLimit in interface DirectBuffer

Overrides:

checkLimit in class AbstractMutableDirectBuffer

Parameters:

limit - up to which access is required.

toString

public String toString()

Overrides:

toString in class Object

ensureCapacity

protected final void ensureCapacity(int index,
 int length)

Description copied from class: AbstractMutableDirectBuffer

A hook to ensure the underlying buffer has enough capacity for writing data into the buffer.

Specified by:

ensureCapacity in class AbstractMutableDirectBuffer

Parameters:

index - at which write occurs.

length - in bytes.