Package org.apache.qpid.protonj2.buffer

Interface ProtonBuffer

All Superinterfaces:

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

All Known Subinterfaces:

ProtonCompositeBuffer

All Known Implementing Classes:

Netty4ToProtonBufferAdapter, Netty5ToProtonBufferAdapter, ProtonByteArrayBuffer, ProtonCompositeBufferImpl

public interface ProtonBuffer
extends ProtonBufferAccessors, Resource<ProtonBuffer>, Comparable<ProtonBuffer>

Buffer type abstraction used to provide users of the proton library with a means of using their own type of byte buffer types in combination with the library tooling.

Method Summary

Modifier and Type	Method	Description
default ProtonBuffer	advanceReadOffset(int length)	Adjusts the current getReadOffset() of this buffer by the specified length.
default ProtonBuffer	advanceWriteOffset(int length)	Adjusts the current getWriteOffset() of this buffer by the specified length.
default ProtonBufferIterator	bufferIterator()	Creates and returns a new ProtonBufferIterator that iterates from the current read offset and continues until all readable bytes have been traversed.
ProtonBufferIterator	bufferIterator(int offset, int length)	Creates and returns a new ProtonBufferIterator that iterates from the given offset and continues until specified number of bytes has been traversed.
default ProtonBufferIterator	bufferReverseIterator()	Creates and returns a new ProtonBufferIterator that reverse iterates over the readable bytes of the source buffer (write offset to read offset).
ProtonBufferIterator	bufferReverseIterator(int offset, int length)	Creates and returns a new ProtonBufferIterator that reverse iterates from the given offset and continues until specified number of bytes has been traversed.
int	capacity()
default ProtonBuffer	clear()	Reset the read and write offsets to zero.
void	close()	Close the buffer and clean up an resources that are held.
ProtonBuffer	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 ensureWritable(int) call.
default int	compareTo(ProtonBuffer buffer)	Compares the remaining content of the current buffer with the remaining content of the given buffer, which must not be null.
ProtonBufferComponentAccessor	componentAccessor()	Returns a component access object that can be used to gain access to the constituent buffer components for use in IO operations or other lower level buffer operations that need to work on single compoents.
int	componentCount()	Returns the number of constituent buffer components that are contained in this buffer instance which for a non-composite buffer will always be one (namely itself).
ProtonBuffer	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 ProtonBuffer	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 ProtonBuffer	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 ProtonBuffer	copy(int index, int length)	Returns a copy of this buffer's sub-region.
ProtonBuffer	copy(int index, int length, boolean readOnly)	Returns a copy of this buffer's sub-region.
void	copyInto(int offset, byte[] destination, int destOffset, int length)	Copies the given number of bytes from this buffer into the specified target byte array starting at the given offset into this buffer.
void	copyInto(int offset, ByteBuffer destination, int destOffset, int length)	Copies the given number of bytes from this buffer into the specified target ByteBuffer starting at the given offset into this buffer.
void	copyInto(int offset, ProtonBuffer destination, int destOffset, int length)	Copies the given number of bytes from this buffer into the specified target ProtonBuffer starting at the given offset into this buffer.
default ProtonBuffer	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.
ProtonBuffer	ensureWritable(int amount, 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.
ProtonBuffer	fill(byte value)	Assigns the given value to every byte in the buffer without respect for the buffer read or write offsets.
default int	getReadableBytes()
int	getReadOffset()
default int	getWritableBytes()
int	getWriteOffset()
int	implicitGrowthLimit()	Returns 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.
ProtonBuffer	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.
default int	indexOf(byte needle)	Starting from the current read offset into this buffer, find the next offset (index) in the buffer where the given value is located or -1 if the value is not found by the time the remaining readable bytes has been searched.
int	indexOf(byte needle, int offset, int length)	Starting from the given offset into this buffer, find the next offset (index) in the buffer where the given value is located or -1 if the value is not found by the time the specified number of bytes has been searched.
boolean	isClosed()	A Resource is closed either following a call to the Resource.close() method or by the resource being transfered by way of the Resource.transfer() method.
boolean	isComposite()
boolean	isDirect()
default boolean	isReadable()
boolean	isReadOnly()
default boolean	isWritable()
int	readableComponentCount()	Returns the number of readable constituent buffer components that are contained in this buffer instance which for a non-composite buffer will always be zero or one (namely itself).
default ProtonBuffer	readBytes(byte[] destination, int offset, int length)	Read from this buffer, into the destination array, the given number of bytes.
default ProtonBuffer	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 CharSequence	readCharSequence(int length, Charset charset)	Reads a CharSequence of the provided length using the given Charset.
default ProtonBuffer	readSplit(int length)	Splits this buffer at the read offset + the length given.
ProtonBuffer	setReadOffset(int value)	Sets the read offset for this buffer.
ProtonBuffer	setWriteOffset(int value)	Sets the write offset for this buffer.
default ProtonBuffer	split()	Splits this buffer at the write offset.
ProtonBuffer	split(int splitOffset)	Splits this buffer at the given offset.
default String	toString(Charset charset)	Returns a String created from the buffer's underlying bytes using the specified Charset for the newly created String.
int	transferFrom(FileChannel channel, long position, int length)	Reads a sequence of bytes from the given channel into this buffer.
int	transferFrom(ReadableByteChannel channel, int length)	Reads a sequence of bytes from the given channel into this buffer.
int	transferTo(WritableByteChannel channel, int length)	Read from this buffer and write to the given channel.
default Object	unwrap()	Return the underlying buffer object that backs this ProtonBuffer instance, or self if there is no backing object.
int	writableComponentCount()	Returns the number of writable constituent buffer components that are contained in this buffer instance which for a non-composite buffer will always be zero or one (namely itself).
default ProtonBuffer	writeBytes(byte[] source)	Writes into this buffer, all the bytes from the given byte array.
default ProtonBuffer	writeBytes(byte[] source, int offset, int length)	Writes into this buffer, the given number of bytes from the byte array.
default ProtonBuffer	writeBytes(ByteBuffer source)	Writes into this buffer from the source ByteBuffer.
default ProtonBuffer	writeBytes(ProtonBuffer source)	Writes into this buffer, all the readable bytes from the given buffer.
default ProtonBuffer	writeCharSequence(CharSequence source, Charset charset)	Writes into this buffer, all the bytes from the given source using the passed charset.
default ProtonBuffer	writeSplit(int length)	Splits this buffer at the write offset + the length given.

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

close

void close()

Close the buffer and clean up an resources that are held. The buffer close must not throw an exception.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Resource<ProtonBuffer>

isDirect

boolean isDirect()

Returns:

true if the buffer is backed by native memory.

unwrap

default Object unwrap()

Return the underlying buffer object that backs this ProtonBuffer instance, or self if there is no backing object. This method should be overridden in buffer abstraction when access to the underlying backing store is needed such as when wrapping pooled resources that need explicit release calls.

Returns:

an underlying buffer object or other backing store for this buffer.

convertToReadOnly

ProtonBuffer convertToReadOnly()

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.

Returns:

this buffer for use in chaining.

isReadOnly

boolean isReadOnly()

Returns:

whether this buffer instance is read-only or not.

isClosed

boolean isClosed()

Description copied from interface: Resource

A Resource is closed either following a call to the Resource.close() method or by the resource being transfered by way of the Resource.transfer() method.

Specified by:

isClosed in interface Resource<ProtonBuffer>

Returns:

if this buffer has been closed and can no longer be accessed for reads or writes.

getReadableBytes

default int getReadableBytes()

Returns:

the number of bytes available for reading from this buffer.

getReadOffset

int getReadOffset()

Returns:

the current value of the read offset for this buffer.

setReadOffset

ProtonBuffer setReadOffset(int value)

Sets the read offset for this buffer.

Parameters:

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

Returns:

this buffer for use in chaining.

Throws:

IndexOutOfBoundsException - if the value given is greater than the write offset or negative.

advanceReadOffset

default ProtonBuffer advanceReadOffset(int length)

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

Parameters:

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

Returns:

this ProtonBuffer for chaining.

Throws:

IllegalArgumentException - if the {#code length} given is negative.

IndexOutOfBoundsException - if length is greater than this.readableBytes

isReadable

default boolean isReadable()

Returns:

true if the read index is less than the write index.

getWritableBytes

default int getWritableBytes()

Returns:

the number of bytes that can be written to this buffer before the limit is hit.

getWriteOffset

int getWriteOffset()

Returns:

the current value of the write offset for this buffer.

setWriteOffset

ProtonBuffer setWriteOffset(int value)

Sets the write offset for this buffer.

Parameters:

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

Returns:

this buffer for use in chaining.

Throws:

IndexOutOfBoundsException - if the value less than the read offset or greater than the capacity.

advanceWriteOffset

default ProtonBuffer advanceWriteOffset(int length)

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

Parameters:

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

Returns:

this ProtonBuffer for chaining.

Throws:

IllegalArgumentException - if the {#code length} given is negative.

IndexOutOfBoundsException - if length is greater than the buffer capacity()

isWritable

default boolean isWritable()

Returns:

true if the buffer has bytes remaining between the write offset and the capacity.

fill

ProtonBuffer fill(byte value)

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

Parameters:

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

Returns:

this ProtonBuffer for chaining.

capacity

int capacity()

Returns:

the number of bytes this buffer can currently contain.

implicitGrowthLimit

int implicitGrowthLimit()

Returns 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.

Returns:

the number of bytes this buffer can currently grow to..

implicitGrowthLimit

ProtonBuffer 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. 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.

Parameters:

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

Returns:

this buffer for using in call chaining.

ensureWritable

default ProtonBuffer ensureWritable(int amount)
                             throws IndexOutOfBoundsException,
IllegalArgumentException

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.

Parameters:

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

Returns:

this buffer for using in call chaining.

Throws:

IllegalArgumentException - if the amount given is less than zero.

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

ensureWritable

ProtonBuffer ensureWritable(int amount,
 int minimumGrowth,
 boolean allowCompaction)
                     throws IndexOutOfBoundsException,
IllegalArgumentException

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.

Parameters:

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

IllegalArgumentException - if the amount given is less than zero.

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

copy

default ProtonBuffer 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. The returned copy will not be read-only regardless of the read-only state of this buffer instance at the time of copy.

Returns:

a deep copy of this ProtonBuffer instance.

copy

default ProtonBuffer copy(int index,
 int length)

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 getReadOffset() or 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.

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 ProtonBuffer 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. 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.

Parameters:

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

Returns:

a new ProtonBuffer instance containing the copied bytes.

copy

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

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 getReadOffset() or 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.

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.

clear

default ProtonBuffer clear()

Reset the read and write offsets to zero.

This method is not required to reset the data previously written to this buffer.

Returns:

this buffer for using in call chaining.

compact

ProtonBuffer 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 ensureWritable(int) call.

Returns:

this buffer for using in call chaining.

readSplit

default ProtonBuffer readSplit(int length)

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

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 ProtonBuffer writeSplit(int length)

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

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 ProtonBuffer split()

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.

Returns:

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

split

ProtonBuffer split(int splitOffset)

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.

Parameters:

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

Returns:

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

toString

default String toString(Charset charset)

Returns a String created from the buffer's underlying bytes using the specified Charset for the newly created String.

Parameters:

charset - the Charset to use to construct the new string.

Returns:

a string created from the buffer's underlying bytes using the given Charset.

compareTo

default int compareTo(ProtonBuffer buffer)

Compares the remaining content of the current buffer with the remaining content of the given buffer, which must not be null. Each byte is compared in turn as an unsigned value, returning upon the first difference. If no difference is found before the end of one buffer, the shorter buffer is considered less than the other, or else if the same length then they are considered equal.

Specified by:

compareTo in interface Comparable<ProtonBuffer>

Parameters:

buffer - The buffer to compare to this instance.

Returns:

a negative, zero, or positive integer when this buffer is less than, equal to, or greater than the given buffer.

See Also:

• Comparable.compareTo(Object)

writeCharSequence

default ProtonBuffer writeCharSequence(CharSequence source,
 Charset charset)

Writes into this buffer, all the bytes from the given source using the passed charset. This updates the write offset of this buffer.

Parameters:

source - The CharSequence to read the bytes from.

charset - The Charset to use for encoding the bytes that will be written.

Returns:

this buffer for using in call chaining.

readCharSequence

default CharSequence readCharSequence(int length,
 Charset charset)

Reads a CharSequence of the provided length using the given Charset. This advances the getReadOffset() reader offset} of this buffer.

Parameters:

length - The number of bytes to read to create the resulting CharSequence.

charset - The Charset of the bytes to be read and decoded into the resulting CharSequence.

Returns:

CharSequence read and decoded from bytes in this buffer.

Throws:

IndexOutOfBoundsException - if the passed length is more than the getReadableBytes() of this buffer.

copyInto

void copyInto(int offset,
 byte[] destination,
 int destOffset,
 int length)

Copies the given number of bytes from this buffer into the specified target byte array starting at the given offset into this buffer. The copied region is written into the target starting at the given offset and continues for the specified length of elements.

Parameters:

offset - The offset into this buffer where the copy begins from.

destination - The destination byte array where the copied bytes are written.

destOffset - The offset into the destination to begin writing the copied bytes.

length - The number of bytes to copy into the destination.

Throws:

NullPointerException - if the destination array is null.

IndexOutOfBoundsException - if the source or destination positions, or the length, are negative, or if the resulting end positions reaches beyond the end of either this buffer, or the destination array.

IllegalStateException - if this buffer has already been closed.

copyInto

void copyInto(int offset,
 ByteBuffer destination,
 int destOffset,
 int length)

Copies the given number of bytes from this buffer into the specified target ByteBuffer starting at the given offset into this buffer. The copied region is written into the target starting at the given offset and continues for the specified length of elements.

Parameters:

offset - The offset into this buffer where the copy begins from.

destination - The destination ByteBuffer where the copied bytes are written.

destOffset - The offset into the destination to begin writing the copied bytes.

length - The number of bytes to copy into the destination.

Throws:

NullPointerException - if the destination buffer is null.

IndexOutOfBoundsException - if the source or destination positions, or the length, are negative, or if the resulting end positions reaches beyond the end of either this buffer, or the destination buffer.

IllegalStateException - if this buffer has already been closed.

copyInto

void copyInto(int offset,
 ProtonBuffer destination,
 int destOffset,
 int length)

Copies the given number of bytes from this buffer into the specified target ProtonBuffer starting at the given offset into this buffer. The copied region is written into the target starting at the given offset and continues for the specified length of elements.

Parameters:

offset - The offset into this buffer where the copy begins from.

destination - The destination ProtonBuffer where the copied bytes are written.

destOffset - The offset into the destination to begin writing the copied bytes.

length - The number of bytes to copy into the destination.

Throws:

NullPointerException - if the destination buffer is null.

IndexOutOfBoundsException - if the source or destination positions, or the length, are negative, or if the resulting end positions reaches beyond the end of either this buffer, or the destination buffer.

IllegalStateException - if this buffer has already been closed.

writeBytes

default ProtonBuffer writeBytes(ProtonBuffer source)

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

Parameters:

source - The buffer to read from.

Returns:

This buffer.

Throws:

NullPointerException - If the source buffer is null.

writeBytes

default ProtonBuffer writeBytes(byte[] source)

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

Parameters:

source - The byte array to read from.

Returns:

this buffer for using in call chaining.

writeBytes

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

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

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 ProtonBuffer writeBytes(ByteBuffer source)

Writes into this buffer from the source ByteBuffer. This updates the getWriteOffset() of this buffer and also the position of the source ByteBuffer.

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

Parameters:

source - The ByteBuffer to read from.

Returns:

this buffer for using in call chaining.

readBytes

default ProtonBuffer 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.

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

Parameters:

destination - The ByteBuffer to write into.

Returns:

this buffer for using in call chaining.

readBytes

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

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.

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.

transferTo

int transferTo(WritableByteChannel channel,
 int length)
        throws IOException

Read from this buffer and write to the given channel.

The number of bytes actually written to the channel are returned. No more than the given length of bytes, or the number of readable bytes, will be written to the channel, whichever is smaller. A channel that has a position marker, will be advanced by the number of bytes written. The read offset of this buffer will also be advanced by the number of bytes written.

Parameters:

channel - The channel to write to.

length - The maximum number of bytes to write.

Returns:

The actual number of bytes written, possibly zero.

Throws:

IOException - If the write-operation on the channel failed for some reason.

transferFrom

int transferFrom(ReadableByteChannel channel,
 int length)
          throws IOException

Reads a sequence of bytes from the given channel into this buffer.

The method reads a given amount of bytes from the provided channel and returns the number of bytes actually read which can be zero or -1 if the channel has reached the end of stream state.

The length value given is a maximum limit however the code will adjust this if the number of writable bytes in this buffer is smaller (or zero) and the result will indicate how many bytes where actually read. The write offset of this buffer will be advanced by the number of bytes read from the buffer as will the channel position index if one exists.

Parameters:

channel - The readable byte channel where the bytes are read

length - The maximum number of bytes to read from the channel

Returns:

The number of bytes read, possibly zero, or -1 if the channel has reached end-of-stream

Throws:

IOException - if the read operation fails

transferFrom

int transferFrom(FileChannel channel,
 long position,
 int length)
          throws IOException

Reads a sequence of bytes from the given channel into this buffer.

The method reads a given amount of bytes from the provided channel and returns the number of bytes actually read which can be zero or -1 if the channel has reached the end of stream state.

The length value given is a maximum limit however the code will adjust this if the number of writable bytes in this buffer is smaller (or zero) and the result will indicate how many bytes where actually read. The write offset of this buffer will be advanced by the number of bytes read from the buffer, the channel will not have its position modified.

Parameters:

channel - The File channel where the bytes are read

position - The position in the channel where the read should begin

length - The maximum number of bytes to read from the channel

Returns:

The number of bytes read, possibly zero, or -1 if the channel has reached end-of-stream

Throws:

IOException - if the read operation fails

isComposite

boolean isComposite()

Returns:

true if the buffer is backed by one or more ProtonBuffer instances.

componentCount

int componentCount()

Returns the number of constituent buffer components that are contained in this buffer instance which for a non-composite buffer will always be one (namely itself). For a composite buffer this count is the total count of all buffers mapped to the composite.

Returns:

the number of buffers managed by this ProtonBuffer instance.

readableComponentCount

int readableComponentCount()

Returns the number of readable constituent buffer components that are contained in this buffer instance which for a non-composite buffer will always be zero or one (namely itself). For a composite buffer this count is the total count of all buffers mapped to the composite which are readable.

Returns:

the number of readable buffers managed by this ProtonBuffer instance.

writableComponentCount

int writableComponentCount()

Returns the number of writable constituent buffer components that are contained in this buffer instance which for a non-composite buffer will always be zero or one (namely itself). For a composite buffer this count is the total count of all buffers mapped to the composite which are writable.

Returns:

the number of writable buffer components managed by this ProtonBuffer instance.

componentAccessor

ProtonBufferComponentAccessor componentAccessor()

Returns a component access object that can be used to gain access to the constituent buffer components for use in IO operations or other lower level buffer operations that need to work on single compoents.

The general usage of the component access object should be within a try-with-resource block as follows:

   try (ProtonBufferComponentAccessor accessor = buffer.componentAccessor()) {
      for (ProtonBufferComponent component : accessor.readableComponents()) {
         // Access logic here....
      }
   }
 

Returns:

a component access object instance used to view the buffer internal components

bufferIterator

default ProtonBufferIterator bufferIterator()

Creates and returns a new ProtonBufferIterator that iterates from the current read offset and continues until all readable bytes have been traversed. The source buffer read and write offsets are not modified by an iterator instance.

The caller must ensure that the source buffer lifetime extends beyond the lifetime of the returned ProtonBufferIterator.

Returns:

a new buffer iterator that iterates over the readable bytes.

bufferIterator

ProtonBufferIterator bufferIterator(int offset,
 int length)

Creates and returns a new ProtonBufferIterator that iterates from the given offset and continues until specified number of bytes has been traversed. The source buffer read and write offsets are not modified by an iterator instance.

The caller must ensure that the source buffer lifetime extends beyond the lifetime of the returned ProtonBufferIterator.

Parameters:

offset - The offset into the buffer where iteration begins

length - The number of bytes to iterate over.

Returns:

a new buffer iterator that iterates over the readable bytes.

bufferReverseIterator

default ProtonBufferIterator bufferReverseIterator()

Creates and returns a new ProtonBufferIterator that reverse iterates over the readable bytes of the source buffer (write offset to read offset). The source buffer read and write offsets are not modified by an iterator instance.

The caller must ensure that the source buffer lifetime extends beyond the lifetime of the returned ProtonBufferIterator.

Returns:

a new buffer iterator that iterates over the readable bytes.

bufferReverseIterator

ProtonBufferIterator bufferReverseIterator(int offset,
 int length)

Creates and returns a new ProtonBufferIterator that reverse iterates from the given offset and continues until specified number of bytes has been traversed. The source buffer read and write offsets are not modified by an iterator instance.

The caller must ensure that the source buffer lifetime extends beyond the lifetime of the returned ProtonBufferIterator.

Parameters:

offset - The offset into the buffer where iteration begins

length - The number of bytes to iterate over.

Returns:

a new buffer iterator that iterates over the readable bytes.

indexOf

default int indexOf(byte needle)

Starting from the current read offset into this buffer, find the next offset (index) in the buffer where the given value is located or -1 if the value is not found by the time the remaining readable bytes has been searched. This method does not affect the read or write offset and can be called from any point in the buffer regardless of the current read or write offsets.

Parameters:

needle - The byte value to search for in the remaining buffer bytes.

Returns:

the location in the buffer where the value was found or -1 if not found.

indexOf

int indexOf(byte needle,
 int offset,
 int length)

Starting from the given offset into this buffer, find the next offset (index) in the buffer where the given value is located or -1 if the value is not found by the time the specified number of bytes has been searched. This method does not affect the read or write offset and can be called from any point in the buffer regardless of the current read or write offsets. The search bounds are that of the buffer's readable bytes meaning that the starting office cannot be less than the read offset and the length cannot cause the search to read past the readable bytes otherwise an IndexOutOfBoundsException will be thrown.

Parameters:

needle - The byte value to search for in the remaining buffer bytes.

offset - The offset into the buffer where the search should begin from.

length - The offset into the buffer where the search should begin from.

Returns:

the location in the buffer where the value was found or -1 if not found.