Package org.springframework.core.io.buffer

Interface DataBuffer

All Known Subinterfaces:
CloseableDataBuffer, PooledDataBuffer, TouchableDataBuffer
All Known Implementing Classes:
DataBufferWrapper, DefaultDataBuffer, Netty5DataBuffer, NettyDataBuffer
public interface DataBuffer
Basic abstraction over byte buffers.

DataBuffers 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:

  • 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

    • 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 DataBuffers 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:

    • 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:

    • 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

      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