Package org.agrona

Interface DirectBuffer

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      long addressOffset()
      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[] byteArray()
      Get the underlying byte[] if one exists.
      java.nio.ByteBuffer byteBuffer()
      Get the underlying ByteBuffer if one exists.
      int capacity()
      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, java.nio.ByteBuffer dstBuffer, int length)
      Get from the underlying buffer into a supplied ByteBuffer current Buffer.position().
      void getBytes​(int index, java.nio.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, java.nio.ByteOrder byteOrder)
      Get the value at a given index.
      double getDouble​(int index)
      Get the value at a given index.
      double getDouble​(int index, java.nio.ByteOrder byteOrder)
      Get the value at a given index.
      float getFloat​(int index)
      Get the value at a given index.
      float getFloat​(int index, java.nio.ByteOrder byteOrder)
      Get the value at a given index.
      int getInt​(int index)
      Get the value at a given index.
      int getInt​(int index, java.nio.ByteOrder byteOrder)
      Get the value at a given index.
      long getLong​(int index)
      Get the value at a given index.
      long getLong​(int index, java.nio.ByteOrder byteOrder)
      Get the value at a given index.
      short getShort​(int index)
      Get the value at a given index.
      short getShort​(int index, java.nio.ByteOrder byteOrder)
      Get the value at a given index.
      java.lang.String getStringAscii​(int index)
      Get a String from bytes encoded in ASCII format that is length prefixed.
      java.lang.String 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, java.lang.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, java.lang.Appendable appendable)
      Get a String from bytes encoded in ASCII format that is length prefixed and append to an Appendable.
      int getStringAscii​(int index, java.lang.Appendable appendable, java.nio.ByteOrder byteOrder)
      Get a String from bytes encoded in ASCII format that is length prefixed and append to an Appendable.
      java.lang.String getStringAscii​(int index, java.nio.ByteOrder byteOrder)
      Get a String from bytes encoded in ASCII format that is length prefixed.
      java.lang.String getStringUtf8​(int index)
      Get a String from bytes encoded in UTF-8 format that is length prefixed.
      java.lang.String getStringUtf8​(int index, int length)
      Get part of String from bytes encoded in UTF-8 format that is length prefixed.
      java.lang.String getStringUtf8​(int index, java.nio.ByteOrder byteOrder)
      Get a String from bytes encoded in UTF-8 format that is length prefixed.
      java.lang.String 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, java.lang.Appendable appendable)
      Get an encoded ASCII String from the buffer that does not have a length prefix and append to an Appendable.
      java.lang.String 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​(java.nio.ByteBuffer buffer)
      Attach a view to a ByteBuffer for providing direct access, the ByteBuffer can be heap based or direct.
      void wrap​(java.nio.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 interface java.lang.Comparable

        compareTo
    • Field Detail

      • 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:
        Constant Field Values
      • DISABLE_ARRAY_CONTENT_PRINTOUT_PROP_NAME

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

        static final java.lang.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:
        Constant Field Values
    • Method Detail

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

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

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

        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

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

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

        long getLong​(int index,
                     java.nio.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,
                   java.nio.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,
                         java.nio.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,
                       java.nio.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,
                       java.nio.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,
                     java.nio.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,
                      java.nio.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,
                      java.nio.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

        java.lang.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,
                           java.lang.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

        java.lang.String getStringAscii​(int index,
                                        java.nio.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,
                           java.lang.Appendable appendable,
                           java.nio.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

        java.lang.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,
                           java.lang.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

        java.lang.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,
                                        java.lang.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

        java.lang.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

        java.lang.String getStringUtf8​(int index,
                                       java.nio.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

        java.lang.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

        java.lang.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:
        java.lang.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:
        byteArray(), byteBuffer()