Package org.apache.qpid.protonj2.buffer

Interface ProtonCompositeBuffer

All Superinterfaces:

AutoCloseable, Comparable<ProtonBuffer>, ProtonBuffer, ProtonBufferAccessors, Resource<ProtonBuffer>

All Known Implementing Classes:

ProtonCompositeBufferImpl

public interface ProtonCompositeBuffer
extends ProtonBuffer

Defines the API for a specialized buffer type that is a composite of other buffer instances which is presented as a single buffer view.

Method Summary

Modifier and Type	Method	Description
default ProtonCompositeBuffer	advanceReadOffset(int length)	Adjusts the current ProtonBuffer.getReadOffset() of this buffer by the specified length.
default ProtonCompositeBuffer	advanceWriteOffset(int length)	Adjusts the current ProtonBuffer.getWriteOffset() of this buffer by the specified length.
ProtonCompositeBuffer	append(ProtonBuffer buffer)	Appends the given buffer to this composite buffer if all the constraints on buffer composites are met, otherwise thrown an exception.
ProtonCompositeBuffer	compact()	Moves the readable portion of the buffer to the beginning of the underlying buffer storage and possibly makes additional bytes available for writes before a buffer expansion would occur via an ProtonBuffer.ensureWritable(int) call.
ProtonCompositeBuffer	convertToReadOnly()	Converts this buffer instance to a read-only buffer, any write operation that is performed on this buffer following this call will fail.
default ProtonCompositeBuffer	copy()	Create a deep copy of the readable bytes of this ProtonBuffer, the returned buffer can be modified without affecting the contents or position markers of this instance.
default ProtonCompositeBuffer	copy(boolean readOnly)	Returns a copy of this buffer's readable bytes and sets the read-only state of the returned buffer based on the value of the read-only flag.
default ProtonCompositeBuffer	copy(int index, int length)	Returns a copy of this buffer's sub-region.
ProtonCompositeBuffer	copy(int index, int length, boolean readOnly)	Returns a copy of this buffer's sub-region.
static ProtonCompositeBuffer	create(ProtonBufferAllocator allocator)	Create an empty composite buffer that will use the provided allocator to create new buffer capacity if writes are performed and insufficient space remains (unless the capacity limit is reached).
static ProtonCompositeBuffer	create(ProtonBufferAllocator allocator, ProtonBuffer buffer)	Create an composite buffer with the given buffer instance as the initial buffer payload.
static ProtonCompositeBuffer	create(ProtonBufferAllocator allocator, ProtonBuffer[] buffers)	Create an composite buffer with the given array of buffers as the initial buffer payload.
Iterable<ProtonBuffer>	decomposeBuffer()	Splits the composite buffer up into a collection of buffers that comprise it and leaves this buffer in what is effectively a closed state.
default ProtonCompositeBuffer	ensureWritable(int amount)	Ensures that the requested number of bytes is available for write operations in the current buffer, growing the buffer if needed to meet the requested writable capacity.
ProtonCompositeBuffer	ensureWritable(int size, int minimumGrowth, boolean allowCompaction)	Ensures that the requested number of bytes is available for write operations in the current buffer, growing the buffer if needed to meet the requested writable capacity.
ProtonCompositeBuffer	fill(byte value)	Assigns the given value to every byte in the buffer without respect for the buffer read or write offsets.
ProtonCompositeBuffer	implicitGrowthLimit(int limit)	Configures the limit assigned to this buffer if one was set which controls how large the capacity of the buffer can grow implicitly via write calls.
static boolean	isComposite(ProtonBuffer buffer)	Checks if the given buffer is an composite buffer instance or not.
default ProtonCompositeBuffer	readBytes(byte[] destination, int offset, int length)	Read from this buffer, into the destination array, the given number of bytes.
default ProtonCompositeBuffer	readBytes(ByteBuffer destination)	Read from this buffer, into the destination ByteBuffer This updates the read offset of this buffer and also the position of the destination ByteBuffer.
default ProtonCompositeBuffer	readSplit(int length)	Splits this buffer at the read offset + the length given.
ProtonCompositeBuffer	setReadOffset(int value)	Sets the read offset for this buffer.
ProtonCompositeBuffer	setWriteOffset(int value)	Sets the write offset for this buffer.
default ProtonCompositeBuffer	split()	Splits this buffer at the write offset.
ProtonCompositeBuffer	split(int splitOffset)	Splits this buffer at the given offset.
ProtonCompositeBuffer	splitComponentsCeil(int splitOffset)	Split this buffer returning a composite that consists of all the buffer components up to and including the buffer that contains the split offset, no buffer components are split.
ProtonCompositeBuffer	splitComponentsFloor(int splitOffset)	Split this buffer returning a composite that consists of all the buffer components that come before the buffer that contains the split offset, no buffer components are split.
default ProtonCompositeBuffer	writeBytes(byte[] source)	Writes into this buffer, all the bytes from the given byte array.
default ProtonCompositeBuffer	writeBytes(byte[] source, int offset, int length)	Writes into this buffer, the given number of bytes from the byte array.
default ProtonCompositeBuffer	writeBytes(ByteBuffer source)	Writes into this buffer from the source ByteBuffer.
default ProtonCompositeBuffer	writeBytes(ProtonBuffer source)	Writes into this buffer, all the readable bytes from the given buffer.
default ProtonCompositeBuffer	writeSplit(int length)	Splits this buffer at the write offset + the length given.

Methods inherited from interface org.apache.qpid.protonj2.buffer.ProtonBuffer

bufferIterator, bufferIterator, bufferReverseIterator, bufferReverseIterator, capacity, clear, close, compareTo, componentAccessor, componentCount, copyInto, copyInto, copyInto, getReadableBytes, getReadOffset, getWritableBytes, getWriteOffset, implicitGrowthLimit, indexOf, indexOf, isClosed, isComposite, isDirect, isReadable, isReadOnly, isWritable, readableComponentCount, readCharSequence, toString, transferFrom, transferFrom, transferTo, unwrap, writableComponentCount, writeCharSequence

Methods inherited from interface org.apache.qpid.protonj2.buffer.ProtonBufferAccessors

getBoolean, getByte, getChar, getDouble, getFloat, getInt, getLong, getShort, getUnsignedByte, getUnsignedInt, getUnsignedShort, readBoolean, readByte, readChar, readDouble, readFloat, readInt, readLong, readShort, readUnsignedByte, readUnsignedInt, readUnsignedShort, setBoolean, setByte, setChar, setDouble, setFloat, setInt, setLong, setShort, setUnsignedByte, setUnsignedInt, setUnsignedShort, writeBoolean, writeByte, writeChar, writeDouble, writeFloat, writeInt, writeLong, writeShort, writeUnsignedByte, writeUnsignedInt, writeUnsignedShort

Methods inherited from interface org.apache.qpid.protonj2.resource.Resource

transfer

Method Details

create

static ProtonCompositeBuffer create(ProtonBufferAllocator allocator)

Create an empty composite buffer that will use the provided allocator to create new buffer capacity if writes are performed and insufficient space remains (unless the capacity limit is reached).

Parameters:

allocator - The allocator to use when adding new buffer capacity automatically.

Returns:

a new empty composite buffer instance.

create

static ProtonCompositeBuffer create(ProtonBufferAllocator allocator,
 ProtonBuffer buffer)

Create an composite buffer with the given buffer instance as the initial buffer payload. The provided buffer allocator will use the provided allocator to create new buffer capacity if writes are performed and insufficient space remains (unless the capacity limit is reached).

Parameters:

allocator - The allocator to use when adding new buffer capacity automatically.

buffer - The initial buffer to append as the body of the returned composite buffer.

Returns:

a new composite buffer instance that wraps the given buffer.

create

static ProtonCompositeBuffer create(ProtonBufferAllocator allocator,
 ProtonBuffer[] buffers)

Create an composite buffer with the given array of buffers as the initial buffer payload. The provided buffer allocator will use the provided allocator to create new buffer capacity if writes are performed and insufficient space remains (unless the capacity limit is reached).

Parameters:

allocator - The allocator to use when adding new buffer capacity automatically.

buffers - The initial buffers to append as the body of the returned composite buffer.

Returns:

a new composite buffer instance that wraps the given buffers.

isComposite

static boolean isComposite(ProtonBuffer buffer)

Checks if the given buffer is an composite buffer instance or not.

Parameters:

buffer - the buffer instance to check.

Returns:

true if the buffer given is a composite buffer or false if not.

append

ProtonCompositeBuffer append(ProtonBuffer buffer)

Appends the given buffer to this composite buffer if all the constraints on buffer composites are met, otherwise thrown an exception.

Parameters:

buffer - The buffer to append to this composite collection of buffers.

Returns:

this composite buffer instance.

decomposeBuffer

Iterable<ProtonBuffer> decomposeBuffer()

Splits the composite buffer up into a collection of buffers that comprise it and leaves this buffer in what is effectively a closed state. The returned buffers are now the property of the caller who must ensure they are closed when no longer in use..

Returns:

the collection of buffers that comprised this composite buffer.

splitComponentsFloor

ProtonCompositeBuffer splitComponentsFloor(int splitOffset)

Split this buffer returning a composite that consists of all the buffer components that come before the buffer that contains the split offset, no buffer components are split. This allows for operations such as reclaiming read bytes from a buffer to reduce overall memory use.

Parameters:

splitOffset - The index into the buffer where the split should be performed.

Returns:

A ProtonCompositeBuffer that owns all buffers that come before the buffer that holds given index.

splitComponentsCeil

ProtonCompositeBuffer splitComponentsCeil(int splitOffset)

Split this buffer returning a composite that consists of all the buffer components up to and including the buffer that contains the split offset, no buffer components are split.

Parameters:

splitOffset - The index into the buffer where the split should be performed.

Returns:

A ProtonCompositeBuffer that owns all buffers up to and including the buffer that holds given index.

fill

ProtonCompositeBuffer fill(byte value)

Description copied from interface: ProtonBuffer

Assigns the given value to every byte in the buffer without respect for the buffer read or write offsets.

Specified by:

fill in interface ProtonBuffer

Parameters:

value - The byte value to assign each byte in this buffer.

Returns:

this ProtonBuffer for chaining.

setReadOffset

ProtonCompositeBuffer setReadOffset(int value)

Description copied from interface: ProtonBuffer

Sets the read offset for this buffer.

Specified by:

setReadOffset in interface ProtonBuffer

Parameters:

value - The offset into the buffer where the read offset should be positioned.

Returns:

this buffer for use in chaining.

advanceReadOffset

default ProtonCompositeBuffer advanceReadOffset(int length)

Description copied from interface: ProtonBuffer

Adjusts the current ProtonBuffer.getReadOffset() of this buffer by the specified length.

Specified by:

advanceReadOffset in interface ProtonBuffer

Parameters:

length - the number of bytes to advance the read offset by.

Returns:

this ProtonBuffer for chaining.

setWriteOffset

ProtonCompositeBuffer setWriteOffset(int value)

Description copied from interface: ProtonBuffer

Sets the write offset for this buffer.

Specified by:

setWriteOffset in interface ProtonBuffer

Parameters:

value - The offset into the buffer where the write offset should be positioned.

Returns:

this buffer for use in chaining.

advanceWriteOffset

default ProtonCompositeBuffer advanceWriteOffset(int length)

Description copied from interface: ProtonBuffer

Adjusts the current ProtonBuffer.getWriteOffset() of this buffer by the specified length.

Specified by:

advanceWriteOffset in interface ProtonBuffer

Parameters:

length - the number of bytes to advance the write offset by.

Returns:

this ProtonBuffer for chaining.

implicitGrowthLimit

ProtonCompositeBuffer implicitGrowthLimit(int limit)

Description copied from interface: ProtonBuffer

Configures the limit assigned to this buffer if one was set which controls how large the capacity of the buffer can grow implicitly via write calls. Once the limit is hit any write call that requires more capacity than is currently available will throw an exception instead of allocating more space.

When a capacity limit is hit the buffer can still be enlarged but must be done explicitly via the ensure writable APIs.

The growth limit set applies only to this buffer instance and is not carried over to a copied buffer of the split buffer created from any of the buffer split calls.

Specified by:

implicitGrowthLimit in interface ProtonBuffer

Parameters:

limit - The limit to assign as the maximum capacity this buffer can grow

Returns:

this buffer for using in call chaining.

ensureWritable

default ProtonCompositeBuffer ensureWritable(int amount)
                                      throws IndexOutOfBoundsException,
IllegalArgumentException

Description copied from interface: ProtonBuffer

Ensures that the requested number of bytes is available for write operations in the current buffer, growing the buffer if needed to meet the requested writable capacity. This method will not alter the write offset but may change the value returned from the capacity method if new buffer space is allocated.

This method allows buffer compaction as a strategy to reclaim already read space to make room for additional writes. This implies that a composite buffer can reuse already read buffers to extend the buffer's writable space by moving them to the end of the set of composite buffers and reseting their index values to make them fully writable.

Specified by:

ensureWritable in interface ProtonBuffer

Parameters:

amount - The number of bytes beyond the current write index needed.

Returns:

this buffer for using in call chaining.

Throws:

IndexOutOfBoundsException - if the amount given would result in the buffer exceeding the maximum capacity for this buffer.

IllegalArgumentException - if the amount given is less than zero.

ensureWritable

ProtonCompositeBuffer ensureWritable(int size,
 int minimumGrowth,
 boolean allowCompaction)
                              throws IndexOutOfBoundsException,
IllegalArgumentException

Description copied from interface: ProtonBuffer

Ensures that the requested number of bytes is available for write operations in the current buffer, growing the buffer if needed to meet the requested writable capacity. This method will not alter the write offset but may change the value returned from the capacity method if new buffer space is allocated. If the buffer cannot create the required number of byte via compaction then the buffer will be grown by either the requested number of bytes or by the minimum allowed value specified.

This method allows buffer compaction as a strategy to reclaim already read space to make room for additional writes. This implies that a composite buffer can reuse already read buffers to extend the buffer's writable space by moving them to the end of the set of composite buffers and reseting their index values to make them fully writable.

Specified by:

ensureWritable in interface ProtonBuffer

Parameters:

size - The number of bytes beyond the current write index needed.

minimumGrowth - The minimum number of byte that the buffer can grow by

allowCompaction - Can the buffer use compaction as a strategy to create more writable space.

Returns:

this buffer for using in call chaining.

Throws:

IndexOutOfBoundsException - if the amount given would result in the buffer exceeding the maximum capacity for this buffer.

IllegalArgumentException - if the amount given is less than zero.

convertToReadOnly

ProtonCompositeBuffer convertToReadOnly()

Description copied from interface: ProtonBuffer

Converts this buffer instance to a read-only buffer, any write operation that is performed on this buffer following this call will fail. A buffer cannot be made writable after this call.

Specified by:

convertToReadOnly in interface ProtonBuffer

Returns:

this buffer for use in chaining.

copy

default ProtonCompositeBuffer copy()

Description copied from interface: ProtonBuffer

Create a deep copy of the readable bytes of this ProtonBuffer, the returned buffer can be modified without affecting the contents or position markers of this instance. The returned copy will not be read-only regardless of the read-only state of this buffer instance at the time of copy.

Specified by:

copy in interface ProtonBuffer

Returns:

a deep copy of this ProtonBuffer instance.

copy

default ProtonCompositeBuffer copy(int index,
 int length)

Description copied from interface: ProtonBuffer

Returns a copy of this buffer's sub-region. Modifying the content of the returned buffer or this buffer does not affect each other at all. This method does not modify the value returned from ProtonBuffer.getReadOffset() or ProtonBuffer.getWriteOffset() of this buffer.

The returned buffer will not be read-only even if this buffer is and as such the contents will be a deep copy regardless of this buffer's read-only state.

Specified by:

copy in interface ProtonBuffer

Parameters:

index - The index in this buffer where the copy should begin

length - The number of bytes to copy to the new buffer from this one.

Returns:

a new ProtonBuffer instance containing the copied bytes.

copy

default ProtonCompositeBuffer copy(boolean readOnly)

Description copied from interface: ProtonBuffer

Returns a copy of this buffer's readable bytes and sets the read-only state of the returned buffer based on the value of the read-only flag. If this buffer is read-only and the flag indicates a read-only copy then the copy may be a shallow copy that references the readable bytes of the source buffer.

Specified by:

copy in interface ProtonBuffer

Parameters:

readOnly - Should the returned buffer be read-only or not.

Returns:

a new ProtonBuffer instance containing the copied bytes.

copy

ProtonCompositeBuffer copy(int index,
 int length,
 boolean readOnly)
                    throws IllegalArgumentException

Description copied from interface: ProtonBuffer

Returns a copy of this buffer's sub-region. Modifying the content of the returned buffer or this buffer does not affect each other at all. This method does not modify the value returned from ProtonBuffer.getReadOffset() or ProtonBuffer.getWriteOffset() of this buffer.

If this buffer is read-only and the requested copy is also read-only the copy may be shallow and allow each buffer to share the same memory.

Specified by:

copy in interface ProtonBuffer

Parameters:

index - The index in this buffer where the copy should begin

length - The number of bytes to copy to the new buffer from this one.

readOnly - Should the returned buffer be read-only or not.

Returns:

a new ProtonBuffer instance containing the copied bytes.

Throws:

IllegalArgumentException - if the offset or length given are out of bounds.

compact

ProtonCompositeBuffer compact()

Description copied from interface: ProtonBuffer

Moves the readable portion of the buffer to the beginning of the underlying buffer storage and possibly makes additional bytes available for writes before a buffer expansion would occur via an ProtonBuffer.ensureWritable(int) call.

Specified by:

compact in interface ProtonBuffer

Returns:

this buffer for using in call chaining.

readSplit

default ProtonCompositeBuffer readSplit(int length)

Description copied from interface: ProtonBuffer

Splits this buffer at the read offset + the length given.

Specified by:

readSplit in interface ProtonBuffer

Parameters:

length - The number of bytes beyond the read offset where the split should occur

Returns:

A new buffer that owns the memory spanning the range given.

writeSplit

default ProtonCompositeBuffer writeSplit(int length)

Description copied from interface: ProtonBuffer

Splits this buffer at the write offset + the length given.

Specified by:

writeSplit in interface ProtonBuffer

Parameters:

length - The number of bytes beyond the write offset where the split should occur

Returns:

A new buffer that owns the memory spanning the range given.

split

default ProtonCompositeBuffer split()

Description copied from interface: ProtonBuffer

Splits this buffer at the write offset.

This creates two independent buffers that can manage differing views of the same memory region or in the case of a composite buffer two buffers that take ownership of differing sections of the composite buffer range. For a composite buffer a single buffer might be split if the offset lays within its bounds but all others buffers are divided amongst the two split buffers.

If this buffer is a read-only buffer then the resulting split buffer will also be read-only.

Specified by:

split in interface ProtonBuffer

Returns:

A new buffer that owns the memory spanning the range given.

split

ProtonCompositeBuffer split(int splitOffset)

Description copied from interface: ProtonBuffer

Splits this buffer at the given offset.

This creates two independent buffers that can manage differing views of the same memory region or in the case of a composite buffer two buffers that take ownership of differing sections of the composite buffer range. For a composite buffer a single buffer might be split if the offset lays within its bounds but all others buffers are divided amongst the two split buffers.

If this buffer is a read-only buffer then the resulting split buffer will also be read-only.

Specified by:

split in interface ProtonBuffer

Parameters:

splitOffset - The offset in this buffer where the split should occur.

Returns:

A new buffer that owns the memory spanning the range given.

writeBytes

default ProtonCompositeBuffer writeBytes(ProtonBuffer source)

Description copied from interface: ProtonBuffer

Writes into this buffer, all the readable bytes from the given buffer. This updates the ProtonBuffer.getWriteOffset() of this buffer, and the ProtonBuffer.getReadOffset() of the given buffer.

Specified by:

writeBytes in interface ProtonBuffer

Parameters:

source - The buffer to read from.

Returns:

This buffer.

writeBytes

default ProtonCompositeBuffer writeBytes(byte[] source)

Description copied from interface: ProtonBuffer

Writes into this buffer, all the bytes from the given byte array. This updates the ProtonBuffer.getWriteOffset() of this buffer by the length of the array.

Specified by:

writeBytes in interface ProtonBuffer

Parameters:

source - The byte array to read from.

Returns:

this buffer for using in call chaining.

writeBytes

default ProtonCompositeBuffer writeBytes(byte[] source,
 int offset,
 int length)

Description copied from interface: ProtonBuffer

Writes into this buffer, the given number of bytes from the byte array. This updates the ProtonBuffer.getWriteOffset() of this buffer by the length argument. Implementations are recommended to specialize this method and provide a more efficient version.

Specified by:

writeBytes in interface ProtonBuffer

Parameters:

source - The byte array to read from.

offset - The position in the source from where bytes should be written to this buffer.

length - The number of bytes to copy.

Returns:

this buffer for using in call chaining.

writeBytes

default ProtonCompositeBuffer writeBytes(ByteBuffer source)

Description copied from interface: ProtonBuffer

Writes into this buffer from the source ByteBuffer. This updates the ProtonBuffer.getWriteOffset() of this buffer and also the position of the source ByteBuffer. Implementations are recommended to specialize this method and provide a more efficient version.

Note: the behavior is undefined if the given ByteBuffer is an alias for the memory in this buffer.

Specified by:

writeBytes in interface ProtonBuffer

Parameters:

source - The ByteBuffer to read from.

Returns:

this buffer for using in call chaining.

readBytes

default ProtonCompositeBuffer readBytes(ByteBuffer destination)

Description copied from interface: ProtonBuffer

Read from this buffer, into the destination ByteBuffer This updates the read offset of this buffer and also the position of the destination ByteBuffer.

Note: the behavior is undefined if the given ByteBuffer is an alias for the memory in this buffer.

Specified by:

readBytes in interface ProtonBuffer

Parameters:

destination - The ByteBuffer to write into.

Returns:

this buffer for using in call chaining.

readBytes

default ProtonCompositeBuffer readBytes(byte[] destination,
 int offset,
 int length)

Description copied from interface: ProtonBuffer

Read from this buffer, into the destination array, the given number of bytes. This updates the read offset of this buffer by the length argument.

Specified by:

readBytes in interface ProtonBuffer

Parameters:

destination - The byte array to write into.

offset - Position in the destination to where bytes should be written from this buffer.

length - The number of bytes to copy.

Returns:

This buffer.