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 and Description
static int	INITIAL_CAPACITY Initial capacity of the buffer from which it will expand.
static 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 and 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 and 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 void	ensureCapacity(int index, int length)
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(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.
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 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 Detail

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 Detail

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 Detail

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)

Specified by:

ensureCapacity in class AbstractMutableDirectBuffer