DataBuffer

public interface DataBuffer
Known Indirect Subclasses

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.

Public Methods

abstract <R> R
accept(DataStorageVisitor<R> visitor)
Visits the backing storage of this buffer.
abstract DataBuffer<T>
copyTo(DataBuffer<T> dst, long size)
Write the references of the objects in the source array into this buffer.
abstract boolean
equals(Object obj)
Checks equality between data buffers.
abstract T
getObject(long index)
Reads the value at the given index.
abstract boolean
isReadOnly()
Tells whether or not this buffer is backed by an accessible array.
abstract 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.
abstract 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.
abstract DataBuffer<T>
read(T[] dst)
Read the references of the objects in this buffer into the destination array.
abstract DataBuffer<T>
read(T[] dst, int offset, int length)
Read the references of the objects in this buffer into the destination array.
abstract DataBuffer<T>
setObject(T value, long index)
Writes the given value into this buffer at the given index.
abstract long
size()
Size of the buffer, in elements.
abstract 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.
abstract DataBufferWindow<? extends DataBuffer<T>>
window(long size)
Creates a DataBufferWindow that provides a partial view of this buffer.
abstract DataBuffer<T>
write(T[] src)
Write the references of the objects in the source array into this buffer.
abstract DataBuffer<T>
write(T[] src, int offset, int length)
Bulk put method, using int arrays.

Public Methods

public abstract 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 fallback() so the visitor can execute some generic routine if needed.

Parameters
visitor visits the data storage of this buffer
Returns
  • the same value returned by the visitor

public abstract 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

public abstract 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.

Parameters
obj object to compare this buffer with
Returns
  • true if this buffer is equal to the provided object

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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