Interface DataBuffer<T>

Type Parameters:
T - type of data stored in this buffer
All Known Subinterfaces:
BooleanDataBuffer, ByteDataBuffer, DoubleDataBuffer, FloatDataBuffer, IntDataBuffer, LongDataBuffer, ShortDataBuffer
All Known Implementing Classes:
AbstractDataBuffer
public interface DataBuffer<T>
A container of data of a specific type.

Instances of DataBuffer map native or heap memory segments to a linear view that supports:

  • 64-bits indexing, allowing to work with buffer larger than 231 bytes
  • Storage of object of any types and not only primitives
  • Generic types allows to work directly with boxed types as well, which does not require explicit buffer types as with the standard JDK buffers.
It is important to note that there is no guarantee the memory managed by a DataBuffer is linear, specially when dealing with non-primitive types or large buffers.

  • Method Summary

    Modifier and Type
    Method
    Description
    default <R> R
    accept(DataStorageVisitor<R> visitor)
    Visits the backing storage of this buffer.
    DataBuffer<T>
    copyTo(DataBuffer<T> dst, long size)
    Write the references of the objects in the source array into this buffer.
    boolean
    equals(Object obj)
    Checks equality between data buffers.
    T
    getObject(long index)
    Reads the value at the given index.
    boolean
    isReadOnly()
    Tells whether or not this buffer is backed by an accessible array.
    default DataBuffer<T>
    narrow(long size)
    Creates a new buffer whose content is a shared subsequence of this buffer's content, whose size is set to the given value.
    default DataBuffer<T>
    offset(long index)
    Creates a new buffer whose content is a shared subsequence of this buffer's content, starting at the given index.
    default DataBuffer<T>
    read(T[] dst)
    Read the references of the objects in this buffer into the destination array.
    DataBuffer<T>
    read(T[] dst, int offset, int length)
    Read the references of the objects in this buffer into the destination array.
    DataBuffer<T>
    setObject(T value, long index)
    Writes the given value into this buffer at the given index.
    long
    size()
    Size of the buffer, in elements.
    DataBuffer<T>
    slice(long index, long size)
    Creates a new buffer whose content is a shared subsequence of this buffer's content, starting at the given index and of the given size.
    default DataBufferWindow<? extends DataBuffer<T>>
    window(long size)
    Creates a DataBufferWindow that provides a partial view of this buffer.
    default DataBuffer<T>
    write(T[] src)
    Write the references of the objects in the source array into this buffer.
    DataBuffer<T>
    write(T[] src, int offset, int length)
    Bulk put method, using int arrays.

  • Method Details

    • size

      long size()
      Size of the buffer, in elements.

      For exemple, in case of a byte buffer, this value is equal to the number of bytes this buffer can hold. For an integer buffer, it is equal to the number of integers, therefore the size in bytes of this buffer is size() * Integer.BYTES.

      Returns:
      the buffer size

    • isReadOnly

      boolean isReadOnly()
      Tells whether or not this buffer is backed by an accessible array.
      Returns:
      true if, and only if, this buffer is read-only

    • getObject

      T getObject(long index)
      Reads the value at the given index. Important: Usage of this method should be limited to buffers of non-primitive types or when the data type is not deterministically known by the caller. In any other case, prefer the usage of its primitive variant which will significantly improve performances (e.g. IntDataBuffer.getInt(idx)
      Parameters:
      index - the index from which the float will be read
      Returns:
      the value at the given index
      Throws:
      IndexOutOfBoundsException - if index is negative or not smaller than the buffer size

    • setObject

      DataBuffer<T> setObject(T value, long index)
      Writes the given value into this buffer at the given index. Important: Usage of this method should be limited to buffers of non-primitive types or when the data type is not deterministically known by the caller. In any other case, prefer the usage of its primitive variant which will significantly improve performances (e.g. IntDataBuffer.setInt(idx)
      Parameters:
      value - the value to be written
      index - the index at which the value will be written
      Returns:
      this buffer
      Throws:
      IndexOutOfBoundsException - if index is negative or not smaller than the buffer size
      ReadOnlyBufferException - if this buffer is read-only

    • read

      default DataBuffer<T> read(T[] dst)
      Read the references of the objects in this buffer into the destination array.

      This method transfers values from this buffer into the given destination array. If there are fewer values in the buffer than are required to satisfy the request, that is, if dst.length > size(), then no values are transferred and a BufferUnderflowException is thrown.

      Otherwise, this method copies n = dst.length values from this buffer into the given array.

      Parameters:
      dst - the array into which values are to be written
      Returns:
      this buffer
      Throws:
      BufferUnderflowException - if there are not enough values to copy from this buffer

    • read

      DataBuffer<T> read(T[] dst, int offset, int length)
      Read the references of the objects in this buffer into the destination array.

      This method transfers values from this buffer into the given destination array. If there are fewer values in the buffer than are required to satisfy the request, that is, if length > size(), then no values are transferred and a BufferUnderflowException is thrown.

      Otherwise, this method copies n = length values from this buffer into the given array starting at the given offset.

      Parameters:
      dst - the array into which values are to be written
      offset - the offset within the array of the first value to be written; must be non-negative and no larger than dst.length
      length - the maximum number of values to be written to the given array; must be non-negative and no larger than dst.length - offset
      Returns:
      this buffer
      Throws:
      BufferUnderflowException - if there are fewer than length values remaining in this buffer
      IndexOutOfBoundsException - if the preconditions on the offset and length parameters do not hold

    • write

      default DataBuffer<T> write(T[] src)
      Write the references of the objects in the source array into this buffer.

      This method transfers the values in the given source array into this buffer. If there are more values in the source array than in this buffer, that is, if src.length > size(), then no values are transferred and a BufferOverflowException is thrown.

      Otherwise, this method copies n = src.length values from the given array.

      Parameters:
      src - the source array from which values are to be read
      Returns:
      this buffer
      Throws:
      BufferOverflowException - if there is insufficient space in this buffer for the values in the source array
      ReadOnlyBufferException - if this buffer is read-only

    • write

      DataBuffer<T> write(T[] src, int offset, int length)
      Bulk put method, using int arrays.

      This method transfers the values in the given source array into this buffer. If there are more values in the source array than in this buffer, that is, if length > size(), then no values are transferred and a BufferOverflowException is thrown.

      Otherwise, this method copies n = length values from the given array into this buffer, starting at the given offset.

      Parameters:
      src - the source array from which values are to be read
      offset - the offset within the array of the first value to be read; must be non-negative and no larger than src.length
      length - the number of values to be read from the given array; must be non-negative and no larger than src.length - offset
      Returns:
      this buffer
      Throws:
      BufferOverflowException - if there is insufficient space in this buffer for the values in the source array
      IndexOutOfBoundsException - if the preconditions on the offset and length parameters do not hold
      ReadOnlyBufferException - if this buffer is read-only

    • copyTo

      DataBuffer<T> copyTo(DataBuffer<T> dst, long size)
      Write the references of the objects in the source array into this buffer.

      If there are more values to copy than the destination buffer size, i.e. size > dst.size(), then no values are transferred and a BufferOverflowException is thrown. On the other hand, if there are more values to copy that the source buffer size, i.e. > src.size(), then a BufferUnderfloatException is thrown.

      Otherwise, this method copies n = size values from this buffer into the destination buffer.

      Parameters:
      dst - the destination buffer into which values are copied; must not be this buffer
      size - number of values to copy to the destination buffer
      Returns:
      this buffer
      Throws:
      IllegalArgumentException - if the destination buffer is this buffer
      ReadOnlyBufferException - if the destination buffer is read-only
      BufferOverflowException - if there is not enough space in destination buffer
      BufferUnderflowException - if there are not enough values in the source buffer

    • offset

      default DataBuffer<T> offset(long index)
      Creates a new buffer whose content is a shared subsequence of this buffer's content, starting at the given index.

      The index must not be greater than this buffer size. Changes to this buffer's content will be visible in the new buffer and vice versa. The new buffer will be read-only if, and only if, this buffer is read-only.

      This call is equivalent to slice(index, size() - index)

      Parameters:
      index - index of the first value of the new buffer created, must not be greater than size()
      Returns:
      the new buffer
      Throws:
      IllegalArgumentException - if index do not pass validation checks

    • narrow

      default DataBuffer<T> narrow(long size)
      Creates a new buffer whose content is a shared subsequence of this buffer's content, whose size is set to the given value.

      The new size must not be greater than this buffer size. Changes to this buffer's content will be visible in the new buffer and vice versa. The new buffer will be read-only if, and only if, this buffer is read-only.

      This call is equivalent to slice(0, size)

      Parameters:
      size - size of this new buffer
      Returns:
      the new buffer
      Throws:
      IllegalArgumentException - if index and/or size values do not pass validation checks

    • slice

      DataBuffer<T> slice(long index, long size)
      Creates a new buffer whose content is a shared subsequence of this buffer's content, starting at the given index and of the given size.

      The index plus the new size must not be greater than this buffer size. Changes to this buffer's content will be visible in the new buffer and vice versa. The new buffer will be read-only if, and only if, this buffer is read-only.

      Parameters:
      index - index of the first value of the new buffer created
      size - size of this new buffer, must not be greater than size()
      Returns:
      the new buffer
      Throws:
      IllegalArgumentException - if size value do not pass validation checks

    • window

      default DataBufferWindow<? extends DataBuffer<T>> window(long size)
      Creates a DataBufferWindow that provides a partial view of this buffer.

      The created window has a fixed size and can "slide" along this buffer to provide different views of the data without allocating a new buffer instance, like offset(long) does. This improves overall performance when this operation is repeated frequently. For example: 

      IntDataBuffer bufferA = DataBuffers.ofInts(1024);
// ... init buffer data
IntDataBuffer bufferB = DataBuffers.ofInts(1, 2, 3, 4);

// Return the index of the first occurrence of bufferB in bufferA using a sliding window
DataBufferWindow<IntDataBuffer> windowA = bufferA.window(4);
for (int i = 0; i < bufferA.size() - bufferB.size(); ++i) {
    if (windowA.slideTo(i).buffer().equals(bufferB)) {
        return i;
    }
}

      The returned object is stateful and is not thread-safe.

      Parameters:
      size - size of the window
      Returns:
      a new window that starts at the index 0 of this buffer
      Throws:
      UnsupportedOperationException - if this type of buffer does not support buffer windows

    • accept

      default <R> R accept(DataStorageVisitor<R> visitor)
      Visits the backing storage of this buffer.

      The buffer implementation is responsible of passing back a reference to the actual data storage to the provided visitor. The visitor does not have to handle all possible types of data storage and can override only methods for storage it is actually interested in. For any other type of storage, this call will fallback to DataStorageVisitor.fallback() so the visitor can execute some generic routine if needed.

      Type Parameters:
      R - type of value returned by the visitor
      Parameters:
      visitor - visits the data storage of this buffer
      Returns:
      the same value returned by the visitor

    • equals

      boolean equals(Object obj)
      Checks equality between data buffers.

      A data buffer is equal to another object if this object is another DataBuffer of the same size, type and the elements are equal and in the same order. For example: 

      IntDataBuffer buffer = DataBuffers.of(1, 2, 3);

assertEquals(buffer, DataBuffers.of(1, 2, 3));  // true
assertEquals(buffer, DataBuffers.ofObjects(1, 2, 3));  // true, as Integers are equal to ints
assertNotEquals(buffer, DataBuffers.of(1, 2, 3, 0));  // false, different sizes
assertNotEquals(buffer, DataBuffers.of(1, 3, 2));  // false, different order
assertNotEquals(buffer, DataBuffers.of(1L, 2L, 3L));  // false, different types

      Note that the computation required to verify equality between two buffers can be expensive in some cases and therefore, it is recommended to not use this method in a critical path where performances matter.

      Overrides:
      equals in class Object
      Parameters:
      obj - object to compare this buffer with
      Returns:
      true if this buffer is equal to the provided object