Package io.grpc.internal

Interface ReadableBuffer

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
AbstractReadableBuffer, CompositeReadableBuffer, ForwardingReadableBuffer
public interface ReadableBuffer extends Closeable
Interface for an abstract byte buffer. Buffers are intended to be a read-only, except for the read position which is incremented after each read call.

Buffers may optionally expose a backing array for optimization purposes, similar to what is done in ByteBuffer. It is not expected that callers will attempt to modify the backing array.

  • Method Summary

    Modifier and Type
    Method
    Description
    byte[]
    array()
    Gets the backing array for this buffer.
    int
    arrayOffset()
    Gets the offset in the backing array of the current read position.
    boolean
    byteBufferSupported()
    Indicates whether or not getByteBuffer() operation is supported for this buffer.
    void
    close()
    Closes this buffer and releases any resources.
    ByteBuffer
    getByteBuffer()
    Gets a ByteBuffer that contains some bytes of the content next to be read, or null if this buffer has been exhausted.
    boolean
    hasArray()
    Indicates whether or not this buffer exposes a backing array.
    void
    mark()
    Marks the current position in this buffer.
    boolean
    markSupported()
    Indicates whether or not mark() operation is supported for this buffer.
    int
    readableBytes()
    Gets the current number of readable bytes remaining in this buffer.
    void
    readBytes(byte[] dest, int destOffset, int length)
    Reads length bytes from this buffer and writes them to the destination array.
    ReadableBuffer
    readBytes(int length)
    Reads length bytes from this buffer and returns a new Buffer containing them.
    void
    readBytes(OutputStream dest, int length)
    Reads length bytes from this buffer and writes them to the destination stream.
    void
    readBytes(ByteBuffer dest)
    Reads from this buffer until the destination's position reaches its limit, and increases the read position by the number of the transferred bytes.
    int
    readInt()
    Reads a 4-byte signed integer from this buffer using big-endian byte ordering.
    int
    readUnsignedByte()
    Reads the next unsigned byte from this buffer and increments the read position by 1.
    void
    reset()
    Repositions this buffer to the position at the time mark() was last called on this buffer.
    void
    skipBytes(int length)
    Increments the read position by the given length.
    default void
    touch()
    Note that the current callsite has access to this buffer, or do nothing.

  • Method Details

    • readableBytes

      int readableBytes()
      Gets the current number of readable bytes remaining in this buffer.

    • readUnsignedByte

      int readUnsignedByte()
      Reads the next unsigned byte from this buffer and increments the read position by 1.
      Throws:
      IndexOutOfBoundsException - if required bytes are not readable

    • readInt

      int readInt()
      Reads a 4-byte signed integer from this buffer using big-endian byte ordering. Increments the read position by 4.
      Throws:
      IndexOutOfBoundsException - if required bytes are not readable

    • skipBytes

      void skipBytes(int length)
      Increments the read position by the given length.
      Throws:
      IndexOutOfBoundsException - if required bytes are not readable

    • readBytes

      void readBytes(byte[] dest, int destOffset, int length)
      Reads length bytes from this buffer and writes them to the destination array. Increments the read position by length.
      Parameters:
      dest - the destination array to receive the bytes.
      destOffset - the starting offset in the destination array.
      length - the number of bytes to be copied.
      Throws:
      IndexOutOfBoundsException - if required bytes are not readable or dest is too small.

    • readBytes

      void readBytes(ByteBuffer dest)
      Reads from this buffer until the destination's position reaches its limit, and increases the read position by the number of the transferred bytes.
      Parameters:
      dest - the destination buffer to receive the bytes.
      Throws:
      IndexOutOfBoundsException - if required bytes are not readable

    • readBytes

      void readBytes(OutputStream dest, int length) throws IOException
      Reads length bytes from this buffer and writes them to the destination stream. Increments the read position by length. If the required bytes are not readable, throws IndexOutOfBoundsException.
      Parameters:
      dest - the destination stream to receive the bytes.
      length - the number of bytes to be copied.
      Throws:
      IOException - thrown if any error was encountered while writing to the stream.
      IndexOutOfBoundsException - if required bytes are not readable

    • readBytes

      ReadableBuffer readBytes(int length)
      Reads length bytes from this buffer and returns a new Buffer containing them. Some implementations may return a Buffer sharing the backing memory with this buffer to prevent copying. However, that means that the returned buffer may keep the (possibly much larger) backing memory in use even after this buffer is closed.
      Parameters:
      length - the number of bytes to contain in returned Buffer.
      Throws:
      IndexOutOfBoundsException - if required bytes are not readable

    • hasArray

      boolean hasArray()
      Indicates whether or not this buffer exposes a backing array.

    • array

      byte[] array()
      Gets the backing array for this buffer. This is an optional method, so callers should first check hasArray().
      Throws:
      UnsupportedOperationException - the buffer does not support this method

    • arrayOffset

      int arrayOffset()
      Gets the offset in the backing array of the current read position. This is an optional method, so callers should first check hasArray()
      Throws:
      UnsupportedOperationException - the buffer does not support this method

    • touch

      default void touch()
      Note that the current callsite has access to this buffer, or do nothing. This is only useful when the buffer has leak detection and intrumentation to record usages before the buffer was leaked. That can make it much easier to track down where the buffer was leaked. If this isn't such a buffer, the method does nothing.

    • markSupported

      boolean markSupported()
      Indicates whether or not mark() operation is supported for this buffer.

    • mark

      void mark()
      Marks the current position in this buffer. A subsequent call to the reset() method repositions this stream at the last marked position so that subsequent reads re-read the same bytes.

    • reset

      void reset()
      Repositions this buffer to the position at the time mark() was last called on this buffer.

    • byteBufferSupported

      boolean byteBufferSupported()
      Indicates whether or not getByteBuffer() operation is supported for this buffer.

    • getByteBuffer

      @Nullable ByteBuffer getByteBuffer()
      Gets a ByteBuffer that contains some bytes of the content next to be read, or null if this buffer has been exhausted. The number of bytes contained in the returned buffer is implementation specific. The position of this buffer is unchanged after calling this method. The returned buffer's content should not be modified, but the position, limit, and mark may be changed. Operations for changing the position, limit, and mark of the returned buffer does not affect the position, limit, and mark of this buffer. Buffers returned by this method have independent position, limit and mark. This is an optional method, so callers should first check byteBufferSupported().
      Throws:
      UnsupportedOperationException - the buffer does not support this method.

    • close

      void close()
      Closes this buffer and releases any resources.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable