public class ByteBufferByteSource extends AbstractByteSource
Byte source backed by a list of byte buffers. This byte source allows for accessing a sequence of buffers like they were one contiguous buffer.
Attention: Special care must be taken to ensure that all
byte buffers added to an instance of this class have the same
ByteOrder
. Otherwise the get methods that return multi-byte
data-types might have unexpected results.
The get*Array
methods are optimized to only use one copy
operation for transferring data. An extra copy operation is necessary for
elements that span across two of the backing ByteBuffer
s, however all
other elements are read with only a single copy operation. If the
ByteBuffer
's ByteOrder
is the platforms native byte order,
array reads can be expected to be very efficient, because complete blocks of
memory are copied.
Sub-classes might want to override release(ByteBuffer)
in order to
reuse byte buffers.
Instances of this class are not thread-safe. If multiple threads are going to
access an instance of this class, access to it must be synchronized. This
also applies to simple read operations (without advancing the position)
because under certain conditions the state of the backing ByteBuffer
s
might be changed temporarily.
ByteSource.AtomicGetOperation<T>
SIZE_OF_BYTE, SIZE_OF_DOUBLE, SIZE_OF_FLOAT, SIZE_OF_INT, SIZE_OF_LONG, SIZE_OF_SHORT
Constructor and Description |
---|
ByteBufferByteSource()
Creates a new byte source that initially does not contain any buffers.
|
Modifier and Type | Method and Description |
---|---|
ByteBufferByteSource |
appendBuffer(ByteBuffer buffer)
Appends a byte buffer to the list of available buffers.
|
ByteBufferByteSource |
appendBuffers(ByteBuffer[] buffers)
Appends an array of byte buffers to the list of available buffers.
|
ByteBufferByteSource |
appendBuffers(Iterable<? extends ByteBuffer> buffers)
Appends an array of byte buffers to the list of available buffers.
|
<T> T |
atomicGet(ByteSource.AtomicGetOperation<T> atomicGetOperation)
Starts an atomic get operation.
|
ByteBufferByteSource |
getByteArray(byte[] destination,
int offset,
int length)
Reads the specified number of bytes into the supplied array and advances
the current position.
|
ByteBufferByteSource |
getDoubleArray(double[] destination,
int offset,
int length)
Reads the specified number of double values into the supplied array and
advances the current position.
|
ByteBufferByteSource |
getFloatArray(float[] destination,
int offset,
int length)
Reads the specified number of float values into the supplied array and
advances the current position.
|
ByteBufferByteSource |
getIntArray(int[] destination,
int offset,
int length)
Reads the specified number of int values into the supplied array and
advances the current position.
|
ByteBufferByteSource |
getLongArray(long[] destination,
int offset,
int length)
Reads the specified number of long values into the supplied array and
advances the current position.
|
ByteBufferByteSource |
getShortArray(short[] destination,
int offset,
int length)
Reads the specified number of short values into the supplied array and
advances the current position.
|
protected void |
release(ByteBuffer buffer)
Called every time a byte buffer is released (removed from the list of
remaining buffers).
|
int |
remaining()
Returns the number of bytes remaining in this source.
|
ByteBuffer |
removeLastBuffer()
Removes and returns the last buffer in the queue of byte buffers backing
this byte source.
|
ByteBufferByteSource |
skip(int length)
Skips the specified number of bytes.
|
getByte, getByteArray, getDouble, getDoubleArray, getFloat, getFloatArray, getInt, getIntArray, getLong, getLongArray, getShort, getShortArray, toString
public ByteBufferByteSource()
BufferUnderflowException
until at least one usable buffer is
appended to this source.protected void release(ByteBuffer buffer)
buffer
- buffer that has been removed and can be released.public ByteBufferByteSource appendBuffer(ByteBuffer buffer)
buffer
.buffer
- buffer to be appended to the internal list of buffers.this
object.IllegalStateException
- if adding the buffer would push the number of remaining bytes
in this byte source above Long.MAX_VALUE
.public ByteBufferByteSource appendBuffers(ByteBuffer[] buffers)
buffers
.buffers
- buffers to be appended to the internal list of buffers.this
object.IllegalStateException
- if adding the buffers would push the number of remaining
bytes in this byte source above Integer.MAX_VALUE
.
None of the buffers are added in this case.public ByteBufferByteSource appendBuffers(Iterable<? extends ByteBuffer> buffers)
buffers
.buffers
- buffers to be appended to the internal list of buffers.this
object.IllegalStateException
- if adding the buffer would push the number of remaining bytes
in this byte source above Integer.MAX_VALUE
. None of
the buffers are added in this case.public ByteBuffer removeLastBuffer()
Removes and returns the last buffer in the queue of byte buffers backing
this byte source. If this is the only remaining buffer in the queue and
thus data has already been read from it, the buffer's position has
advanced accordingly and thus the number of bytes remaining has
decreased. If all data in the buffer has already been read, the buffer
has been released and thus null
is returned.
The main use for this method is to remove a partially filled buffer so that more data can be added to it when the data already in the buffer is not sufficient to satisfy a function reading from the byte source. This way, it can be avoided to accumulate partially filled buffers in the byte source which would have a negative impact on memory usage and might also hurt the read performance.
Care must be taken when adding data to the buffer returned by this method. As the buffer is prepared for reading from it, the new data must be added behind the buffer's limit and the limit must be advanced accordingly.
null
if the queue is empty (remaining()
returns zero).IllegalStateException
- if an atomic read operation is in progress.public ByteBufferByteSource skip(int length)
ByteSource
length
- number of bytes to be skipped.public <T> T atomicGet(ByteSource.AtomicGetOperation<T> atomicGetOperation)
ByteSource
ByteSource.AtomicGetOperation.get()
method of
atomicGetOperation
throws an exception) all data read within
the transaction is kept and this byte source's position is reset to the
position before the transaction started. This method will throw any
exception thrown by ByteSource.AtomicGetOperation.get()
. Atomic get
operations may be nested (see ByteSource.AtomicGetOperation.get()
for
details). Despite its name, this method should not be considered to be
thread-safe.T
- type of the return value of the atomic operation.atomicGetOperation
- get operation that shall be performed atomically.ByteSource.AtomicGetOperation.get()
.public int remaining()
ByteSource
BufferUnderflowException
is thrown.public ByteBufferByteSource getByteArray(byte[] destination, int offset, int length)
ByteSource
destination
- array into which the read data is copied. This array's length
must be at least length + destinationOffset
.offset
- offset into the destination array. The destination array is
filled starting at this position.length
- number of bytes to be read.public ByteBufferByteSource getDoubleArray(double[] destination, int offset, int length)
ByteSource
getDoubleArray
in interface ByteSource
getDoubleArray
in class AbstractByteSource
destination
- array into which the read values are copied. This array's
length must be at least
length + destinationOffset
.offset
- offset into the destination array. The destination array is
filled starting at this position.length
- number of values to be read.public ByteBufferByteSource getFloatArray(float[] destination, int offset, int length)
ByteSource
getFloatArray
in interface ByteSource
getFloatArray
in class AbstractByteSource
destination
- array into which the read values are copied. This array's
length must be at least
length + destinationOffset
.offset
- offset into the destination array. The destination array is
filled starting at this position.length
- number of values to be read.public ByteBufferByteSource getIntArray(int[] destination, int offset, int length)
ByteSource
getIntArray
in interface ByteSource
getIntArray
in class AbstractByteSource
destination
- array into which the read values are copied. This array's
length must be at least
length + destinationOffset
.offset
- offset into the destination array. The destination array is
filled starting at this position.length
- number of values to be read.public ByteBufferByteSource getLongArray(long[] destination, int offset, int length)
ByteSource
getLongArray
in interface ByteSource
getLongArray
in class AbstractByteSource
destination
- array into which the read values are copied. This array's
length must be at least
length + destinationOffset
.offset
- offset into the destination array. The destination array is
filled starting at this position.length
- number of values to be read.public ByteBufferByteSource getShortArray(short[] destination, int offset, int length)
ByteSource
getShortArray
in interface ByteSource
getShortArray
in class AbstractByteSource
destination
- array into which the read values are copied. This array's
length must be at least
length + destinationOffset
.offset
- offset into the destination array. The destination array is
filled starting at this position.length
- number of values to be read.Copyright © 2014–2017 aquenos GmbH. All rights reserved.