ReadableBuffer (Qpid Proton-J API)

All Known Implementing Classes:

CompositeReadableBuffer, ReadableBuffer.ByteBufferReader
```
public interface ReadableBuffer
```
Interface to abstract a buffer, similar to WritableBuffer

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class ReadableBuffer.ByteBufferReader

Nested Classes
Modifier and Type	Interface and Description
`static class`	`ReadableBuffer.ByteBufferReader`

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`byte[]`	`array()` Returns the primitive array that backs this buffer if one exists and the buffer is not read-only.
`int`	`arrayOffset()` Returns the offset into the backing array of the first element in the buffer.
`java.nio.ByteBuffer`	`byteBuffer()`
`int`	`capacity()` Returns the capacity of the backing buffer of this ReadableBuffer
`ReadableBuffer`	`clear()` Resets the buffer position to zero and sets the limit to the buffer capacity, the mark value is discarded if set.
`ReadableBuffer`	`duplicate()` Creates a duplicate `ReadableBuffer` to this instance.
`ReadableBuffer`	`flip()` Sets the buffer limit to the current position and the position is set to zero, the mark value reset to undefined.
`byte`	`get()` Reads the byte at the current position and advances the position by 1.
`ReadableBuffer`	`get(byte[] target)` A bulk read method that copies bytes from this buffer into the target byte array.
`ReadableBuffer`	`get(byte[] target, int offset, int length)` A bulk read method that copies bytes from this buffer into the target byte array.
`byte`	`get(int index)` Reads the byte at the given index, the buffer position is not affected.
`ReadableBuffer`	`get(WritableBuffer target)` Copy data from this buffer to the target buffer starting from the current position and continuing until either this buffer's remaining bytes are consumed or the target is full.
`double`	`getDouble()` Reads eight bytes from the buffer and returns them as an double value.
`float`	`getFloat()` Reads four bytes from the buffer and returns them as an float value.
`int`	`getInt()` Reads four bytes from the buffer and returns them as an integer value.
`long`	`getLong()` Reads eight bytes from the buffer and returns them as an long value.
`short`	`getShort()` Reads two bytes from the buffer and returns them as an short value.
`boolean`	`hasArray()` Returns true if this ReadableBuffer is backed by an array which can be accessed by the `array()` and `arrayOffset()` methods.
`boolean`	`hasRemaining()`
`int`	`limit()`
`ReadableBuffer`	`limit(int limit)` Sets the current read limit of this buffer to the given value.
`ReadableBuffer`	`mark()` Mark the current position of this buffer which can be returned to after a read operation by calling `reset()`.
`int`	`position()`
`ReadableBuffer`	`position(int position)` Sets the current position of this buffer to the given value.
`java.lang.String`	`readString(java.nio.charset.CharsetDecoder decoder)` Decodes a String from the buffer using the provided `CharsetDecoder` starting the decode at the current position and reading until the limit is reached.
`java.lang.String`	`readUTF8()` Reads a UTF-8 encoded String from the buffer starting the decode at the current position and reading until the limit is reached.
`ReadableBuffer`	`reclaimRead()` Compact the backing storage of this ReadableBuffer, possibly freeing previously-read portions of pooled data or reducing the number of backing arrays if present.
`int`	`remaining()`
`ReadableBuffer`	`reset()` Reset the buffer's position to a previously marked value, the mark should remain set after calling this method.
`ReadableBuffer`	`rewind()` Resets the buffer position to zero and clears and previously set mark.
`ReadableBuffer`	`slice()` Creates a new ReadableBuffer instance that is a view of the readable portion of this buffer.

- Method Detail
  - capacity
```
int capacity()
```
    Returns the capacity of the backing buffer of this ReadableBuffer
    
    Returns:
    
    the capacity of the backing buffer of this ReadableBuffer
  - hasArray
```
boolean hasArray()
```
    Returns true if this ReadableBuffer is backed by an array which can be accessed by the array() and arrayOffset() methods.
    
    Returns:
    
    true if the buffer is backed by a primitive array.
  - array
```
byte[] array()
```
    Returns the primitive array that backs this buffer if one exists and the buffer is not read-only. The caller should have checked the hasArray() method before calling this method.
    
    Returns:
    
    the array that backs this buffer is available.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this ReadableBuffer doesn't support array access.
    
    java.nio.ReadOnlyBufferException - if the ReadableBuffer is read-only.
  - arrayOffset
```
int arrayOffset()
```
    Returns the offset into the backing array of the first element in the buffer. The caller should have checked the hasArray() method before calling this method.
    
    Returns:
    
    the offset into the backing array of the first element in the buffer.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this ReadableBuffer doesn't support array access.
    
    java.nio.ReadOnlyBufferException - if the ReadableBuffer is read-only.
  - reclaimRead
```
ReadableBuffer reclaimRead()
```
    Compact the backing storage of this ReadableBuffer, possibly freeing previously-read portions of pooled data or reducing the number of backing arrays if present.
    This is an optional operation and care should be taken in its implementation.
    
    Returns:
    
    a reference to this buffer
  - get
```
byte get()
```
    Reads the byte at the current position and advances the position by 1.
    
    Returns:
    
    the byte at the current position.
    
    Throws:
    
    java.nio.BufferUnderflowException - if the buffer position has reached the limit.
  - get
```
byte get(int index)
```
    Reads the byte at the given index, the buffer position is not affected.
    
    Parameters:
    
    index - The index in the buffer from which to read the byte.
    
    Returns:
    
    the byte value stored at the target index.
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if the index is not in range for this buffer.
  - getInt
```
int getInt()
```
    Reads four bytes from the buffer and returns them as an integer value. The buffer position is advanced by four byes.
    
    Returns:
    
    and integer value composed of bytes read from the buffer.
    
    Throws:
    
    java.nio.BufferUnderflowException - if the buffer position has reached the limit.
  - getLong
```
long getLong()
```
    Reads eight bytes from the buffer and returns them as an long value. The buffer position is advanced by eight byes.
    
    Returns:
    
    and long value composed of bytes read from the buffer.
    
    Throws:
    
    java.nio.BufferUnderflowException - if the buffer position has reached the limit.
  - getShort
```
short getShort()
```
    Reads two bytes from the buffer and returns them as an short value. The buffer position is advanced by two byes.
    
    Returns:
    
    and short value composed of bytes read from the buffer.
    
    Throws:
    
    java.nio.BufferUnderflowException - if the buffer position has reached the limit.
  - getFloat
```
float getFloat()
```
    Reads four bytes from the buffer and returns them as an float value. The buffer position is advanced by four byes.
    
    Returns:
    
    and float value composed of bytes read from the buffer.
    
    Throws:
    
    java.nio.BufferUnderflowException - if the buffer position has reached the limit.
  - getDouble
```
double getDouble()
```
    Reads eight bytes from the buffer and returns them as an double value. The buffer position is advanced by eight byes.
    
    Returns:
    
    and double value composed of bytes read from the buffer.
    
    Throws:
    
    java.nio.BufferUnderflowException - if the buffer position has reached the limit.
  - get
```
ReadableBuffer get(byte[] target,
                   int offset,
                   int length)
```
    A bulk read method that copies bytes from this buffer into the target byte array.
    
    Parameters:
    
    target - The byte array to copy bytes read from this buffer.
    
    offset - The offset into the given array where the copy starts.
    
    length - The number of bytes to copy into the target array.
    
    Returns:
    
    a reference to this ReadableBuffer instance.
    
    Throws:
    
    java.nio.BufferUnderflowException - if the are less readable bytes than the array length.
    
    java.lang.IndexOutOfBoundsException - if the offset or length values are invalid.
  - get
```
ReadableBuffer get(byte[] target)
```
    A bulk read method that copies bytes from this buffer into the target byte array.
    
    Parameters:
    
    target - The byte array to copy bytes read from this buffer.
    
    Returns:
    
    a reference to this ReadableBuffer instance.
    
    Throws:
    
    java.nio.BufferUnderflowException - if the are less readable bytes than the array length.
  - get
```
ReadableBuffer get(WritableBuffer target)
```
    Copy data from this buffer to the target buffer starting from the current position and continuing until either this buffer's remaining bytes are consumed or the target is full.
    
    Parameters:
    
    target - The WritableBuffer to transfer this buffer's data to.
    
    Returns:
    
    a reference to this ReadableBuffer instance.
  - slice
```
ReadableBuffer slice()
```
    Creates a new ReadableBuffer instance that is a view of the readable portion of this buffer. The position will be set to zero and the limit and the reported capacity will match the value returned by this buffer's remaining() method, the mark will be undefined.
    
    Returns:
    
    a new ReadableBuffer that is a view of the readable portion of this buffer.
  - flip
```
ReadableBuffer flip()
```
    Sets the buffer limit to the current position and the position is set to zero, the mark value reset to undefined.
    
    Returns:
    
    a reference to this ReadableBuffer.
  - limit
```
ReadableBuffer limit(int limit)
```
    Sets the current read limit of this buffer to the given value. If the buffer mark value is defined and is larger than the limit the mark will be discarded. If the position is larger than the new limit it will be reset to the new limit.
    
    Parameters:
    
    limit - The new read limit to set for this buffer.
    
    Returns:
    
    a reference to this ReadableBuffer.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the limit value is negative or greater than the capacity.
  - limit
```
int limit()
```
    Returns:
    
    the current value of this buffer's limit.
  - position
```
ReadableBuffer position(int position)
```
    Sets the current position of this buffer to the given value. If the buffer mark value is defined and is larger than the newly set position is must be discarded.
    
    Parameters:
    
    position - The new position to set for this buffer.
    
    Returns:
    
    a reference to this ReadableBuffer.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the position value is negative or greater than the limit.
  - position
```
int position()
```
    Returns:
    
    the current position from which the next read operation will start.
  - mark
```
ReadableBuffer mark()
```
    Mark the current position of this buffer which can be returned to after a read operation by calling reset().
    
    Returns:
    
    a reference to this ReadableBuffer.
  - reset
```
ReadableBuffer reset()
```
    Reset the buffer's position to a previously marked value, the mark should remain set after calling this method.
    
    Returns:
    
    a reference to this ReadableBuffer.
    
    Throws:
    
    java.nio.InvalidMarkException - if the mark value is undefined.
  - rewind
```
ReadableBuffer rewind()
```
    Resets the buffer position to zero and clears and previously set mark.
    
    Returns:
    
    a reference to this ReadableBuffer.
  - clear
```
ReadableBuffer clear()
```
    Resets the buffer position to zero and sets the limit to the buffer capacity, the mark value is discarded if set.
    
    Returns:
    
    a reference to this ReadableBuffer.
  - remaining
```
int remaining()
```
    Returns:
    
    the remaining number of readable bytes in this buffer.
  - hasRemaining
```
boolean hasRemaining()
```
    Returns:
    
    true if there are readable bytes still remaining in this buffer.
  - duplicate
```
ReadableBuffer duplicate()
```
    Creates a duplicate ReadableBuffer to this instance.
    The duplicated buffer will have the same position, limit and mark as this buffer. The two buffers share the same backing data.
    
    Returns:
    
    a duplicate of this ReadableBuffer.
  - byteBuffer
```
java.nio.ByteBuffer byteBuffer()
```
    Returns:
    
    a ByteBuffer view of the current readable portion of this buffer.
  - readUTF8
```
java.lang.String readUTF8()
                   throws java.nio.charset.CharacterCodingException
```
    Reads a UTF-8 encoded String from the buffer starting the decode at the current position and reading until the limit is reached. The position is advanced to the limit once this method returns. If there is no bytes remaining in the buffer when this method is called a null is returned.
    
    Returns:
    
    a string decoded from the remaining bytes in this buffer.
    
    Throws:
    
    java.nio.charset.CharacterCodingException - if the encoding is invalid for any reason.
  - readString
```
java.lang.String readString(java.nio.charset.CharsetDecoder decoder)
                     throws java.nio.charset.CharacterCodingException
```
    Decodes a String from the buffer using the provided CharsetDecoder starting the decode at the current position and reading until the limit is reached. The position is advanced to the limit once this method returns. If there is no bytes remaining in the buffer when this method is called a null is returned.
    
    Returns:
    
    a string decoded from the remaining bytes in this buffer.
    
    Throws:
    
    java.nio.charset.CharacterCodingException - if the encoding is invalid for any reason.

Interface ReadableBuffer

Nested Class Summary

Method Summary

Method Detail

capacity

hasArray

array

arrayOffset

reclaimRead

get

get

getInt

getLong

getShort

getFloat

getDouble

get

get

get

slice

flip

limit

limit

position

position

mark

reset

rewind

clear

remaining

hasRemaining

duplicate

byteBuffer

readUTF8

readString