U - The type of the BytesStore that backs this Bytes instance.public interface Bytes<U> extends BytesStore<Bytes<U>,U>, BytesIn<U>, BytesOut<U>, net.openhft.chronicle.core.io.SingleThreadedChecked
Bytes class is a versatile container for raw byte data, providing rich functionality to read and write
data in various formats including integers, longs, floating-point values, strings, and more. It also supports
advanced operations such as seeking, slicing, and copying.
This class serves as an abstraction layer over a ByteBuffer, byte[], POJO, or native memory
Besides basic primitive types, Bytes can serialize and deserialize more complex structures,
including custom user-defined objects that implement ReadBytesMarshallable or WriteBytesMarshallable.
Bytes can be used for a variety of purposes such as:
Bytes is essentially a view of a region within a BytesStore and is equipped with separate read and
write cursors, boasting a 63-bit addressing capacity (approximately 8 EiB), as opposed to Java's built-in
ByteBuffer, which only supports 31-bit addressing with a single cursor.
A Bytes instance can represent either a fixed region of memory or an elastic buffer that dynamically
resizes as needed. It is mutable and designed for single-threaded use as it is not thread-safe.
The cursors within Bytes consist of a write-position and a read-position, which must adhere to these constraints:
start() <= readPosition() <= writePosition() <= writeLimit() <= capacity()readLimit() == writePosition() && readPosition() <= safeLimit()
It is important to note that a Bytes object is a resource that is ReferenceCounted. Operations on a Bytes
object that has been released may result in an IllegalStateException.
Note: Some operations on Bytes may throw IllegalStateException if the underlying storage has been released.
Always ensure proper release of resources when finished with a Bytes instance, especially if it's backed by system resources
like file handles or network sockets.
BytesStore,
ReadBytesMarshallable,
WriteBytesMarshallable| Modifier and Type | Field and Description |
|---|---|
static int |
DEFAULT_BYTE_BUFFER_CAPACITY
The default initial size of an elastic Bytes object backed by a ByteBuffer, which is 256 bytes.
|
static long |
MAX_CAPACITY
The maximum capacity a Bytes object can have, approximately 8 EiB (Exbibytes) minus 16 bytes.
|
static int |
MAX_HEAP_CAPACITY
The maximum capacity a Bytes object can have if it is allocated on the heap, which is 2 GiB (Gibibytes) minus 16 bytes.
|
charToStringJAVA9_STRING_CODER_LATIN, JAVA9_STRING_CODER_UTF16| Modifier and Type | Method and Description |
|---|---|
static @NotNull VanillaBytes |
allocateDirect(byte[] bytes)
Creates and returns a new fix sized wrapper for native (64-bit address)
memory with the contents copied from the given
bytes array. |
static @NotNull VanillaBytes<Void> |
allocateDirect(long capacity)
Creates and returns a new
VanillaBytes object that is a fixed-size wrapper for native memory
(accessible via 64-bit addresses) with the specified capacity. |
static @NotNull NativeBytes<Void> |
allocateElasticDirect()
Creates and returns a new elastic wrapper for native memory (accessible via 64-bit addresses)
with an initial capacity of zero bytes.
|
static @NotNull NativeBytes<Void> |
allocateElasticDirect(long initialCapacity)
Creates and returns a new elastic wrapper for native memory (accessible via 64-bit addresses)
with the given
initialCapacity. |
static @NotNull OnHeapBytes |
allocateElasticOnHeap()
Creates and returns a new elastic wrapper for memory allocated on the heap,
with an initial capacity of 32 bytes.
|
static @NotNull OnHeapBytes |
allocateElasticOnHeap(int initialCapacity)
Creates and returns a new elastic wrapper for memory allocated on the heap,
with the specified
initialCapacity. |
default @NotNull Bytes<U> |
bytesForRead()
Creates and returns a new slice of this Bytes object with its start position set to the current
read position and its capacity determined by the current limit.
|
default @NotNull Bytes<U> |
bytesForWrite()
Creates and returns a Bytes object that wraps the bytesStore of this Bytes object,
ranging from the
start position to the realCapacity. |
@Nullable BytesStore |
bytesStore()
Returns the backing BytesStore that this Bytes object wraps.
|
@NotNull Bytes<U> |
clear()
Clears the content of this Bytes object and resets its state.
|
@NotNull Bytes<U> |
compact()
Compacts this Bytes object by moving the read position to the start.
|
BytesStore<Bytes<U>,U> |
copy()
Creates and returns a deep copy of this Bytes object, including the data between
RandomCommon.readPosition() and RandomCommon.readLimit(). |
default long |
copyTo(@NotNull BytesStore targetByteStore)
Copies bytes from this Bytes object into the provided
targetByteStore. |
default void |
copyTo(@NotNull OutputStream outputStream)
Copies bytes from this Bytes object to the provided
outputStream. |
static @NotNull Bytes<byte[]> |
directFrom(@NotNull String text)
Constructs and returns a new Bytes instance which contains the provided
text encoded in ISO-8859-1. |
static @NotNull Bytes<ByteBuffer> |
elasticByteBuffer()
Creates and returns a new elastic wrapper for a direct (off-heap) ByteBuffer with a default capacity,
which can be resized as needed.
|
static @NotNull Bytes<ByteBuffer> |
elasticByteBuffer(int initialCapacity)
Creates and returns a new elastic wrapper for a direct (off-heap) ByteBuffer with
the given
initialCapacity which will be resized as required. |
static @NotNull Bytes<ByteBuffer> |
elasticByteBuffer(int initialCapacity,
int maxCapacity)
Creates and returns a new elastic wrapper for a direct (off-heap) ByteBuffer with
the given
initialCapacity which will be resized as required up
to the given maxCapacity. |
static @NotNull Bytes<ByteBuffer> |
elasticHeapByteBuffer()
Creates and returns a new elastic wrapper for a heap ByteBuffer with a default
initialCapacity
of 128 bytes, that can dynamically resize as required. |
static @NotNull Bytes<ByteBuffer> |
elasticHeapByteBuffer(int initialCapacity)
Creates and returns a new elastic wrapper for a heap ByteBuffer, with the provided
initialCapacity,
that can dynamically resize as required. |
static Bytes<?> |
empty()
Creates and returns an empty, fixed-size, immutable object.
|
default void |
ensureCapacity(long desiredCapacity)
Ensures that this Bytes object has the capacity to accommodate the specified amount of data.
|
static <T> Bytes<T> |
forFieldGroup(T object,
@NotNull String groupName)
Creates and returns a new Bytes view that maps to a group of fields within the provided
object. |
static @NotNull Bytes<byte[]> |
from(@NotNull CharSequence text)
Constructs and returns a new Bytes instance which contains the provided
text encoded in ISO-8859-1. |
static @NotNull Bytes<byte[]> |
from(@NotNull String text)
Creates and returns a new object containing the given
text encoded in ISO-8859-1 character set. |
static Bytes<Void> |
fromDirect(@NotNull CharSequence text)
Constructs and returns a new Bytes instance which contains the provided
text encoded in ISO-8859-1. |
static @NotNull Bytes<?> |
fromHexString(@NotNull String s)
Converts a hexadecimal string, generated by one of the
toHexString methods, back into a Bytes object. |
default long |
indexOf(@NotNull Bytes source)
Returns the index within this Bytes object of the first occurrence of the specified
sub-bytes represented by the
source Bytes object. |
default int |
indexOf(@NotNull BytesStore source,
int fromIndex)
Returns the lowest index value starting from the provided
fromIndex for which the contents of this
Bytes object equals the provided source , or -1 if no such index value exists. |
default boolean |
isClear()
Returns if the
readPosition is at the start and
the writeLimit is at the end. |
boolean |
isElastic()
Checks if this Bytes object is elastic, meaning it can dynamically resize when more data is written
than its current
realCapacity(). |
default boolean |
isEqual(@Nullable String other)
Compares the contents of this Bytes object with the provided
other string for equality. |
default <T extends ReadBytesMarshallable> |
readMarshallableLength16(@NotNull Class<T> clazz,
T using)
Reads the content of this Bytes object and converts it into an instance of the specified class.
|
default void |
readWithLength(long length,
@NotNull BytesOut<U> bytesOut)
Writes the specified number of bytes from this Bytes object into the provided
bytesOut. |
default boolean |
readWrite()
Checks if this Bytes object supports both reading and writing.
|
default long |
realCapacity()
Returns the actual capacity of the ByteStore before any resizing occurs.
|
default long |
safeLimit() |
default boolean |
sharedMemory()
Determines whether this Bytes object is backed by memory that can be shared across multiple
processes.
|
default @NotNull String |
toHexString()
Creates and returns a new String representing the contents of this Bytes object in hexadecimal form,
with comments describing the meaning of the bytes.
|
default @NotNull String |
toHexString(long maxLength)
Creates and returns a new String representing the contents of this Bytes object in hexadecimal form,
with comments describing the meaning of the bytes.
|
default @NotNull String |
toHexString(long offset,
long maxLength)
Creates and returns a new String representing the contents of this Bytes object in hexadecimal form,
with comments describing the meaning of the bytes.
|
static @NotNull String |
toString(@NotNull Bytes<?> buffer)
Creates and returns a substring from the provided
buffer between its current
readPosition and readLimit. |
static @NotNull String |
toString(@NotNull Bytes<?> buffer,
long maxLen)
Creates and returns a substring from the provided
buffer between its current
readPosition and readLimit, truncated to the specified maximum length. |
static @NotNull String |
toString(@NotNull Bytes<?> buffer,
long position,
long length)
Extracts a string from the provided
buffer starting at the specified position,
and spanning for the specified length number of characters. |
default boolean |
unchecked()
Checks whether this Bytes object operates in an unchecked mode.
|
default @NotNull Bytes<U> |
unchecked(boolean unchecked)
Creates and returns a new Bytes which is optionally unchecked as indicated by the provided
unchecked. |
default void |
unwrite(long fromOffset,
int count)
Removes a specified number of bytes starting from a given offset within this Bytes object.
|
static Bytes<byte[]> |
valueOf(String text)
A reflection-friendly alias for the
from(String) method. |
static @NotNull Bytes<byte[]> |
wrapForRead(byte[] byteArray)
Creates and returns a new Bytes instance that wraps the provided
byteArray. |
static @NotNull Bytes<ByteBuffer> |
wrapForRead(@NotNull ByteBuffer byteBuffer)
Creates and returns a new Bytes instance that wraps the provided
byteBuffer. |
static @NotNull Bytes<byte[]> |
wrapForWrite(byte[] byteArray)
Creates and returns a new Bytes instance that wraps the provided
byteArray and
is ready for writing operations. |
static @NotNull Bytes<ByteBuffer> |
wrapForWrite(@NotNull ByteBuffer byteBuffer)
Creates and returns a new Bytes instance that wraps the provided
byteBuffer. |
default Bytes |
write(@NotNull InputStream inputStream)
Writes the contents of the provided
inputStream into this Bytes object. |
default void |
writeMarshallableLength16(@NotNull WriteBytesMarshallable marshallable)
Writes the content of the provided
marshallable into this Bytes object, including a 16-bit length indicator
preceding the actual object data. |
addAndGetDouble, addAndGetDoubleNotAtomic, addAndGetFloat, addAndGetFloatNotAtomic, addAndGetInt, addAndGetIntNotAtomic, addAndGetLong, addAndGetShortNotAtomic, addAndGetUnsignedByteNotAtomic, byteCheckSum, byteCheckSum, capacity, charAt, cipher, cipher, compareAndSwapDouble, compareAndSwapFloat, compareAndSwapInt, compareAndSwapLong, contentEquals, elasticByteBuffer, endsWith, equalBytes, follow, forFields, from, hash, inside, inside, isDirectMemory, isEmpty, isEqual, isImmutableEmptyByteStore, lazyNativeBytesStoreWithFixedCapacity, length, move, nativePointer, nativeStore, nativeStoreFrom, nativeStoreWithFixedCapacity, startsWith, startsWith, subSequence, to8bitString, toDebugString, toDebugString, underlyingObject, wrap, wrap, wrap, writeMaxInt, writeMaxLong, zeroOutappend, append, appendAndReturnLength, internalNumberBuffer, nativeWrite, testAndSetInt, write, write, write, write, write, write8bit, write8bit, writeBoolean, writeByte, writeByte, writeDouble, writeFloat, writeInt, writeInt24, writeLong, writeOrderedDouble, writeOrderedFloat, writeOrderedInt, writeOrderedLong, writeShort, writeUnsignedByte, writeUnsignedInt, writeUnsignedShort, writeUtf8, writeUtf8Limited, writeVolatileByte, writeVolatileDouble, writeVolatileFloat, writeVolatileInt, writeVolatileLong, writeVolatileShortchars, codePoints, toStringbytesMethodReader, bytesMethodReaderBuilder, readObjectcanReadDirect, canReadDirect, compareUtf8, copyTo, copyTo, createCharToString, fastHash, findByte, nativeRead, parseLong, peekUnsignedByte, peekVolatileInt, printable, read, readBoolean, readByte, readDouble, readFloat, readIncompleteLong, readInt, readLong, readShort, readUnsignedByte, readUnsignedInt, readUnsignedInt24, readUnsignedShort, readUtf8, readUtf8Limited, readUtf8Limited, readVolatileByte, readVolatileDouble, readVolatileFloat, readVolatileInt, readVolatileLong, readVolatileShort, subBytes, testAndSetInt, toByteArray, toTemporaryDirectByteBufferlastDecimalPlaces, lastDecimalPlaces, lastNumberHadDigits, lastNumberHadDigits, parse8bit, parse8bit, parse8bit, parse8bit, parse8bit, parseBigDecimal, parseBoolean, parseBoolean, parseDouble, parseFlexibleLong, parseFloat, parseInt, parseLong, parseLongDecimal, parseUtf8, parseUtf8, parseUtf8, reader, skipToinputStream, lenient, lenient, parseHexLong, parseUtf8, parseUtf8, peekUnsignedByte, rawReadByte, rawReadInt, rawReadLong, read, read, read, read, read, read, read8bit, read8bit, read8bit, readBigDecimal, readBigInteger, readBoolean, readByte, readChar, readDouble, readEnum, readFloat, readHistogram, readIncompleteLong, readInt, readInt24, readLimit, readLimitToCapacity, readLong, readPosition, readPositionForHeader, readPositionRemaining, readPositionUnlimited, readShort, readSkip, readStopBit, readStopBitChar, readStopBitDecimal, readStopBitDouble, readUnsignedByte, readUnsignedInt, readUnsignedInt24, readUnsignedShort, readUtf8, readUtf8, readUtf8, readUtf8, readVolatileInt, readVolatileLong, readWithLength, readWithLength, readWithLength0, uncheckedReadSkipBackOne, uncheckedReadSkipOne, uncheckedReadUnsignedByte, unsafeRead, unsafeReadObject, unsafeReadObjectbytesMethodWriter, writeObjectappend, append, append, append, append, append, append, append, append, append, append8bit, append8bit, append8bit, append8bit, append8bit, appendBase, appendBase16, appendBase16, appendDateMillis, appendDecimal, appendTimeMillis, decimaliser, decimaliser, fpAppend0, fpAppend0, internalNumberBuffer, writerappendUtf8, appendUtf8, appendUtf8, appendUtf8, appendUtf8, appendUtf8, canWriteDirect, copyFrom, outputStream, rawWriteByte, rawWriteInt, rawWriteLong, unsafeWrite, unsafeWriteObject, unsafeWriteObject, write, write, write, write, write, write, write, write, write8bit, write8bit, write8bit, write8bit, writeBigDecimal, writeBigInteger, writeBoolean, writeByte, writeChar, writeDouble, writeDoubleAndInt, writeEnum, writeFloat, writeHistogram, writeInt, writeInt24, writeIntAdv, writeLimit, writeLong, writeLongAdv, writeOrderedInt, writeOrderedLong, writePosition, writePositionForHeader, writePositionRemaining, writeShort, writeSkip, writeSome, writeSome, writeStopBit, writeStopBit, writeStopBit, writeStopBitDecimal, writeUnsignedByte, writeUnsignedInt, writeUnsignedInt24, writeUnsignedShort, writeUtf8, writeUtf8, writeWithLengthclearAndPad, prepend, prewrite, prewrite, prewriteByte, prewriteInt, prewriteLong, prewriteShortadjustHexDumpIndentation, retainedHexDumpDescription, writeHexDumpDescriptionstatic final long MAX_CAPACITY
static final int MAX_HEAP_CAPACITY
static final int DEFAULT_BYTE_BUFFER_CAPACITY
@NotNull static @NotNull Bytes<ByteBuffer> elasticByteBuffer()
DEFAULT_BYTE_BUFFER_CAPACITY.
The memory for the returned Bytes object is allocated off-heap, meaning it's not under the JVM's garbage collector's immediate purview. It's crucial to conscientiously release these resources when they're no longer required to ensure timely memory deallocation. If these resources are not manually released, they will still eventually be reclaimed by the garbage collector, but possibly with a delay.
@NotNull static @NotNull Bytes<ByteBuffer> elasticByteBuffer(int initialCapacity)
initialCapacity which will be resized as required.
The memory for the returned Bytes object is allocated off-heap, meaning it's not under the JVM's garbage collector's immediate purview. It's crucial to conscientiously release these resources when they're no longer required to ensure timely memory deallocation. If these resources are not manually released, they will still eventually be reclaimed by the garbage collector, but possibly with a delay.
initialCapacity - the initial non-negative capacity given in bytesIllegalArgumentException - if the provided initialCapacity is negative.@NotNull static @NotNull Bytes<ByteBuffer> elasticByteBuffer(int initialCapacity, int maxCapacity)
initialCapacity which will be resized as required up
to the given maxCapacity.
The memory for the returned Bytes object is allocated off-heap, meaning it's not under the JVM's garbage collector's immediate purview. It's crucial to conscientiously release these resources when they're no longer required to ensure timely memory deallocation. If these resources are not manually released, they will still eventually be reclaimed by the garbage collector, but possibly with a delay.
This method allows for fine-tuned control over the buffer's capacity, enabling performance optimization and resource management.
initialCapacity - the initial non-negative capacity given in bytesmaxCapacity - the maximum capacity given in bytes; must be non-negative and at least as large as initialCapacityIllegalArgumentException - if the provided initialCapacity or maxCapacity is negative,
or if maxCapacity is less than initialCapacity.@NotNull static @NotNull Bytes<ByteBuffer> elasticHeapByteBuffer(int initialCapacity)
initialCapacity,
that can dynamically resize as required.
The returned Bytes object utilizes heap memory, which is managed by the JVM's garbage collector. This is suitable for scenarios where the buffer size may change, and the application requires the flexibility of automatic memory management.
Please note that, since this is heap memory, the garbage collector will manage the memory deallocation.
initialCapacity - the initial capacity of the buffer in bytes; must be non-negativeIllegalArgumentException - if the provided initialCapacity is negative@NotNull static @NotNull Bytes<ByteBuffer> elasticHeapByteBuffer()
initialCapacity
of 128 bytes, that can dynamically resize as required.
This is a convenience method that behaves similarly to elasticHeapByteBuffer(int initialCapacity),
but with a preset default initial capacity.
The returned Bytes object utilizes heap memory, which is managed by the JVM's garbage collector.
static <T> Bytes<T> forFieldGroup(@NotNull T object, @NotNull @NotNull String groupName)
object.
The group of fields is identified by the FieldGroup annotation with a name specified by groupName.
This method effectively turns the group of fields into a contiguous memory segment that can be accessed and manipulated
as a single entity using the returned Bytes object.
Example of using FieldGroup to group fields:
static class Padding extends Parent {
{@literal @}FieldGroup("p")
// 128 bytes
transient long p0, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11, p12, p13, p14, p15;
}
Example of creating a Bytes view for a field group:
Padding example = new Padding();
Bytes<Padding> bytes = Bytes.forFieldGroup(example, "p");
Note: The data in the resulting Bytes view is preceded by the length of the data encoded as an unsigned byte. This consumes one byte of storage and limits the maximum size of the data in the view to 255 usable bytes.
T - The type of the underlying objectobject - The non-null object containing the fields to be mappedgroupName - The non-null name of the field group as specified in FieldGroupNullPointerException - If the provided object or the provided groupName is null@NotNull static @NotNull Bytes<ByteBuffer> wrapForRead(@NotNull @NotNull ByteBuffer byteBuffer) throws net.openhft.chronicle.core.io.ClosedIllegalStateException, net.openhft.chronicle.core.io.ThreadingIllegalStateException
byteBuffer.
The returned Bytes instance is configured for reading from the current position of the
byteBuffer up to its limit.
This method is provided for convenience. However, it's important to note that this method may create intermediate objects, which might not be ideal for performance-sensitive applications that require minimizing garbage creation. To avoid creating intermediate objects, consider using a different approach as demonstrated in the example below.
byteBuffer - The ByteBuffer to wrap. Must be non-null and must not be read-only.byteBuffer, ready for reading.NullPointerException - If the provided byteBuffer is null.ReadOnlyBufferException - If the provided byteBuffer is read-only.BufferUnderflowException - If there is not enough data in the buffer.net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way.@NotNull static @NotNull Bytes<ByteBuffer> wrapForWrite(@NotNull @NotNull ByteBuffer byteBuffer) throws net.openhft.chronicle.core.io.ClosedIllegalStateException, net.openhft.chronicle.core.io.ThreadingIllegalStateException
byteBuffer.
The returned Bytes instance is configured for writing, starting at the current position of the
byteBuffer up to its limit.
Important Note: When the returned Bytes instance is closed, any direct byteBuffer will be deallocated
and should no longer be used.
byteBuffer - The ByteBuffer to wrap. Must be non-null and must not be read-only.byteBuffer, ready for writing.NullPointerException - If the provided byteBuffer is null.ReadOnlyBufferException - If the provided byteBuffer is read-only.BufferOverflowException - If there is not enough space in the buffer.net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way.@NotNull static @NotNull Bytes<byte[]> wrapForRead(byte[] byteArray)
byteArray.
The returned Bytes instance is configured for reading, starting from the beginning of the
byteArray up to its length.
Important Note: This method creates intermediate objects and might not be ideal for performance-sensitive applications due to garbage creation.
byteArray - The byte array to wrap. Must be non-null.byteArray, ready for reading.NullPointerException - If the provided byteArray is null.@NotNull static @NotNull Bytes<byte[]> wrapForWrite(byte[] byteArray)
byteArray and
is ready for writing operations.
Important Note: This method is intended for convenience, but might not be optimal for performance-sensitive scenarios as it creates intermediate objects which might lead to garbage collection overhead.
byteArray - The byte array to wrap for writing operations. Must be non-null.byteArray, ready for writing.NullPointerException - If the provided byteArray is null.@NotNull static @NotNull Bytes<byte[]> from(@NotNull @NotNull CharSequence text)
text encoded in ISO-8859-1.
The returned Bytes instance is ready for reading and is allocated on the heap.from in interface BytesStore<Bytes<U>,U>text - The non-null text to be converted and wrapped in a Bytes instance.NullPointerException - If the provided text is null.static Bytes<Void> fromDirect(@NotNull @NotNull CharSequence text)
text encoded in ISO-8859-1.
The returned Bytes instance is ready for reading and is allocated using native memory.text - The non-null text to be converted and wrapped in a Bytes instance.NullPointerException - If the provided text is null.@NotNull static @NotNull Bytes<byte[]> directFrom(@NotNull @NotNull String text)
text encoded in ISO-8859-1.
The returned Bytes instance is ready for reading and is allocated using native memory.text - The non-null text to be converted and wrapped in a Bytes instance.NullPointerException - If the provided text is null.@NotNull static @NotNull Bytes<byte[]> from(@NotNull @NotNull String text)
text encoded in ISO-8859-1 character set.
The returned Bytes object is allocated on the heap and is ready for reading.
The ISO-8859-1 encoding is used because it is a single-byte encoding that supports the first 256 Unicode characters, making it well-suited for encoding texts that primarily consist of Western European characters.
from in interface BytesStore<Bytes<U>,U>text - A non-null String to be converted into bytes using ISO-8859-1 encoding and wrapped in a Bytes object.Bytes object containing the text, encoded using the ISO-8859-1 character set.NullPointerException - If the provided text is null.static Bytes<?> empty()
empty in interface BytesStore<Bytes<U>,U>Bytes object with fixed size and immutable contents.@UsedViaReflection static Bytes<byte[]> valueOf(String text)
from(String) method.
This method is functionally equivalent to from(String) and is primarily intended for invocation through reflection mechanisms.
It creates and returns a new object containing the given text, encoded in the ISO-8859-1 character set.
text - A non-null String to be converted into bytes using ISO-8859-1 encoding and wrapped in a Bytes object.Bytes object containing the text, encoded using the ISO-8859-1 character set.NullPointerException - If the provided text is null.@NotNull static @NotNull VanillaBytes<Void> allocateDirect(long capacity) throws IllegalArgumentException
VanillaBytes object that is a fixed-size wrapper for native memory
(accessible via 64-bit addresses) with the specified capacity.
This method is used to allocate a fixed amount of native memory, which can be useful for performance-sensitive applications.
capacity - The non-negative capacity of the native memory to be allocated, measured in bytes.VanillaBytes object that wraps the allocated native memory.IllegalArgumentException - If the provided capacity is negative.@NotNull static @NotNull NativeBytes<Void> allocateElasticDirect()
Native memory allocation can be faster and is not subject to Java's garbage collection, making it suitable for performance-sensitive applications.
NativeBytes object representing an elastic wrapper for native memory.@NotNull static @NotNull NativeBytes<Void> allocateElasticDirect(long initialCapacity) throws IllegalArgumentException
initialCapacity. The capacity of the wrapper will be automatically
resized as needed.
Native memory allocation can be faster and is not subject to Java's garbage collection, making it suitable for performance-sensitive applications.
initialCapacity - The initial non-negative capacity of the wrapper in bytes.NativeBytes object representing an elastic wrapper for native memory.IllegalArgumentException - If the provided initialCapacity is negative.@NotNull static @NotNull OnHeapBytes allocateElasticOnHeap()
Heap memory allocation is managed by the Java Virtual Machine and is subject to garbage collection.
OnHeapBytes object representing an elastic wrapper for heap memory.@NotNull static @NotNull OnHeapBytes allocateElasticOnHeap(int initialCapacity)
initialCapacity. The capacity of the wrapper will
be automatically resized as needed.
Heap memory allocation is managed by the Java Virtual Machine and is subject to garbage collection.
initialCapacity - The initial non-negative capacity of the wrapper in bytes.OnHeapBytes object representing an elastic wrapper for heap memory.IllegalArgumentException - If the provided initialCapacity is negative.@NotNull static @NotNull String toString(@NotNull @NotNull Bytes<?> buffer) throws BufferUnderflowException, IllegalArgumentException
buffer between its current
readPosition and readLimit.
The buffer's state remains unchanged by this method.
If the length of the extracted substring is greater than maxLen,
an ellipsis "..." is appended to the resulting string. Note that in this case, the
length of the returned string will be maxLen + 3.
buffer - The buffer to extract the string from. Must not be null.BufferUnderflowException - If there is not enough data in the buffer.IllegalArgumentException - If maxLen is negative.NullPointerException - If the provided buffer is null.@NotNull static @NotNull String toString(@NotNull @NotNull Bytes<?> buffer, long maxLen) throws BufferUnderflowException, IllegalArgumentException
buffer between its current
readPosition and readLimit, truncated to the specified maximum length.
The buffer's state remains unchanged by this method.
If the length of the extracted substring is greater than maxLen,
an ellipsis "..." is appended to the resulting string. Note that in this case, the
length of the returned string will be maxLen + 3.
buffer - The buffer to extract the string from. Must not be null.maxLen - The maximum length of the string to be extracted.BufferUnderflowException - If there is not enough data in the buffer.IllegalArgumentException - If maxLen is negative.NullPointerException - If the provided buffer is null.@NotNull static @NotNull String toString(@NotNull @NotNull Bytes<?> buffer, long position, long length)
buffer starting at the specified position,
and spanning for the specified length number of characters. The buffer's state
remains unchanged by this method.
The method reads length bytes from the buffer, starting at position,
and constructs a string from these bytes.
buffer - The buffer to extract the string from. Must not be null.position - The position in the buffer to start extracting the string from.length - The number of characters to include in the extracted string.IllegalArgumentException - If the provided position or length is negative.NullPointerException - If the provided buffer is null.@NotNull static @NotNull VanillaBytes allocateDirect(byte[] bytes) throws net.openhft.chronicle.core.io.ClosedIllegalStateException, net.openhft.chronicle.core.io.ThreadingIllegalStateException
bytes array.
Changes in the given bytes will not be affected by writes in
the returned wrapper or vice versa.
bytes - array to copy, the array reference must not be nullNullPointerException - If the provided bytes is nullnet.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way.@NotNull static @NotNull Bytes<?> fromHexString(@NotNull @NotNull String s)
toHexString methods, back into a Bytes object.
This method takes a string that represents hexadecimal data along with comments (which describe the meaning of
the bytes), and converts it back into a Bytes object. The input string should have been generated by the
toHexString method. It can contain hexadecimal values, spaces, and comments. The method is able to
correctly parse and ignore spaces and comments during conversion.
For example, given the string:
"c3 76 6d 68 # vmh: b6 03 56 4d 48 # VMH"This method would convert it to a
Bytes object representing the original bytes before they were converted
to the hexadecimal representation.s - the hexadecimal string to convert, which must have been generated by the toHexString method.
This parameter must not be null.Bytes object representing the original byte values of the provided hexadecimal string.IllegalArgumentException - If the provided string is not in the valid format produced by the toHexString
method.@NotNull default @NotNull Bytes<U> unchecked(boolean unchecked) throws net.openhft.chronicle.core.io.ClosedIllegalStateException, net.openhft.chronicle.core.io.ThreadingIllegalStateException
unchecked.
This allows bounds checks to be turned off.
Note: this means that the result is no longer elastic, even if this is elastic.
Note: It is only possible to go from a checked Bytes to an unchecked bytes and not vice versa.
unchecked - if true, minimal bounds checks will be performednet.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way.default boolean unchecked()
When a Bytes object is unchecked, it performs minimal or no bounds checking on read and write operations. This can improve performance but may result in undefined behavior if attempting to access out-of-bounds elements.
true if this Bytes object operates in unchecked mode; false otherwise.default long safeLimit()
safeLimit in interface BytesStore<Bytes<U>,U>default boolean isClear()
BytesStorereadPosition is at the start and
the writeLimit is at the end.
I.e start() == readPosition() && writeLimit() == capacity()
isClear in interface BytesStore<Bytes<U>,U>readPosition is at the start and
the writeLimit is at the enddefault long realCapacity()
BytesStorerealCapacity in interface BytesStore<Bytes<U>,U>realCapacity in interface RandomDataInputrealCapacity in interface StreamingDataOutput<Bytes<U>>BytesStore<Bytes<U>,U> copy() throws IllegalStateException, net.openhft.chronicle.core.io.ClosedIllegalStateException, net.openhft.chronicle.core.io.ThreadingIllegalStateException
RandomCommon.readPosition() and RandomCommon.readLimit().
The copy will have its own separate storage and state, and modifications to the copy will not affect the original Bytes object, and vice versa.
copy in interface BytesStore<Bytes<U>,U>net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe wayIllegalStateException@NotNull default @NotNull String toHexString()
readPosition()
and encodes at most 1024 bytes.
Each line of the output string contains hexadecimal representation of 16 bytes, followed by comments describing the meaning of those bytes.
For example, if the Bytes object contains bytes representing the ASCII string "VMH", the output would be similar to this:
c3 76 6d 68 # vmh: b6 03 56 4d 48 # VMH
This is assumed to be used to print the contents on a best effort basis. If an Error occurs it will be returned in the String.
@NotNull default @NotNull String toHexString(long maxLength)
readPosition()
and encodes at most the provided maxLength bytes.
Each line of the output string contains hexadecimal representation of 16 bytes, followed by comments describing the meaning of those bytes.
For example, if the Bytes object contains bytes representing the ASCII string "VMH", and maxLength is large enough, the output would be similar to this:
c3 76 6d 68 # vmh: b6 03 56 4d 48 # VMH
This is assumed to be used to print the contents on a best effort basis. If an Error occurs it will be returned in the String.
maxLength - Limit the number of bytes to be encoded.IllegalArgumentException - If the provided maxLength is negative.@NotNull default @NotNull String toHexString(long offset, long maxLength)
offset
and encodes at most the provided maxLength bytes.
The method reads data starting from the specified offset. Each line of the output string contains
hexadecimal representation of 16 bytes, followed by comments describing the meaning of those bytes.
If the number of bytes from the offset to the end exceeds maxLength, the output string
will be suffixed with "... truncated".
For example, if the Bytes object contains bytes representing the ASCII string "VMH", and offset is 0, and maxLength is large enough, the output would be similar to this:
c3 76 6d 68 # vmh: b6 03 56 4d 48 # VMH
This is assumed to be used to print the contents on a best effort basis. If an Error occurs it will be returned in the String.
offset - The starting offset within the Bytes object to begin the hexadecimal conversion.maxLength - Limit the number of bytes to be encoded. If the number of bytes exceeds maxLength,
the output will be suffixed with "... truncated".IllegalArgumentException - If the provided offset or maxLength is negative.boolean isElastic()
realCapacity().
Elastic Bytes objects can automatically grow to accommodate additional data, whereas non-elastic ones have a fixed capacity.
true if this Bytes object is elastic; false otherwise.default void ensureCapacity(long desiredCapacity)
throws DecoratedBufferOverflowException,
IllegalStateException,
net.openhft.chronicle.core.io.ClosedIllegalStateException,
net.openhft.chronicle.core.io.ThreadingIllegalStateException
If this Bytes object is elastic and doesn't have enough capacity, it will be resized. If it is not
elastic and doesn't have enough capacity, a DecoratedBufferOverflowException will be thrown.
ensureCapacity in interface StreamingDataOutput<Bytes<U>>desiredCapacity - The minimum capacity, in bytes, that is required.DecoratedBufferOverflowException - If the Bytes object is not elastic and there isn't enough space
or if the provided desiredCapacity is negative.net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe wayIllegalStateException@NotNull default @NotNull Bytes<U> bytesForRead() throws IllegalStateException, net.openhft.chronicle.core.io.ClosedIllegalStateException, net.openhft.chronicle.core.io.ThreadingIllegalStateException
Note that the slice is a subsection of this Bytes object and will not be elastic regardless of the elasticity of the parent Bytes object.
bytesForRead in interface BytesStore<Bytes<U>,U>net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe wayIllegalStateException@NotNull default @NotNull Bytes<U> bytesForWrite() throws IllegalStateException, net.openhft.chronicle.core.io.ClosedIllegalStateException
start position to the realCapacity.
The returned Bytes object is non-elastic and supports both read and write operations using cursors.
bytesForWrite in interface BytesStore<Bytes<U>,U>net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe wayIllegalStateException@Nullable @Nullable BytesStore bytesStore()
The BytesStore represents the underlying storage of bytes that the Bytes object is manipulating.
bytesStore in interface BytesStore<Bytes<U>,U>default boolean isEqual(@Nullable
@Nullable String other)
throws IllegalStateException
other string for equality.
This method returns true if the contents of this Bytes object is equal to the contents
of the other string. Otherwise, it returns false.
other - The string to compare with the contents of this Bytes object, can be null.true if the contents of this Bytes object equals the contents of the provided
other string; false otherwise.net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe wayIllegalStateException@NotNull @NotNull Bytes<U> compact() throws net.openhft.chronicle.core.io.ClosedIllegalStateException, net.openhft.chronicle.core.io.ThreadingIllegalStateException
This operation is useful to free up space for writing by discarding bytes that have already been read.
net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe waydefault long copyTo(@NotNull
@NotNull BytesStore targetByteStore)
throws net.openhft.chronicle.core.io.ClosedIllegalStateException
targetByteStore.
The number of bytes copied is the minimum of the remaining bytes in this Bytes object and the
remaining capacity in the targetByteStore.
copyTo in interface BytesStore<Bytes<U>,U>copyTo in interface StreamingDataInput<Bytes<U>>targetByteStore - The target BytesStore to copy bytes into, must not be null.NullPointerException - If the provided targetByteStore is null.net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe waydefault void copyTo(@NotNull
@NotNull OutputStream outputStream)
throws IOException,
net.openhft.chronicle.core.io.ClosedIllegalStateException
outputStream.
Bytes are written from the current read position up to the limit of this Bytes object.
copyTo in interface BytesStore<Bytes<U>,U>copyTo in interface StreamingDataInput<Bytes<U>>outputStream - The OutputStream to write the bytes to, must not be null.net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.IOException - If an I/O error occurs while writing to the provided
outputStream.NullPointerException - If the provided outputStream is null.OutputStreamdefault boolean sharedMemory()
A Bytes object backed by a memory-mapped file, for example, can be shared among processes, whereas a Bytes object backed by heap memory cannot be shared in this way.
true if this Bytes object uses memory that can be shared across processes,
false otherwise.default void unwrite(long fromOffset,
int count)
throws BufferUnderflowException,
BufferOverflowException,
net.openhft.chronicle.core.io.ClosedIllegalStateException,
net.openhft.chronicle.core.io.ThreadingIllegalStateException
This method effectively removes count bytes beginning at the specified fromOffset,
shifting any subsequent bytes to the left (reduces their index).
The write position is adjusted accordingly, and the capacity remains unchanged.
fromOffset - The offset from which to start removing bytes.count - The number of bytes to remove.BufferUnderflowException - If fromOffset is negative or greater than the
write position.BufferOverflowException - If there isn't enough space to perform the unwrite operation.net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe waydefault long indexOf(@NotNull
@NotNull Bytes source)
throws net.openhft.chronicle.core.io.ClosedIllegalStateException
source Bytes object.
The method returns the lowest index k at which the contents of this Bytes object
equals the provided source Bytes object. If no such sequence exists, then -1
is returned.
Formally, the method returns the lowest index k such that:
this.startsWith(source, k)
If no such value of k exists, then -1 is returned.
source - The sub-bytes to search for within this Bytes object, must not be null.-1 if there
is no such occurrence.NullPointerException - If the provided source is null.net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.default int indexOf(@NotNull
@NotNull BytesStore source,
int fromIndex)
throws net.openhft.chronicle.core.io.ClosedIllegalStateException
fromIndex for which the contents of this
Bytes object equals the provided source , or -1 if no such index value exists.
On other words, returns the index within this Bytes object of the first occurrence of the
provided source
The returned index is the smallest value k for which:
If no such value of k exists, thenthis.startsWith(bytes, k)
-1 is returned.source - the non-null sub-bytes to search for.fromIndex - to start searching fromNullPointerException - If the provided source is nullnet.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.@NotNull @NotNull Bytes<U> clear() throws IllegalStateException, net.openhft.chronicle.core.io.ClosedIllegalStateException, net.openhft.chronicle.core.io.ThreadingIllegalStateException
clear in interface StreamingCommon<Bytes<U>>net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe wayIllegalStateExceptiondefault boolean readWrite()
readWrite in interface BytesStore<Bytes<U>,U>true if this Bytes object supports both reading and writing, false otherwise.default void readWithLength(long length,
@NotNull
@NotNull BytesOut<U> bytesOut)
throws BufferUnderflowException,
net.openhft.chronicle.core.io.IORuntimeException,
BufferOverflowException,
net.openhft.chronicle.core.io.ClosedIllegalStateException,
net.openhft.chronicle.core.io.ThreadingIllegalStateException
bytesOut.
This operation does not affect the readLimit or readPosition of this Bytes object.
length - The number of bytes to write. Must be non-negative.bytesOut - The target BytesOut object to write to. Must not be null.BufferUnderflowException - If the specified length is greater than the number of bytes available for reading from this Bytes object.net.openhft.chronicle.core.io.IORuntimeException - If an error occurs while reading from this Bytes object or writing to bytesOut.BufferOverflowException - If bytesOut does not have enough capacity to hold the bytes being written.net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe wayIllegalArgumentException - If the specified length is negative.NullPointerException - If the provided bytesOut is null.default <T extends ReadBytesMarshallable> T readMarshallableLength16(@NotNull @NotNull Class<T> clazz, @Nullable T using) throws BufferUnderflowException, net.openhft.chronicle.core.io.ClosedIllegalStateException, net.openhft.chronicle.core.io.InvalidMarshallableException, net.openhft.chronicle.core.io.ThreadingIllegalStateException
If the using parameter is not null, this method will update its state with the read content.
Otherwise, it will create a new instance of the specified class.
readMarshallableLength16 in interface BytesIn<U>T - The type of the object being read.clazz - The class of the object to be read. Must not be null.using - An optional instance to update with the read content. Can be null.using was provided.BufferUnderflowException - If there are not enough bytes in this Bytes object to read the content.net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.InvalidMarshallableException - If the data in this Bytes object cannot be converted into an instance of the specified class.NullPointerException - If the provided clazz is null.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way.writeMarshallableLength16(WriteBytesMarshallable)default void writeMarshallableLength16(@NotNull
@NotNull WriteBytesMarshallable marshallable)
throws BufferOverflowException,
net.openhft.chronicle.core.io.ClosedIllegalStateException,
BufferUnderflowException,
net.openhft.chronicle.core.io.InvalidMarshallableException,
net.openhft.chronicle.core.io.ThreadingIllegalStateException
marshallable into this Bytes object, including a 16-bit length indicator
preceding the actual object data. The length indicator denotes the number of bytes taken up by the object data.
This method is useful for serialization, as it writes not only the content of the marshallable object
but also information about its size.
writeMarshallableLength16 in interface BytesOut<U>marshallable - The object to be serialized and written to this Bytes object. Must not be null.BufferOverflowException - If there is not enough capacity in this Bytes object to store the serialized data.net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.
cannot be addressed with 16-bits.NullPointerException - If the provided marshallable is null.BufferUnderflowException - If there is not enough data available in the buffer.net.openhft.chronicle.core.io.InvalidMarshallableException - If the object cannot be written due to invalid data.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way.readMarshallableLength16(Class, ReadBytesMarshallable)default Bytes write(@NotNull @NotNull InputStream inputStream) throws IOException, BufferOverflowException, net.openhft.chronicle.core.io.ClosedIllegalStateException, net.openhft.chronicle.core.io.ThreadingIllegalStateException
inputStream into this Bytes object. Continues reading from the
inputStream and writing into this Bytes object until the end of the stream is reached.
Note: This method does not close the provided inputStream.
inputStream - The input stream from which data is to be read. Must not be null.IOException - If an I/O error occurs when reading from the inputStream.BufferOverflowException - If there is not enough capacity in this Bytes object to write the data read from the input stream.net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe wayNullPointerException - If the provided inputStream is null.Copyright © 2023. All rights reserved.