Package org.agrona

Interface DirectBuffer

All Superinterfaces:
Comparable<DirectBuffer>
All Known Subinterfaces:
AtomicBuffer, MutableDirectBuffer
All Known Implementing Classes:
AbstractMutableDirectBuffer, ExpandableArrayBuffer, ExpandableDirectByteBuffer, UnsafeBuffer

public interface DirectBuffer extends 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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    Deprecated.
    static final String
    Name of the system property that specify if the bounds checks should be disabled.
    static final boolean
    Should bounds-checks operations be done or not.
    static final int
    Length of the header on strings to denote the length of the string in bytes.
  • Method Summary

    Modifier and Type
    Method
    Description
    long
    Reads the underlying offset 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[]
    Get the underlying byte[] if one exists.
    Get the underlying ByteBuffer if one exists.
    int
    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, ByteBuffer dstBuffer, int length)
    Get from the underlying buffer into a supplied ByteBuffer current Buffer.position().
    void
    getBytes(int index, ByteBuffer dstBuffer, int dstOffset, int length)
    Get from the underlying buffer into a supplied ByteBuffer at an 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, ByteOrder byteOrder)
    Get the value at a given index.
    double
    getDouble(int index)
    Get the value at a given index.
    double
    getDouble(int index, ByteOrder byteOrder)
    Get the value at a given index.
    float
    getFloat(int index)
    Get the value at a given index.
    float
    getFloat(int index, ByteOrder byteOrder)
    Get the value at a given index.
    int
    getInt(int index)
    Get the value at a given index.
    int
    getInt(int index, ByteOrder byteOrder)
    Get the value at a given index.
    long
    getLong(int index)
    Get the value at a given index.
    long
    getLong(int index, ByteOrder byteOrder)
    Get the value at a given index.
    short
    getShort(int index)
    Get the value at a given index.
    short
    getShort(int index, ByteOrder byteOrder)
    Get the value at a given index.
    getStringAscii(int index)
    Get a String from bytes encoded in ASCII format that is length prefixed.
    getStringAscii(int index, int length)
    Get part of a String from bytes encoded in ASCII format that is length prefixed.
    int
    getStringAscii(int index, int length, Appendable appendable)
    Get part of a String from bytes encoded in ASCII format that is length prefixed and append to an Appendable.
    int
    getStringAscii(int index, Appendable appendable)
    Get a String from bytes encoded in ASCII format that is length prefixed and append to an Appendable.
    int
    getStringAscii(int index, Appendable appendable, ByteOrder byteOrder)
    Get a String from bytes encoded in ASCII format that is length prefixed and append to an Appendable.
    getStringAscii(int index, ByteOrder byteOrder)
    Get a String from bytes encoded in ASCII format that is length prefixed.
    getStringUtf8(int index)
    Get a String from bytes encoded in UTF-8 format that is length prefixed.
    getStringUtf8(int index, int length)
    Get part of String from bytes encoded in UTF-8 format that is length prefixed.
    getStringUtf8(int index, ByteOrder byteOrder)
    Get a String from bytes encoded in UTF-8 format that is length prefixed.
    getStringWithoutLengthAscii(int index, int length)
    Get an encoded ASCII String from the buffer that does not have a length prefix.
    int
    getStringWithoutLengthAscii(int index, int length, Appendable appendable)
    Get an encoded ASCII String from the buffer that does not have a length prefix and append to an Appendable.
    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)
    Parse the ASCII encoded integer value at a given index.
    long
    parseLongAscii(int index, int length)
    Parse the ASCII encoded long integer value at a given index.
    int
    parseNaturalIntAscii(int index, int length)
    Parse the ASCII encoded int sized natural value at a given index.
    long
    parseNaturalLongAscii(int index, int length)
    Parse 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(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
    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
    Get the adjustment in indices between an index in this buffer and the wrapped object.

    Methods inherited from interface java.lang.Comparable

    compareTo
  • Field Details

    • STR_HEADER_LEN

      static final int STR_HEADER_LEN
      Length of the header on strings to denote the length of the string in bytes.
      See Also:
    • DISABLE_ARRAY_CONTENT_PRINTOUT_PROP_NAME

      @Deprecated static final String DISABLE_ARRAY_CONTENT_PRINTOUT_PROP_NAME
      Deprecated.
      Don't print the content of the array while calling toString() on buffer instance.
      See Also:
    • DISABLE_BOUNDS_CHECKS_PROP_NAME

      static final String DISABLE_BOUNDS_CHECKS_PROP_NAME
      Name of the system property that specify if the bounds checks should be disabled. To disable bounds checks set this property to true.
      See Also:
    • SHOULD_BOUNDS_CHECK

      static final boolean SHOULD_BOUNDS_CHECK
      Should bounds-checks operations be done or not. Controlled by the DISABLE_BOUNDS_CHECKS_PROP_NAME system property.
      See Also:
  • Method Details

    • 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 - in bytes at which the view begins.
      length - in bytes of the buffer included in the view.
    • wrap

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

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

      Parameters:
      buffer - to which the view is attached.
    • wrap

      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

      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 - in bytes at which the view begins.
      length - in bytes 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 the memory address.
      Returns:
      the underlying offset 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.
      See Also:
    • byteBuffer

      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:
      IndexOutOfBoundsException - if limit is beyond buffer capacity.
    • getLong

      long getLong(int index, 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, 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)
      Parse 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)
      Parse 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)
      Parse 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)
      Parse 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, 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, 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, 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, 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, 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, ByteBuffer dstBuffer, int dstOffset, int length)
      Get from the underlying buffer into a supplied ByteBuffer at an 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

      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

      int getStringAscii(int index, Appendable appendable)
      Get a String from bytes encoded in ASCII format that is length prefixed and append to an Appendable.
      Parameters:
      index - at which the String begins.
      appendable - to append the chars to.
      Returns:
      the number of bytes copied.
    • getStringAscii

      String getStringAscii(int index, 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

      int getStringAscii(int index, Appendable appendable, ByteOrder byteOrder)
      Get a String from bytes encoded in ASCII format that is length prefixed and append to an Appendable.
      Parameters:
      index - at which the String begins.
      appendable - to append the chars to.
      byteOrder - for the length at the beginning of the String.
      Returns:
      the number of bytes copied.
    • getStringAscii

      String getStringAscii(int index, int length)
      Get part of a 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.
    • getStringAscii

      int getStringAscii(int index, int length, Appendable appendable)
      Get part of a String from bytes encoded in ASCII format that is length prefixed and append to an Appendable.
      Parameters:
      index - at which the String begins.
      length - of the String in bytes to decode.
      appendable - to append the chars to.
      Returns:
      the number of bytes copied.
    • getStringWithoutLengthAscii

      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.
    • getStringWithoutLengthAscii

      int getStringWithoutLengthAscii(int index, int length, Appendable appendable)
      Get an encoded ASCII String from the buffer that does not have a length prefix and append to an Appendable.
      Parameters:
      index - at which the String begins.
      length - of the String in bytes to decode.
      appendable - to append the chars to.
      Returns:
      the number of bytes copied.
    • getStringUtf8

      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

      String getStringUtf8(int index, 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

      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

      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:
      IndexOutOfBoundsException - if the length goes outside 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: