net.openhft.chronicle.bytes

Interface StreamingDataOutput<S extends StreamingDataOutput<S>>

All Superinterfaces:

StreamingCommon<S>

All Known Subinterfaces:

Bytes<U>, BytesOut<U>, ByteStringAppender<B>

All Known Implementing Classes:

AbstractBytes, ChunkedMappedBytes, CommonMappedBytes, EmbeddedBytes, GuardedNativeBytes, HexDumpBytes, MappedBytes, NativeBytes, OnHeapBytes, SingleMappedBytes, SubBytes, UncheckedBytes, UncheckedNativeBytes, VanillaBytes

public interface StreamingDataOutput<S extends StreamingDataOutput<S>>
extends StreamingCommon<S>

StreamingDataOutput is an interface for classes that support writing data to a stream. Position based access. Once data has been read, the writePosition() moves.

The various write methods in this interface support writing bytes, arrays of bytes, and sequences of bytes from other sources like ByteBuffer and RandomDataInput. It also provides methods for writing primitive data types and their boxed counterparts. Additionally, it supports writing complex data structures such as BigDecimal, BigInteger, Histogram and objects in unsafe way.

Not all the methods are expected to be implemented by classes. Default methods are provided for common use cases. Classes that extend this interface can override these methods to provide more efficient or custom implementations.

Implementations of this interface are expected to handle cases where the buffer may not have enough capacity to handle the write operation. In such cases, methods should throw a BufferOverflowException.

Instances of classes implementing StreamingDataOutput are not guaranteed to be thread safe. If multiple threads interact with the same instance, external synchronization should be used.

See Also:

RandomDataOutput, ByteBuffer, BufferOverflowException, BigDecimal, BigInteger, Histogram

Field Summary

Fields

Modifier and Type	Field and Description
static int	JAVA9_STRING_CODER_LATIN
static int	JAVA9_STRING_CODER_UTF16

Fields inherited from interface net.openhft.chronicle.core.io.ReferenceOwner

INIT, TMP

Method Summary

Modifier and Type	Method and Description
long	addressForRead(long offset) Retrieves the underlying memory address for reading.
default long	addressForRead(long offset, int buffer) Retrieves the underlying memory address for reading.
long	addressForWrite(long offset) Retrieves the underlying memory address for writing.
long	addressForWritePosition() Retrieves the underlying memory address for writing at the current write position.
default S	appendUtf8(byte[] bytes, int offset, int length) Appends a UTF-8 encoded byte array to this output stream, taking into account the provided offset and length.
default S	appendUtf8(byte[] bytes, int offset, int length, byte coder) Appends a UTF-8 encoded byte array to this output stream, taking into account the provided offset, length, and coder.
default S	appendUtf8(char[] chars, int offset, int length) Appends a UTF-8 encoded CharSequence to this output stream from a specific offset and length.
default S	appendUtf8(@NotNull CharSequence cs) Appends a UTF-8 encoded CharSequence to this output stream.
default S	appendUtf8(@NotNull CharSequence cs, int offset, int length) Appends a UTF-8 encoded CharSequence to this output stream from a specific offset and length.
default S	appendUtf8(int codepoint) Appends a UTF-8 encoded character to this output stream.
default ByteOrder	byteOrder() Retrieves the byte order used by the buffer.
@NotNull Bytes<?>	bytesForRead() Retrieves a Bytes object for reading.
@NotNull Bytes<?>	bytesForWrite() Retrieves a Bytes object for writing.
default boolean	canWriteDirect(long count) Determines if the buffer can write the specified count of bytes directly.
default long	capacity()
default void	copyFrom(@NotNull InputStream input) Copies data from the provided InputStream into this Bytes object.
void	ensureCapacity(long desiredCapacity) Ensures that the buffer has the desired capacity.
byte[]	internalNumberBuffer() Deprecated.
boolean	isDirectMemory() Checks if the buffer uses direct memory.
default long	lengthWritten(long startPosition) Calculates the length of data written from the given start position.
default @NotNull OutputStream	outputStream() Provides a view of this Bytes object as an OutputStream.
default S	rawWriteByte(byte i8) Writes a byte to the data stream without any additional checks or transformations.
default S	rawWriteInt(int i) Writes an integer to the data stream without any additional checks or transformations.
default S	rawWriteLong(long i) Writes a long integer to the data stream without performing a bounds check.
default long	readLimit() If the resource is closed, the returned value is unspecified.
default long	readPosition() Returns the read position.
default long	readRemaining() Calculates the number of bytes remaining that can be read from the current read position.
long	realCapacity() Returns the actual capacity of the buffer without resize.
default long	realReadRemaining() Calculates the number of bytes that can be safely read directly.
default long	realWriteRemaining() Calculates the number of bytes remaining that can be written from the current write position with resizing.
boolean	sharedMemory() Checks if the Bytes use shared memory.
default long	start()
default S	unsafeWrite(long address, int length) Writes raw native memory to this output stream.
default S	unsafeWriteObject(Object o, int length) Writes the memory content of an object to this output stream.
default S	unsafeWriteObject(Object o, int offset, int length) Writes the memory content of an object to this output stream from a specific offset.
default S	write(byte[] byteArray) Writes all the bytes from the given byteArray into the output stream.
S	write(byte[] byteArray, int offset, int length) Writes the specified number of bytes from the given byteArray into the output stream, starting from the given offset.
default S	write(@NotNull BytesStore<?,?> bytes) Writes all available data from the specified BytesStore into the output stream.
default S	write(@NotNull BytesStore<?,?> bytes, long readOffset, long length) Writes the specified number of bytes from the provided BytesStore into the output stream, starting from the given read offset.
default S	write(@NotNull CharSequence text) Writes the provided text to this StreamingDataOutput at the current writePosition().
default S	write(@NotNull CharSequence text, int startText, int length) Writes the provided text to this StreamingDataOutput at the current writePosition()
default S	write(@NotNull RandomDataInput bytes) Writes all available data from the specified RandomDataInput into the output stream.
default S	write(@NotNull RandomDataInput bytes, long readOffset, long length) Writes the specified number of bytes from the provided RandomDataInput object into the output stream, starting from the given read offset.
default S	write8bit(@Nullable CharSequence text) Writes a CharSequence as an 8-bit string to the data stream.
default S	write8bit(@NotNull CharSequence text, int start, int length) Writes a subsequence of a CharSequence as an 8-bit string to the data stream.
default S	write8bit(@Nullable String s) Writes a String as an 8-bit string to the data stream.
S	write8bit(@NotNull String text, int start, int length) Writes a subsequence of a String as an 8-bit string to the data stream.
default void	writeBigDecimal(@NotNull BigDecimal bd) Writes the given BigDecimal into this Bytes object.
default void	writeBigInteger(@NotNull BigInteger bi) Writes the given BigInteger into this Bytes object.
default S	writeBoolean(boolean flag) Writes a boolean value to this output stream.
S	writeByte(byte i8) Writes a byte to the data stream.
default S	writeChar(char ch) Writes a char to the data stream as a stop bit encoded value.
S	writeDouble(double d) Writes a double-precision floating-point number to the data stream.
S	writeDoubleAndInt(double d, int i) Writes a double-precision floating-point number followed by an integer to the data stream.
default <E extends Enum<E>> S	writeEnum(E e) Writes an enum value to this output stream by writing the enum's name.
S	writeFloat(float f) Writes a floating-point number to the data stream.
default void	writeHistogram(@NotNull net.openhft.chronicle.core.util.Histogram histogram) Writes the given Histogram object into this Bytes object.
S	writeInt(int i) Writes an integer to the data stream.
default S	writeInt24(int i) Writes a 24-bit integer to the data stream.
S	writeIntAdv(int i, int advance) Writes an integer to the data stream, then advances the write position by the specified amount.
default long	writeLimit() Retrieves the maximum writable position within the buffer.
S	writeLimit(long limit) Sets the limit for writing to the data stream.
S	writeLong(long i64) Writes a long integer to the data stream.
S	writeLongAdv(long i64, int advance) Writes a long integer to the data stream, then advances the write position by the specified amount.
S	writeOrderedInt(int i) Writes an integer value to this output stream using an ordered-writing mechanism.
S	writeOrderedLong(long i) Writes a long value to this output stream using an ordered-writing mechanism.
default long	writePosition() Returns the write position.
S	writePosition(long position) Sets the current write position in the data stream.
default long	writePositionForHeader(boolean skipPadding) Returns the current write position while optionally skipping any padding needed for a header.
default void	writePositionRemaining(long position, long length) Sets the write position and the remaining length of writable bytes in this Bytes object.
default long	writeRemaining() Calculates the number of bytes remaining that can be written from the current write position.
S	writeShort(short i16) Writes a short integer to the data stream.
S	writeSkip(long bytesToSkip) Skips a specified number of bytes from the current write position in the data stream.
S	writeSome(@NotNull ByteBuffer buffer) Writes the available data from the provided ByteBuffer into this Bytes object.
default S	writeSome(@NotNull Bytes<?> bytes) Deprecated. use write(bytes) instead and alter the bytes as you intended
default S	writeStopBit(char x) Writes a stop bit encoded char to the data stream.
default S	writeStopBit(double d) Writes a stop bit encoded double value to the data stream.
default S	writeStopBit(long x) Writes a stop bit encoded long to the data stream.
default S	writeStopBitDecimal(double d) Writes a double value to the data stream with a stop bit encoded decimal.
default S	writeUnsignedByte(int i) Writes an unsigned byte to the data stream.
default S	writeUnsignedInt(long i) Writes an unsigned integer to the data stream.
default S	writeUnsignedInt24(int i) Writes an unsigned 24-bit integer to the data stream.
default S	writeUnsignedShort(int u16) Writes an unsigned short integer to the data stream.
default S	writeUtf8(@Nullable CharSequence text) Writes a UTF-8 encoded string to the data stream, similar to writeUTF, but with a few differences.
default S	writeUtf8(@Nullable String text) Writes a UTF-8 encoded String to the data stream.
default void	writeWithLength(@NotNull RandomDataInput bytes) Writes data from the provided RandomDataInput into this Bytes object with prefixed length.

Methods inherited from interface net.openhft.chronicle.bytes.StreamingCommon

clear

Methods inherited from interface net.openhft.chronicle.core.io.ReferenceCounted

addReferenceChangeListener, refCount, release, releaseLast, releaseLast, removeReferenceChangeListener, reserve, reservedBy, reserveTransfer, tryReserve

Methods inherited from interface net.openhft.chronicle.core.io.ReferenceOwner

referenceId, referenceName, temporary

Field Detail

JAVA9_STRING_CODER_LATIN

static final int JAVA9_STRING_CODER_LATIN

See Also:

Constant Field Values

JAVA9_STRING_CODER_UTF16

static final int JAVA9_STRING_CODER_UTF16

See Also:

Constant Field Values

Method Detail

writePosition

@NotNull
S writePosition(long position)
                  throws BufferOverflowException

Sets the current write position in the data stream. The write position indicates the point where the next write operation will begin. Calling this method does not modify the data in the stream; it only changes the position where future write operations will take place.

Parameters:

position - The new write position. It must be a non-negative number.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if the specified position exceeds the limit of the data buffer.

writeLimit

@NotNull
S writeLimit(long limit)
               throws BufferOverflowException

Sets the limit for writing to the data stream. No data can be written beyond this limit. If an attempt is made to write data beyond this limit, a BufferOverflowException will be thrown.

Parameters:

limit - The new write limit. It must be a non-negative number.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if the specified limit is less than the current write position.

writeSkip

@NotNull
S writeSkip(long bytesToSkip)
              throws BufferOverflowException,
                     IllegalStateException

Skips a specified number of bytes from the current write position in the data stream. This method adjusts the write position either forward or backward based on the value of bytesToSkip. The new position should not exceed the write limit.

Parameters:

bytesToSkip - The number of bytes to skip. This can be a negative number to move the position backward.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if the new position calculated by the skip operation falls outside the limits of the data buffer.

IllegalStateException - if released

writePositionForHeader

default long writePositionForHeader(boolean skipPadding)

Returns the current write position while optionally skipping any padding needed for a header. The write position can be optionally aligned to a 4-byte boundary.

Parameters:

skipPadding - If true, aligns the write position to the next 4-byte boundary.

Returns:

The current write position after optional alignment.

outputStream

@NotNull
default @NotNull OutputStream outputStream()

Provides a view of this Bytes object as an OutputStream. Any data written to the returned OutputStream will be appended to this Bytes object.

Returns:

An OutputStream view of this Bytes object.

writeStopBit

@NotNull
default S writeStopBit(long x)
                         throws BufferOverflowException,
                                IllegalStateException

Writes a stop bit encoded long to the data stream. Stop bit encoding is a form of variable-length integer encoding that uses the continuation bit to indicate if there are more bytes to be processed.

Parameters:

x - The long value to be written to the data stream.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeStopBit

@NotNull
default S writeStopBit(char x)
                         throws BufferOverflowException,
                                IllegalStateException

Writes a stop bit encoded char to the data stream. Stop bit encoding is a form of variable-length integer encoding that uses the continuation bit to indicate if there are more bytes to be processed.

Parameters:

x - The char value to be written to the data stream.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeStopBit

@NotNull
default S writeStopBit(double d)
                         throws BufferOverflowException,
                                IllegalStateException

Writes a stop bit encoded double value to the data stream. Stop bit encoding is a form of variable-length integer encoding that uses the continuation bit to indicate if there are more bytes to be processed.

Parameters:

d - The double value to be written to the data stream.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeStopBitDecimal

@NotNull
default S writeStopBitDecimal(double d)
                                throws BufferOverflowException,
                                       IllegalStateException

Writes a double value to the data stream with a stop bit encoded decimal. The encoding used aims to efficiently store values with a small number of significant digits.

Parameters:

d - The double value to be written to the data stream.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeUtf8

@NotNull
default S writeUtf8(@Nullable
                             @Nullable CharSequence text)
                      throws BufferOverflowException,
                             IllegalStateException,
                             IllegalArgumentException,
                             BufferUnderflowException

Writes a UTF-8 encoded string to the data stream, similar to writeUTF, but with a few differences. Firstly, the length is stop bit encoded, meaning that the length encoding may be one byte longer for short strings, but the string's length is not limited. Secondly, the string can be null.

Parameters:

text - The string to be written. Can be null.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

IllegalArgumentException

BufferUnderflowException

writeUtf8

@NotNull
default S writeUtf8(@Nullable
                             @Nullable String text)
                      throws BufferOverflowException,
                             IllegalStateException,
                             BufferUnderflowException,
                             IllegalArgumentException

Writes a UTF-8 encoded String to the data stream. This method is functionally similar to writeUtf8(CharSequence), but it specifically accepts a String as an argument.

Parameters:

text - The string to be written. Can be null.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

BufferUnderflowException

IllegalArgumentException

write8bit

@NotNull
default S write8bit(@Nullable
                             @Nullable CharSequence text)
                      throws BufferOverflowException,
                             ArithmeticException,
                             IllegalStateException,
                             BufferUnderflowException

Writes a CharSequence as an 8-bit string to the data stream. If the CharSequence is null, a stop bit encoded -1 is written. If the CharSequence is an instance of BytesStore, the contents are written directly from the BytesStore. Otherwise, the method delegates to the write8bit(String) or write8bit(CharSequence, int, int) as appropriate.

Parameters:

text - The CharSequence to be written. Can be null.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

ArithmeticException

BufferUnderflowException

write8bit

@NotNull
default S write8bit(@NotNull
                             @NotNull CharSequence text,
                             int start,
                             int length)
                      throws BufferOverflowException,
                             IndexOutOfBoundsException,
                             ArithmeticException,
                             IllegalStateException,
                             BufferUnderflowException

Writes a subsequence of a CharSequence as an 8-bit string to the data stream. If the CharSequence is an instance of String, the method delegates to the write8bit(String, int, int).

Parameters:

text - The CharSequence to be written.

start - The index of the first char in the CharSequence to write.

length - The number of chars from the CharSequence to write.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

IndexOutOfBoundsException

ArithmeticException

BufferUnderflowException

write8bit

@NotNull
S write8bit(@NotNull
                     @NotNull String text,
                     int start,
                     int length)

Writes a subsequence of a String as an 8-bit string to the data stream. This method is to be implemented by concrete subclasses.

Parameters:

text - The String to be written.

start - The index of the first char in the String to write.

length - The number of chars from the String to write.

Returns:

The current StreamingDataOutput instance.

write

@NotNull
default S write(@NotNull
                         @NotNull CharSequence text)
                  throws BufferOverflowException,
                         IndexOutOfBoundsException,
                         IllegalStateException

Writes the provided text to this StreamingDataOutput at the current writePosition().

Parameters:

text - to write

Returns:

this StreamingDataOutput

Throws:

BufferOverflowException - if the provided text cannot be accommodated.

IllegalStateException - if this StreamingDataOutput has been previously released.

IllegalArgumentException - if the provided text is null.

IndexOutOfBoundsException

write

@NotNull
default S write(@NotNull
                         @NotNull CharSequence text,
                         int startText,
                         int length)
                  throws BufferOverflowException,
                         IndexOutOfBoundsException,
                         IllegalStateException

Writes the provided text to this StreamingDataOutput at the current writePosition()

Parameters:

text - to write

startText - offset from where text should be copied from

length - number of characters to write.

Returns:

this StreamingDataOutput

Throws:

BufferOverflowException - if the provided text cannot be accommodated.

IllegalStateException - if this StreamingDataOutput has been previously released.

NullPointerException - if the provided text is null.

IllegalArgumentException - if the provided startText or the provided length is negative.

IndexOutOfBoundsException

write8bit

@NotNull
default S write8bit(@Nullable
                             @Nullable String s)
                      throws BufferOverflowException,
                             ArithmeticException,
                             IllegalStateException

Writes a String as an 8-bit string to the data stream. If the string is null, a stop bit encoded -1 is written. Otherwise, the method delegates to the write8bit(String, int, int) method.

Parameters:

s - The String to be written. Can be null.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

ArithmeticException

writeByte

@NotNull
S writeByte(byte i8)
              throws BufferOverflowException,
                     IllegalStateException

Writes a byte to the data stream.

Parameters:

i8 - The byte to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

rawWriteByte

default S rawWriteByte(byte i8)
                throws BufferOverflowException,
                       IllegalStateException

Writes a byte to the data stream without any additional checks or transformations.

Parameters:

i8 - The byte to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeUnsignedByte

@NotNull
default S writeUnsignedByte(int i)
                              throws BufferOverflowException,
                                     ArithmeticException,
                                     IllegalStateException

Writes an unsigned byte to the data stream. The input integer is converted to an unsigned byte using Maths.toUInt8(int) before being written.

Parameters:

i - The integer to be written as an unsigned byte.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

ArithmeticException

writeChar

@NotNull
default S writeChar(char ch)
                      throws BufferOverflowException,
                             IllegalStateException

Writes a char to the data stream as a stop bit encoded value.

Parameters:

ch - The char to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeShort

@NotNull
S writeShort(short i16)
               throws BufferOverflowException,
                      IllegalStateException

Writes a short integer to the data stream.

Parameters:

i16 - The short integer to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeUnsignedShort

@NotNull
default S writeUnsignedShort(int u16)
                               throws BufferOverflowException,
                                      ArithmeticException,
                                      IllegalStateException

Writes an unsigned short integer to the data stream. The input integer is converted to an unsigned short using Maths.toUInt16(int) before being written.

Parameters:

u16 - The integer to be written as an unsigned short.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

ArithmeticException

writeInt24

@NotNull
default S writeInt24(int i)
                       throws BufferOverflowException,
                              ArithmeticException,
                              IllegalStateException

Writes a 24-bit integer to the data stream. The integer is split into a 16-bit short and an 8-bit byte.

Parameters:

i - The integer to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

ArithmeticException

writeUnsignedInt24

@NotNull
default S writeUnsignedInt24(int i)
                               throws BufferOverflowException,
                                      ArithmeticException,
                                      IllegalStateException

Writes an unsigned 24-bit integer to the data stream. The integer is split into a 16-bit short and an 8-bit byte.

Parameters:

i - The integer to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

ArithmeticException

writeInt

@NotNull
S writeInt(int i)
             throws BufferOverflowException,
                    IllegalStateException

Writes an integer to the data stream.

Parameters:

i - The integer to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

rawWriteInt

default S rawWriteInt(int i)
               throws BufferOverflowException,
                      IllegalStateException

Writes an integer to the data stream without any additional checks or transformations.

Parameters:

i - The integer to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeIntAdv

@NotNull
S writeIntAdv(int i,
                       int advance)
                throws BufferOverflowException,
                       IllegalStateException

Writes an integer to the data stream, then advances the write position by the specified amount.

Parameters:

i - The integer to be written.

advance - The number of bytes to advance the write position after the integer has been written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeUnsignedInt

@NotNull
default S writeUnsignedInt(long i)
                             throws BufferOverflowException,
                                    ArithmeticException,
                                    IllegalStateException

Writes an unsigned integer to the data stream. The input long is converted to an unsigned integer using Maths.toUInt32(long) before being written.

Parameters:

i - The long to be written as an unsigned integer.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

ArithmeticException

writeLong

@NotNull
S writeLong(long i64)
              throws BufferOverflowException,
                     IllegalStateException

Writes a long integer to the data stream.

Parameters:

i64 - The long integer to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

rawWriteLong

default S rawWriteLong(long i)
                throws BufferOverflowException,
                       IllegalStateException

Writes a long integer to the data stream without performing a bounds check.

Parameters:

i - The long integer to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeLongAdv

@NotNull
S writeLongAdv(long i64,
                        int advance)
                 throws BufferOverflowException,
                        IllegalStateException

Writes a long integer to the data stream, then advances the write position by the specified amount.

Parameters:

i64 - The long integer to be written.

advance - The number of bytes to advance the write position after the long integer has been written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeFloat

@NotNull
S writeFloat(float f)
               throws BufferOverflowException,
                      IllegalStateException

Writes a floating-point number to the data stream.

Parameters:

f - The floating-point number to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeDouble

@NotNull
S writeDouble(double d)
                throws BufferOverflowException,
                       IllegalStateException

Writes a double-precision floating-point number to the data stream.

Parameters:

d - The double-precision floating-point number to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

writeDoubleAndInt

@NotNull
S writeDoubleAndInt(double d,
                             int i)
                      throws BufferOverflowException,
                             IllegalStateException

Writes a double-precision floating-point number followed by an integer to the data stream.

Parameters:

d - The double-precision floating-point number to be written.

i - The integer to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is insufficient space in the buffer.

IllegalStateException - if released

write

@NotNull
default S write(@NotNull
                         @NotNull RandomDataInput bytes)
                  throws BufferOverflowException,
                         IllegalStateException

Writes all available data from the specified RandomDataInput into the output stream. The position of this output stream is updated accordingly, but the read position of the input data is not changed. The operation will fail if there is not enough space left in the output stream.

Parameters:

bytes - the RandomDataInput from which data is read.

Returns:

The current StreamingDataOutput instance.

Throws:

IllegalArgumentException - if the provided bytes is null.

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if released

write

default S write(@NotNull
                @NotNull BytesStore<?,?> bytes)
         throws BufferOverflowException,
                IllegalStateException

Writes all available data from the specified BytesStore into the output stream. The position of this output stream is updated accordingly, but the read position of the input data is not changed. The operation will fail if there is not enough space left in the output stream.

Parameters:

bytes - the BytesStore from which data is read.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if released

See Also:

StreamingDataInput.read(Bytes)

ensureCapacity

void ensureCapacity(long desiredCapacity)
             throws DecoratedBufferOverflowException,
                    IllegalStateException

Ensures that the buffer has the desired capacity. If the buffer is elastic, it will grow to accommodate the requested capacity. If the buffer is not elastic and there is insufficient space, a DecoratedBufferOverflowException will be thrown.

Parameters:

desiredCapacity - the required capacity.

Throws:

IllegalStateException - if released

DecoratedBufferOverflowException - if the buffer is not elastic and lacks sufficient space, or if the provided desiredCapacity is negative.

realCapacity

long realCapacity()

Returns the actual capacity of the buffer without resize. If the buffer is closed, this method returns -1.

Returns:

the actual capacity of the buffer or -1 if the buffer is closed.

canWriteDirect

default boolean canWriteDirect(long count)

Determines if the buffer can write the specified count of bytes directly. The default implementation always returns false. Override this method in sub-classes to provide specific implementation.

Parameters:

count - the number of bytes to write.

Returns:

true if the buffer can write the specified count of bytes directly, false otherwise.

writeSome

@Deprecated
 @NotNull
default S writeSome(@NotNull
                                          @NotNull Bytes<?> bytes)
                                   throws IllegalStateException

Deprecated. use write(bytes) instead and alter the bytes as you intended

Writes data from the specified Bytes object into the output stream. The amount of data written is the minimum of the remaining data in the Bytes object and the remaining space in the output stream. The position of this output stream is updated accordingly, but the read position of the input data is not changed.

Parameters:

bytes - the Bytes object from which data is read.

Returns:

The current StreamingDataOutput instance.

Throws:

IllegalStateException - if released

write

@NotNull
default S write(@NotNull
                         @NotNull RandomDataInput bytes,
                         long readOffset,
                         long length)
                  throws BufferOverflowException,
                         BufferUnderflowException,
                         IllegalStateException,
                         IllegalArgumentException

Writes the specified number of bytes from the provided RandomDataInput object into the output stream, starting from the given read offset. The position of this output stream is updated accordingly, but the read position of the input data is not changed.

Parameters:

bytes - the RandomDataInput from which data is read.

readOffset - the offset at which reading from the RandomDataInput starts.

length - the number of bytes to write.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

BufferUnderflowException - if there is not enough data available in the input.

IllegalStateException - if released

IllegalArgumentException - if the readOffset or length are invalid.

write

@NotNull
default S write(@NotNull
                         @NotNull BytesStore<?,?> bytes,
                         long readOffset,
                         long length)
                  throws BufferOverflowException,
                         BufferUnderflowException,
                         IllegalStateException,
                         IllegalArgumentException

Writes the specified number of bytes from the provided BytesStore into the output stream, starting from the given read offset. It ensures that the output stream has enough capacity to accommodate the incoming bytes. The position of this output stream is updated accordingly, but the read position of the input data is not changed.

Parameters:

bytes - the BytesStore from which data is read.

readOffset - the offset at which reading from the BytesStore starts.

length - the number of bytes to write.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

BufferUnderflowException - if there is not enough data available in the input.

IllegalStateException - if released

IllegalArgumentException - if the readOffset or length are invalid.

NullPointerException - if the provided bytes object is null.

write

@NotNull
default S write(byte[] byteArray)
                  throws BufferOverflowException,
                         IllegalStateException

Writes all the bytes from the given byteArray into the output stream. The position of the output stream is updated according to the number of bytes written.

Parameters:

byteArray - the array of bytes to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if released

NullPointerException - if the provided byteArray is null.

write

@NotNull
S write(byte[] byteArray,
                 int offset,
                 int length)
          throws BufferOverflowException,
                 IllegalStateException,
                 IllegalArgumentException,
                 ArrayIndexOutOfBoundsException

Writes the specified number of bytes from the given byteArray into the output stream, starting from the given offset. The position of the output stream is updated according to the number of bytes written.

Parameters:

byteArray - the array of bytes to be written.

offset - the start index in the array from where to start writing bytes.

length - the number of bytes to write.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if released

IllegalArgumentException - if the provided offset or length is negative

NullPointerException - if the provided byteArray is null

ArrayIndexOutOfBoundsException - if the provided offset and length combination is invalid.

unsafeWriteObject

default S unsafeWriteObject(Object o,
                            int length)
                     throws BufferOverflowException,
                            IllegalStateException

Writes the memory content of an object to this output stream.

Parameters:

o - The object whose memory content is to be written.

length - The length (in bytes) of the object's content to write.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if the buffer is in an invalid state.

unsafeWriteObject

default S unsafeWriteObject(Object o,
                            int offset,
                            int length)
                     throws BufferOverflowException,
                            IllegalStateException

Writes the memory content of an object to this output stream from a specific offset.

Parameters:

o - The object whose memory content is to be written.

offset - The offset in bytes from the start of the object's content to begin writing from.

length - The length (in bytes) of the object's content to write.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if the buffer is in an invalid state.

unsafeWrite

default S unsafeWrite(long address,
                      int length)

Writes raw native memory to this output stream.

Parameters:

address - The address of the raw memory to write.

length - The length (in bytes) of the raw memory to write.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if the buffer is in an invalid state.

writeSome

@NotNull
S writeSome(@NotNull
                     @NotNull ByteBuffer buffer)
              throws BufferOverflowException,
                     IllegalStateException,
                     BufferUnderflowException

Writes the available data from the provided ByteBuffer into this Bytes object. The number of bytes written is constrained by the space available in this Bytes object. The position of this Bytes object is updated according to the number of bytes written.

Parameters:

buffer - the ByteBuffer from which data is read.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if the buffer is in an invalid state.

BufferUnderflowException - if there is not enough data available in the input ByteBuffer.

NullPointerException - if the provided buffer is null.

writeBoolean

@NotNull
default S writeBoolean(boolean flag)
                         throws BufferOverflowException,
                                IllegalStateException

Writes a boolean value to this output stream.

Parameters:

flag - The boolean value to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if the buffer is in an invalid state.

writeOrderedInt

@NotNull
S writeOrderedInt(int i)
                    throws BufferOverflowException,
                           IllegalStateException

Writes an integer value to this output stream using an ordered-writing mechanism. Ordered writing ensures that the integer is written with a write memory barrier.

Parameters:

i - The integer value to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if the buffer is in an invalid state.

writeOrderedLong

@NotNull
S writeOrderedLong(long i)
                     throws BufferOverflowException,
                            IllegalStateException

Writes a long value to this output stream using an ordered-writing mechanism. Ordered writing ensures that the integer is written with a write memory barrier.

Parameters:

i - The long value to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if the buffer is in an invalid state.

writeEnum

default <E extends Enum<E>> S writeEnum(@NotNull
                                        E e)
                                 throws BufferOverflowException,
                                        ArithmeticException,
                                        IllegalStateException

Writes an enum value to this output stream by writing the enum's name.

Parameters:

e - The enum value to be written.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

ArithmeticException - if a numeric error occurs.

IllegalStateException - if the buffer is in an invalid state.

appendUtf8

@NotNull
default S appendUtf8(@NotNull
                              @NotNull CharSequence cs)
                       throws BufferOverflowException,
                              IllegalStateException,
                              BufferUnderflowException

Appends a UTF-8 encoded CharSequence to this output stream.

Parameters:

cs - The CharSequence to be appended.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if the buffer is in an invalid state.

BufferUnderflowException - if there is not enough data available in the input CharSequence.

appendUtf8

@NotNull
default S appendUtf8(int codepoint)
                       throws BufferOverflowException,
                              IllegalStateException

Appends a UTF-8 encoded character to this output stream.

Parameters:

codepoint - The Unicode code point of the character to be appended.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if the buffer is in an invalid state.

appendUtf8

@NotNull
default S appendUtf8(char[] chars,
                              int offset,
                              int length)
                       throws BufferOverflowException,
                              IllegalStateException,
                              BufferUnderflowException,
                              IllegalArgumentException

Appends a UTF-8 encoded CharSequence to this output stream from a specific offset and length.

Parameters:

chars - The CharSequence to be appended.

offset - The offset from which to start writing the CharSequence.

length - The number of characters from the CharSequence to write.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IndexOutOfBoundsException - if the offset or length is out of bounds for the given CharSequence.

IllegalStateException - if the buffer is in an invalid state.

BufferUnderflowException - if there is not enough data available in the input CharSequence.

IllegalArgumentException

appendUtf8

@NotNull
default S appendUtf8(@NotNull
                              @NotNull CharSequence cs,
                              int offset,
                              int length)
                       throws BufferOverflowException,
                              IndexOutOfBoundsException,
                              IllegalStateException,
                              BufferUnderflowException

Appends a UTF-8 encoded CharSequence to this output stream from a specific offset and length.

Parameters:

cs - The CharSequence to be appended.

offset - The offset from which to start writing the CharSequence.

length - The number of characters from the CharSequence to write.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IndexOutOfBoundsException - if the offset or length is out of bounds for the given CharSequence.

IllegalStateException - if the buffer is in an invalid state.

BufferUnderflowException - if there is not enough data available in the input CharSequence.

appendUtf8

@NotNull
default S appendUtf8(byte[] bytes,
                              int offset,
                              int length,
                              byte coder)
                       throws BufferOverflowException,
                              IllegalStateException

Appends a UTF-8 encoded byte array to this output stream, taking into account the provided offset, length, and coder.

Parameters:

bytes - The byte array to be appended.

offset - The offset from which to start writing the byte array.

length - The number of characters (not bytes) from the byte array to write.

coder - The coder indicating the encoding of the byte array.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if the buffer is in an invalid state.

appendUtf8

@NotNull
default S appendUtf8(byte[] bytes,
                              int offset,
                              int length)
                       throws BufferOverflowException,
                              IllegalStateException

Appends a UTF-8 encoded byte array to this output stream, taking into account the provided offset and length.

Parameters:

bytes - The byte array to be appended.

offset - The offset from which to start writing the byte array.

length - The length of the byte array to write.

Returns:

The current StreamingDataOutput instance.

Throws:

BufferOverflowException - if there is not enough space left in the output stream.

IllegalStateException - if the buffer is in an invalid state.

copyFrom

default void copyFrom(@NotNull
                      @NotNull InputStream input)
               throws IOException,
                      BufferOverflowException,
                      IllegalStateException

Copies data from the provided InputStream into this Bytes object.

Parameters:

input - The InputStream from which data should be copied.

Throws:

IOException - if an I/O error occurs when reading from the InputStream.

BufferOverflowException - if there is not enough space in this Bytes object to store the incoming data.

IllegalStateException - if this Bytes object is in an invalid state.

writePositionRemaining

default void writePositionRemaining(long position,
                                    long length)
                             throws BufferOverflowException

Sets the write position and the remaining length of writable bytes in this Bytes object.

Parameters:

position - The new write position.

length - The new length of writable bytes remaining.

Throws:

BufferOverflowException - if the provided position and length exceeds the size of the buffer.

writeHistogram

default void writeHistogram(@NotNull
                            @NotNull net.openhft.chronicle.core.util.Histogram histogram)
                     throws BufferOverflowException,
                            IllegalStateException

Writes the given Histogram object into this Bytes object.

Parameters:

histogram - The Histogram object to be written.

Throws:

BufferOverflowException - if there is not enough space in this Bytes object to store the Histogram.

IllegalStateException - if this Bytes object is in an invalid state.

writeBigDecimal

default void writeBigDecimal(@NotNull
                             @NotNull BigDecimal bd)
                      throws BufferOverflowException,
                             IllegalStateException,
                             IllegalArgumentException

Writes the given BigDecimal into this Bytes object.

Parameters:

bd - The BigDecimal object to be written.

Throws:

BufferOverflowException - if there is not enough space in this Bytes object to store the BigDecimal.

IllegalStateException - if this Bytes object is in an invalid state.

IllegalArgumentException - if the BigDecimal cannot be written.

writeBigInteger

default void writeBigInteger(@NotNull
                             @NotNull BigInteger bi)
                      throws BufferOverflowException,
                             IllegalStateException,
                             IllegalArgumentException

Writes the given BigInteger into this Bytes object.

Parameters:

bi - The BigInteger object to be written.

Throws:

BufferOverflowException - if there is not enough space in this Bytes object to store the BigInteger.

IllegalStateException - if this Bytes object is in an invalid state.

IllegalArgumentException - if the BigInteger cannot be written.

writeWithLength

default void writeWithLength(@NotNull
                             @NotNull RandomDataInput bytes)
                      throws BufferOverflowException,
                             IllegalStateException

Writes data from the provided RandomDataInput into this Bytes object with prefixed length.

Parameters:

bytes - The RandomDataInput source of data to be written.

Throws:

BufferOverflowException - if there is not enough space in this Bytes object to store the incoming data.

IllegalStateException - if this Bytes object is in an invalid state.

internalNumberBuffer

@Deprecated
byte[] internalNumberBuffer()

Deprecated.

start

default long start()

Returns:

The smallest position allowed in this buffer.

capacity

default long capacity()

Returns:

the highest limit allowed for this buffer.

readPosition

default long readPosition()

Returns the read position.

The read position is start() <= readPosition() && readPosition() <= readLimit() && readPosition < safeLimit()

If the resource is closed, the returned value is unspecified.

Returns:

position to read from.

writePosition

default long writePosition()

Returns the write position.

The write position is readPosition() <= writePosition() && writePosition() <= writeLimit()

If the resource is closed, the returned value is unspecified.

Returns:

position to write to.

lengthWritten

default long lengthWritten(long startPosition)

Calculates the length of data written from the given start position.

Typically this calculates the difference however for HexDumpBytes it's not as simple.

If the resource is closed, the returned value is unspecified.

Parameters:

startPosition - The position to calculate the length from.

Returns:

The length of data written from the given start position.

readRemaining

default long readRemaining()

Calculates the number of bytes remaining that can be read from the current read position.

If the resource is closed, the returned value is unspecified.

Returns:

The number of bytes that can still be read.

realReadRemaining

default long realReadRemaining()

Calculates the number of bytes that can be safely read directly.

If the resource is closed, the returned value is unspecified.

Returns:

The number of bytes that can be safely read directly.

writeRemaining

default long writeRemaining()

Calculates the number of bytes remaining that can be written from the current write position.

If the resource is closed, the returned value is unspecified.

Returns:

The number of bytes that can still be written.

realWriteRemaining

default long realWriteRemaining()

Calculates the number of bytes remaining that can be written from the current write position with resizing.

If the resource is closed, the returned value is unspecified.

Returns:

The number of bytes that can still be written with resizing.

readLimit

default long readLimit()

If the resource is closed, the returned value is unspecified.

Returns:

the highest offset or position allowed for this buffer.

writeLimit

default long writeLimit()

Retrieves the maximum writable position within the buffer.

If the resource is closed, the returned value is unspecified.

Returns:

the write limit

addressForRead

long addressForRead(long offset)
             throws UnsupportedOperationException,
                    BufferUnderflowException,
                    IllegalStateException

Retrieves the underlying memory address for reading. This is for expert users only.

Parameters:

offset - within this buffer. addressForRead(start()) is the actual addressForRead of the first byte.

Returns:

the underlying addressForRead of the buffer

Throws:

UnsupportedOperationException - if the underlying buffer is on the heap

BufferUnderflowException - if the offset is before the start() or the after the capacity()

IllegalStateException - if the buffer has been closed.

addressForRead

default long addressForRead(long offset,
                            int buffer)
                     throws UnsupportedOperationException,
                            BufferUnderflowException,
                            IllegalStateException

Retrieves the underlying memory address for reading. This is for expert users only.

Parameters:

offset - The offset within this buffer.

buffer - The buffer index.

Returns:

The underlying memory address for reading at the specified offset.

Throws:

UnsupportedOperationException - if the underlying buffer is on the heap.

BufferUnderflowException - if the offset is before the start or after the capacity.

IllegalStateException - if the buffer has been closed.

addressForWrite

long addressForWrite(long offset)
              throws UnsupportedOperationException,
                     BufferOverflowException,
                     IllegalStateException

Retrieves the underlying memory address for writing. This is for expert users only.

Parameters:

offset - within this buffer. addressForRead(start()) is the actual addressForRead of the first byte.

Returns:

the underlying addressForRead of the buffer

Throws:

UnsupportedOperationException - if the underlying buffer is on the heap

BufferOverflowException - if the offset is before the start() or the after the capacity()

IllegalStateException

addressForWritePosition

long addressForWritePosition()
                      throws UnsupportedOperationException,
                             BufferOverflowException,
                             IllegalStateException

Retrieves the underlying memory address for writing at the current write position. This is for expert users only.

Returns:

The underlying memory address for writing at the current write position.

Throws:

UnsupportedOperationException - if the underlying buffer is on the heap.

BufferOverflowException - if the current write position is before the start or after the capacity.

IllegalStateException - if the buffer state doesn't allow the operation.

byteOrder

default ByteOrder byteOrder()

Retrieves the byte order used by the buffer.

Returns:

The byte order used by the buffer.

bytesForRead

@NotNull
@NotNull Bytes<?> bytesForRead()
                                 throws IllegalStateException

Retrieves a Bytes object for reading.

Returns:

A Bytes object for reading.

Throws:

IllegalStateException - if the buffer state doesn't allow the operation.

bytesForWrite

@NotNull
@NotNull Bytes<?> bytesForWrite()
                                  throws IllegalStateException

Retrieves a Bytes object for writing.

Returns:

A Bytes object for writing.

Throws:

IllegalStateException - if the buffer state doesn't allow the operation.

sharedMemory

boolean sharedMemory()

Checks if the Bytes use shared memory.

Returns:

True if the Bytes use shared memory, false otherwise.

isDirectMemory

boolean isDirectMemory()

Checks if the buffer uses direct memory.

Returns:

True if the buffer uses direct memory, false otherwise.