Package org.springframework.core.io.buffer

# Interface DataBuffer

All Known Subinterfaces:
  `CloseableDataBuffer`, `PooledDataBuffer`, `TouchableDataBuffer`

All Known Implementing Classes:
  `DataBufferWrapper`, `DefaultDataBuffer`, `JettyDataBuffer`, `Netty5DataBuffer`, `NettyDataBuffer`

public interface DataBuffer
Basic abstraction over byte buffers.

`DataBuffer`s has a separate read and write position, as opposed to `ByteBuffer`'s single position. As such, the `DataBuffer` does not require a flip to read after writing. In general, the following invariant holds for the read and write positions, and the capacity:

> `0` `<=` readPosition `<=` writePosition `<=` capacity

The capacity of a `DataBuffer` is expanded on demand, similar to `StringBuilder`.

The main purpose of the `DataBuffer` abstraction is to provide a convenient wrapper around `ByteBuffer` which is similar to Netty's `ByteBuf` but can also be used on non-Netty platforms (i.e. Servlet containers).

Since:
  5.0
Author:
  Arjen Poutsma, Brian Clozel
See Also:
  - `DataBufferFactory`

## Nested Class Summary

Nested Classes
Modifier and Type
Interface
Description
`static interface`
`DataBuffer.ByteBufferIterator`
A dedicated iterator type that ensures the lifecycle of iterated `ByteBuffer` elements.
`static interface`
`DataBuffer.ByteProcessor`
Process a range of bytes one by one.

## Method Summary

Modifier and Type
Method
Description
`ByteBuffer`
`asByteBuffer()`
Deprecated.
as of 6.0, in favor of `toByteBuffer(ByteBuffer)`, `readableByteBuffers()` or `writableByteBuffers()`
`ByteBuffer`
`asByteBuffer(int index, int length)`
Deprecated.
as of 6.0, in favor of `toByteBuffer(int, ByteBuffer, int, int)`, `readableByteBuffers()` or `writableByteBuffers()`
`default InputStream`
`asInputStream()`
Expose this buffer's data as an `InputStream`.
`default InputStream`
`asInputStream(boolean releaseOnClose)`
Expose this buffer's data as an `InputStream`.
`default OutputStream`
`asOutputStream()`
Expose this buffer's data as an `OutputStream`.
`int`
`capacity()`
Return the number of bytes that this buffer can contain.
`DataBuffer`
`capacity(int capacity)`
Deprecated.
as of 6.0, in favor of `ensureWritable(int)` which has different semantics
`default DataBuffer`
`ensureCapacity(int capacity)`
Deprecated.
since 6.0, in favor of `ensureWritable(int)`
`DataBuffer`
`ensureWritable(int capacity)`
Ensure that the current buffer has enough `writableByteCount()` to write the amount of data given as an argument.
`DataBufferFactory`
`factory()`
Return the `DataBufferFactory` that created this buffer.
`default int`
`forEachByte(int index, int length, DataBuffer.ByteProcessor processor)`
Process a range of bytes from the current buffer using a `DataBuffer.ByteProcessor`.
`byte`
`getByte(int index)`
Read a single byte at the given index from this data buffer.
`int`
`indexOf(IntPredicate predicate, int fromIndex)`
Return the index of the first byte in this buffer that matches the given predicate.
`int`
`lastIndexOf(IntPredicate predicate, int fromIndex)`
Return the index of the last byte in this buffer that matches the given predicate.
`byte`
`read()`
Read a single byte from the current reading position from this data buffer.
`DataBuffer`
`read(byte[] destination)`
Read this buffer's data into the specified destination, starting at the current reading position of this buffer.
`DataBuffer`
`read(byte[] destination, int offset, int length)`
Read at most `length` bytes of this buffer into the specified destination, starting at the current reading position of this buffer.
`DataBuffer.ByteBufferIterator`
`readableByteBuffers()`
Returns a closeable iterator over each `ByteBuffer` in this data buffer that can be read.
`int`
`readableByteCount()`
Return the number of bytes that can be read from this data buffer.
`int`
`readPosition()`
Return the position from which this buffer will read.
`DataBuffer`
`readPosition(int readPosition)`
Set the position from which this buffer will read.
`default DataBuffer`
`retainedSlice(int index, int length)`
Deprecated.
as of 6.0, in favor of `split(int)` which has different semantics
`DataBuffer`
`slice(int index, int length)`
Deprecated.
as of 6.0, in favor of `split(int)` which has different semantics
`DataBuffer`
`split(int index)`
Splits this data buffer into two at the given index.
`default ByteBuffer`
`toByteBuffer()`
Deprecated.
as of 6.0.5, in favor of `toByteBuffer(ByteBuffer)`
`ByteBuffer`
`toByteBuffer(int index, int length)`
Deprecated.
as of 6.0.5, in favor of `toByteBuffer(int, ByteBuffer, int, int)`
`void`
`toByteBuffer(int srcPos, ByteBuffer dest, int destPos, int length)`
Copies the given length from this data buffer into the given destination `ByteBuffer`, beginning at the given source position, and the given destination position in the destination byte buffer.
`default void`
`toByteBuffer(ByteBuffer dest)`
Copies this entire data buffer into the given destination `ByteBuffer`, beginning at the current reading position, and the current position of destination byte buffer.
`String`
`toString(int index, int length, Charset charset)`
Return a part of this buffer's data as a String using the specified charset.
`default String`
`toString(Charset charset)`
Return this buffer's data a String using the specified charset.
`DataBuffer.ByteBufferIterator`
`writableByteBuffers()`
Returns a closeable iterator over each `ByteBuffer` in this data buffer that can be written to.
`int`
`writableByteCount()`
Return the number of bytes that can be written to this data buffer.
`DataBuffer`
`write(byte b)`
Write a single byte into this buffer at the current writing position.
`DataBuffer`
`write(byte[] source)`
Write the given source into this buffer, starting at the current writing position of this buffer.
`DataBuffer`
`write(byte[] source, int offset, int length)`
Write at most `length` bytes of the given source into this buffer, starting at the current writing position of this buffer.
`default DataBuffer`
`write(CharSequence charSequence, Charset charset)`
Write the given `CharSequence` using the given `Charset`, starting at the current writing position.
`DataBuffer`
`write(ByteBuffer... buffers)`
Write one or more `ByteBuffer` to this buffer, starting at the current writing position.
`DataBuffer`
`write(DataBuffer... buffers)`
Write one or more `DataBuffer`s to this buffer, starting at the current writing position.
`int`
`writePosition()`
Return the position to which this buffer will write.
`DataBuffer`
`writePosition(int writePosition)`
Set the position to which this buffer will write.

## Method Details

### factory

DataBufferFactory factory()
Return the `DataBufferFactory` that created this buffer.

Returns:
  the creating buffer factory

### indexOf

int indexOf(IntPredicate predicate, int fromIndex)
Return the index of the first byte in this buffer that matches the given predicate.

Parameters:
  `predicate` - the predicate to match
  `fromIndex` - the index to start the search from
Returns:
  the index of the first byte that matches `predicate`; or `-1` if none match

### lastIndexOf

int lastIndexOf(IntPredicate predicate, int fromIndex)
Return the index of the last byte in this buffer that matches the given predicate.

Parameters:
  `predicate` - the predicate to match
  `fromIndex` - the index to start the search from
Returns:
  the index of the last byte that matches `predicate`; or `-1` if none match

### readableByteCount

int readableByteCount()
Return the number of bytes that can be read from this data buffer.

Returns:
  the readable byte count

### writableByteCount

int writableByteCount()
Return the number of bytes that can be written to this data buffer.

Returns:
  the writable byte count
Since:
  5.0.1

### capacity

int capacity()
Return the number of bytes that this buffer can contain.

Returns:
  the capacity
Since:
  5.0.1

### capacity

@Deprecated(since="6.0") DataBuffer capacity(int capacity)
Deprecated.
as of 6.0, in favor of `ensureWritable(int)` which has different semantics
Set the number of bytes that this buffer can contain.

If the new capacity is lower than the current capacity, the contents of this buffer will be truncated. If the new capacity is higher than the current capacity, it will be expanded.

Parameters:
  `capacity` - the new capacity
Returns:
  this buffer

### ensureCapacity

@Deprecated(since="6.0") default DataBuffer ensureCapacity(int capacity)
Deprecated.
since 6.0, in favor of `ensureWritable(int)`
Ensure that the current buffer has enough `writableByteCount()` to write the amount of data given as an argument. If not, the missing capacity will be added to the buffer.

Parameters:
  `capacity` - the writable capacity to check for
Returns:
  this buffer
Since:
  5.1.4

### ensureWritable

DataBuffer ensureWritable(int capacity)
Ensure that the current buffer has enough `writableByteCount()` to write the amount of data given as an argument. If not, the missing capacity will be added to the buffer.

Parameters:
  `capacity` - the writable capacity to check for
Returns:
  this buffer
Since:
  6.0

### readPosition

int readPosition()
Return the position from which this buffer will read.

Returns:
  the read position
Since:
  5.0.1

### readPosition

DataBuffer readPosition(int readPosition)
Set the position from which this buffer will read.

Parameters:
  `readPosition` - the new read position
Returns:
  this buffer
Throws:
  `IndexOutOfBoundsException` - if `readPosition` is smaller than 0 or greater than `writePosition()`
Since:
  5.0.1

### writePosition

int writePosition()
Return the position to which this buffer will write.

Returns:
  the write position
Since:
  5.0.1

### writePosition

DataBuffer writePosition(int writePosition)
Set the position to which this buffer will write.

Parameters:
  `writePosition` - the new write position
Returns:
  this buffer
Throws:
  `IndexOutOfBoundsException` - if `writePosition` is smaller than `readPosition()` or greater than `capacity()`
Since:
  5.0.1

### getByte

byte getByte(int index)
Read a single byte at the given index from this data buffer.

Parameters:
  `index` - the index at which the byte will be read
Returns:
  the byte at the given index
Throws:
  `IndexOutOfBoundsException` - when `index` is out of bounds
Since:
  5.0.4

### forEachByte

default int forEachByte(int index, int length, DataBuffer.ByteProcessor processor)
Process a range of bytes from the current buffer using a `DataBuffer.ByteProcessor`.

Parameters:
  `index` - the index at which the processing will start
  `length` - the maximum number of bytes to be processed
  `processor` - the processor that consumes bytes
Returns:
  the position that was reached when processing was stopped, or `-1` if the entire byte range was processed.
Throws:
  `IndexOutOfBoundsException` - when `index` is out of bounds
Since:
  6.2.12

### read

byte read()
Read a single byte from the current reading position from this data buffer.

Returns:
  the byte at this buffer's current reading position

### read

DataBuffer read(byte[] destination)
Read this buffer's data into the specified destination, starting at the current reading position of this buffer.

Parameters:
  `destination` - the array into which the bytes are to be written
Returns:
  this buffer

### read

DataBuffer read(byte[] destination, int offset, int length)
Read at most `length` bytes of this buffer into the specified destination, starting at the current reading position of this buffer.

Parameters:
  `destination` - the array into which the bytes are to be written
  `offset` - the index within `destination` of the first byte to be written
  `length` - the maximum number of bytes to be written in `destination`
Returns:
  this buffer

### write

DataBuffer write(byte b)
Write a single byte into this buffer at the current writing position.

Parameters:
  `b` - the byte to be written
Returns:
  this buffer

### write

DataBuffer write(byte[] source)
Write the given source into this buffer, starting at the current writing position of this buffer.

Parameters:
  `source` - the bytes to be written into this buffer
Returns:
  this buffer

### write

DataBuffer write(byte[] source, int offset, int length)
Write at most `length` bytes of the given source into this buffer, starting at the current writing position of this buffer.

Parameters:
  `source` - the bytes to be written into this buffer
  `offset` - the index within `source` to start writing from
  `length` - the maximum number of bytes to be written from `source`
Returns:
  this buffer

### write

DataBuffer write(DataBuffer... buffers)
Write one or more `DataBuffer`s to this buffer, starting at the current writing position. It is the responsibility of the caller to release the given data buffers.

Parameters:
  `buffers` - the byte buffers to write into this buffer
Returns:
  this buffer

### write

DataBuffer write(ByteBuffer... buffers)
Write one or more `ByteBuffer` to this buffer, starting at the current writing position.

Parameters:
  `buffers` - the byte buffers to write into this buffer
Returns:
  this buffer

### write

default DataBuffer write(CharSequence charSequence, Charset charset)
Write the given `CharSequence` using the given `Charset`, starting at the current writing position.

Parameters:
  `charSequence` - the char sequence to write into this buffer
  `charset` - the charset to encode the char sequence with
Returns:
  this buffer
Since:
  5.1.4

### slice

@Deprecated(since="6.0") DataBuffer slice(int index, int length)
Deprecated.
as of 6.0, in favor of `split(int)` which has different semantics
Create a new `DataBuffer` whose contents is a shared subsequence of this data buffer's content. Data between this data buffer and the returned buffer is shared; though changes in the returned buffer's position will not be reflected in the reading nor writing position of this data buffer.

Note that this method will not call `DataBufferUtils.retain(DataBuffer)` on the resulting slice: the reference count will not be increased.

Parameters:
  `index` - the index at which to start the slice
  `length` - the length of the slice
Returns:
  the specified slice of this data buffer

### retainedSlice

@Deprecated(since="6.0") default DataBuffer retainedSlice(int index, int length)
Deprecated.
as of 6.0, in favor of `split(int)` which has different semantics
Create a new `DataBuffer` whose contents is a shared, retained subsequence of this data buffer's content. Data between this data buffer and the returned buffer is shared; though changes in the returned buffer's position will not be reflected in the reading nor writing position of this data buffer.

Note that unlike `slice(int, int)`, this method will call `DataBufferUtils.retain(DataBuffer)` (or equivalent) on the resulting slice.

Parameters:
  `index` - the index at which to start the slice
  `length` - the length of the slice
Returns:
  the specified, retained slice of this data buffer
Since:
  5.2

### split

DataBuffer split(int index)
Splits this data buffer into two at the given index.

Data that precedes the `index` will be returned in a new buffer, while this buffer will contain data that follows after `index`. Memory between the two buffers is shared, but independent and cannot overlap (unlike `slice`).

The read and write position of the returned buffer are truncated to fit within the buffers capacity if necessary. The positions of this buffer are set to `0` if they are smaller than `index`.

Parameters:
  `index` - the index at which it should be split
Returns:
  a new data buffer, containing the bytes from index `0` to `index`
Since:
  6.0

### asByteBuffer

@Deprecated(since="6.0") ByteBuffer asByteBuffer()
Deprecated.
as of 6.0, in favor of `toByteBuffer(ByteBuffer)`, `readableByteBuffers()` or `writableByteBuffers()`
Expose this buffer's bytes as a `ByteBuffer`. Data between this `DataBuffer` and the returned `ByteBuffer` is shared; though changes in the returned buffer's position will not be reflected in the reading nor writing position of this data buffer.

Returns:
  this data buffer as a byte buffer

### asByteBuffer

@Deprecated(since="6.0") ByteBuffer asByteBuffer(int index, int length)
Deprecated.
as of 6.0, in favor of `toByteBuffer(int, ByteBuffer, int, int)`, `readableByteBuffers()` or `writableByteBuffers()`
Expose a subsequence of this buffer's bytes as a `ByteBuffer`. Data between this `DataBuffer` and the returned `ByteBuffer` is shared; though changes in the returned buffer's position will not be reflected in the reading nor writing position of this data buffer.

Parameters:
  `index` - the index at which to start the byte buffer
  `length` - the length of the returned byte buffer
Returns:
  this data buffer as a byte buffer
Since:
  5.0.1

### toByteBuffer

@Deprecated(since="6.0.5") default ByteBuffer toByteBuffer()
Deprecated.
as of 6.0.5, in favor of `toByteBuffer(ByteBuffer)`
Returns a `ByteBuffer` representation of this data buffer. Data between this `DataBuffer` and the returned `ByteBuffer` is not shared.

Returns:
  this data buffer as a byte buffer
Since:
  6.0
See Also:
  - `readableByteBuffers()`
  - `writableByteBuffers()`

### toByteBuffer

@Deprecated(since="6.0.5") ByteBuffer toByteBuffer(int index, int length)
Deprecated.
as of 6.0.5, in favor of `toByteBuffer(int, ByteBuffer, int, int)`
Returns a `ByteBuffer` representation of a subsequence of this buffer's bytes. Data between this `DataBuffer` and the returned `ByteBuffer` is not shared.

Returns:
  this data buffer as a byte buffer
Since:
  6.0
See Also:
  - `readableByteBuffers()`
  - `writableByteBuffers()`

### toByteBuffer

default void toByteBuffer(ByteBuffer dest)
Copies this entire data buffer into the given destination `ByteBuffer`, beginning at the current reading position, and the current position of destination byte buffer.

Parameters:
  `dest` - the destination byte buffer
Since:
  6.0.5

### toByteBuffer

void toByteBuffer(int srcPos, ByteBuffer dest, int destPos, int length)
Copies the given length from this data buffer into the given destination `ByteBuffer`, beginning at the given source position, and the given destination position in the destination byte buffer.

Parameters:
  `srcPos` - the position of this data buffer from where copying should start
  `dest` - the destination byte buffer
  `destPos` - the position in `dest` to where copying should start
  `length` - the amount of data to copy
Since:
  6.0.5

### readableByteBuffers

DataBuffer.ByteBufferIterator readableByteBuffers()
Returns a closeable iterator over each `ByteBuffer` in this data buffer that can be read. Calling this method is more efficient than `toByteBuffer()`, as no data is copied. However, the byte buffers provided can only be used during the iteration.

Note that the returned iterator must be used in a try-with-resources clause or explicitly closed.

Returns:
  a closeable iterator over the readable byte buffers contained in this data buffer
Since:
  6.0.5

### writableByteBuffers

DataBuffer.ByteBufferIterator writableByteBuffers()
Returns a closeable iterator over each `ByteBuffer` in this data buffer that can be written to. The byte buffers provided can only be used during the iteration.

Note that the returned iterator must be used in a try-with-resources clause or explicitly closed.

Returns:
  a closeable iterator over the writable byte buffers contained in this data buffer
Since:
  6.0.5

### asInputStream

default InputStream asInputStream()
Expose this buffer's data as an `InputStream`. Both data and read position are shared between the returned stream and this data buffer. The underlying buffer will not be released when the input stream is closed.

Returns:
  this data buffer as an input stream
See Also:
  - `asInputStream(boolean)`

### asInputStream

default InputStream asInputStream(boolean releaseOnClose)
Expose this buffer's data as an `InputStream`. Both data and read position are shared between the returned stream and this data buffer.

Parameters:
  `releaseOnClose` - whether the underlying buffer will be released when the input stream is closed.
Returns:
  this data buffer as an input stream
Since:
  5.0.4

### asOutputStream

default OutputStream asOutputStream()
Expose this buffer's data as an `OutputStream`. Both data and write position are shared between the returned stream and this data buffer.

Returns:
  this data buffer as an output stream

### toString

default String toString(Charset charset)
Return this buffer's data a String using the specified charset. Default implementation delegates to `toString(readPosition(), readableByteCount(), charset)`.

Parameters:
  `charset` - the character set to use
Returns:
  a string representation of all this buffers data
Since:
  5.2

### toString

String toString(int index, int length, Charset charset)
Return a part of this buffer's data as a String using the specified charset.

Parameters:
  `index` - the index at which to start the string
  `length` - the number of bytes to use for the string
  `charset` - the charset to use
Returns:
  a string representation of a part of this buffers data
Since:
  5.2