Package org.agrona

Class ExpandableArrayBuffer

  • All Implemented Interfaces:
    java.lang.Comparable<DirectBuffer>, DirectBuffer, MutableDirectBuffer

    public class ExpandableArrayBuffer
    extends AbstractMutableDirectBuffer
    Expandable MutableDirectBuffer that is backed by an array. 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_ARRAY_LENGTH. Get operations will throw a IndexOutOfBoundsException if past current capacity.

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

    • Field Detail

      • MAX_ARRAY_LENGTH

        public static final int MAX_ARRAY_LENGTH
        Maximum length to which the underlying buffer can grow. Some JVMs store state in the last few bytes.
        See Also:
        Constant Field Values
      • INITIAL_CAPACITY

        public static final int INITIAL_CAPACITY
        Initial capacity of the buffer from which it will expand as necessary.
        See Also:
        Constant Field Values
    • Constructor Detail

      • ExpandableArrayBuffer

        public ExpandableArrayBuffer​(int initialCapacity)
        Create an ExpandableArrayBuffer with a provided initial length.
        Parameters:
        initialCapacity - of the buffer.
    • 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​(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 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​(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 - 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.
      • byteBuffer

        public 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 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 java.lang.String toString()
        Overrides:
        toString in class java.lang.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.
      • calculateExpansion

        private static int calculateExpansion​(int currentLength,
                                              long requiredLength)