Package org.agrona

Class ExpandableDirectByteBuffer

  • All Implemented Interfaces:
    java.lang.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 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
      • byteBuffer

        private java.nio.ByteBuffer byteBuffer
    • Constructor Detail

      • 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​(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
      • calculateExpansion

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