net.openhft.chronicle.wire

Interface WireOut

All Superinterfaces:

DocumentWritten, MarshallableOut, RollbackIfNotCompleteNotifier, WireCommon

All Known Subinterfaces:

Wire

All Known Implementing Classes:

AbstractAnyWire, AbstractWire, BinaryWire, CSVWire, HashWire, JSONWire, QueryWire, RawWire, ReadAnyWire, TextWire, YamlWire, YamlWireOut

public interface WireOut
extends WireCommon, MarshallableOut

Defines the standard interface for sequential writing to a Bytes stream.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	WireOut.EndOfWire

Method Summary

Modifier and Type	Method and Description
DocumentContext	acquireWritingDocument(boolean metaData) Retrieves a context for writing either data or metadata, reusing an existing context if available.
@NotNull WireOut	addPadding(int paddingToAdd) Adds padding to the wire.
void	clear() Resets both the positions in the wire and the header number.
default @NotNull WireOut	dropDefault(boolean dropDefault)
default WireOut.EndOfWire	endOfWire(boolean writeEOF, long timeout, TimeUnit timeUnit, long lastPosition) Check if end of wire marker is present, optionally writing it unless one is already written.
long	enterHeader(long safeLength) INTERNAL METHOD, call writingDocument instead
@NotNull ValueOut	getValueOut() Retrieves the interface for defining the output of a value that will be written to the stream.
ObjectOutput	objectOutput() Get the ObjectOutput associated with this WireOut.
default @NotNull WireOut	padToCacheAlign() Ensures that the wire's output aligns with cache boundaries.
void	updateFirstHeader() INTERNAL METHOD, call writingDocument instead
void	updateFirstHeader(long headerLen) INTERNAL METHOD, call writingDocument instead
void	updateHeader(long position, boolean metaData, int expectedHeader) INTERNAL METHOD, call writingDocument instead
@NotNull ValueOut	write() Writes an empty field marker to the stream.
ValueOut	write(CharSequence key) Writes a CharSequence key to the stream.
@NotNull ValueOut	write(WireKey key) Writes a WireKey to the stream.
default @NotNull WireOut	writeAlignTo(int alignment, int plus) Aligns the write position to the provided alignment boundary, taking into account the specified offset (plus).
default <K,V> void	writeAllAsMap(Class<K> kClass, Class<V> vClass, @NotNull Map<K,V> map)
@NotNull WireOut	writeComment(CharSequence s) Writes a comment to the wire.
default void	writeDocument(boolean metaData, @NotNull WriteMarshallable writer) Writes a document to the wire.
void	writeEndEvent()
boolean	writeEndOfWire(long timeout, TimeUnit timeUnit, long lastPosition) Write the end of wire marker, unless one is already written.
default ValueOut	writeEvent(Class<?> expectedType, Object eventKey) Writes an event to the stream based on the type and event key.
default ValueOut	writeEventId(int methodId) Writes an event identifier to the stream.
default ValueOut	writeEventId(String name, int methodId) Writes an event identifier with a name to the stream.
default ValueOut	writeEventName(CharSequence key) Writes a CharSequence key to the stream.
default @NotNull ValueOut	writeEventName(WireKey key) Writes a key to the stream.
boolean	writeFirstHeader() INTERNAL METHOD, call writingDocument instead
default void	writeNotCompleteDocument(boolean metaData, @NotNull WriteMarshallable writer) Writes a document to the wire without marking its completion.
void	writeStartEvent() Start an event object, mostly for internal use.
default @NotNull DocumentContext	writingDocument() Starts the process of writing a data document (not metadata) to the wire.
DocumentContext	writingDocument(boolean metaData) Starts the process of writing a document to the wire with an option for metadata.
default boolean	writingIsComplete() Checks if the current writing operation is complete.

Methods inherited from interface net.openhft.chronicle.wire.WireCommon

bytes, bytesComment, classLookup, classLookup, headerNumber, headerNumber, isBinary, newBooleanReference, newIntArrayReference, newIntReference, newLongArrayReference, newLongReference, newTwoLongReference, notCompleteIsNotPresent, notCompleteIsNotPresent, parent, parent, pauser, pauser, reset, usePadding, usePadding, useSelfDescribingMessage

Methods inherited from interface net.openhft.chronicle.wire.MarshallableOut

builder, methodWriter, methodWriterBuilder, methodWriterBuilder, recordHistory, writeBytes, writeDocument, writeDocument, writeMap, writeMessage, writeMessage, writeText

Methods inherited from interface net.openhft.chronicle.wire.RollbackIfNotCompleteNotifier

rollbackIfNotComplete

Method Detail

write

@NotNull
@NotNull ValueOut write()

Writes an empty field marker to the stream.

Returns:

An interface to further define the output for the written value.

writeEventName

@NotNull
default @NotNull ValueOut writeEventName(WireKey key)

Writes a key to the stream. For RAW types, the label will be in text. This can be read using readEventName().

Parameters:

key - The key to write to the stream.

Returns:

An interface to further define the output for the written value.

writeEventName

default ValueOut writeEventName(CharSequence key)

Writes a CharSequence key to the stream.

Parameters:

key - The CharSequence key to write to the stream.

Returns:

An interface to further define the output for the written value.

writeEvent

default ValueOut writeEvent(Class<?> expectedType,
                            Object eventKey)
                     throws net.openhft.chronicle.core.io.InvalidMarshallableException

Writes an event to the stream based on the type and event key.

Parameters:

expectedType - The expected type of the event to write.

eventKey - The key of the event.

Returns:

An interface to further define the output for the written value.

Throws:

net.openhft.chronicle.core.io.InvalidMarshallableException - if there's an error marshalling the event.

writeEventId

default ValueOut writeEventId(int methodId)

Writes an event identifier to the stream.

Parameters:

methodId - The ID of the method representing the event.

Returns:

An interface to further define the output for the written value.

writeEventId

default ValueOut writeEventId(String name,
                              int methodId)

Writes an event identifier with a name to the stream.

Parameters:

name - The name of the event.

methodId - The ID of the method representing the event.

Returns:

An interface to further define the output for the written value.

write

@NotNull
@NotNull ValueOut write(WireKey key)

Writes a WireKey to the stream. This method is typically used for wires that support fields with structured keys.

Parameters:

key - The WireKey to write to the stream.

Returns:

An interface to further define the output for the written value.

write

ValueOut write(CharSequence key)

Writes a CharSequence key to the stream. This provides flexibility to write non-standard keys to the wire.

Parameters:

key - The CharSequence key to write to the stream.

Returns:

An interface to further define the output for the written value.

getValueOut

@NotNull
@NotNull ValueOut getValueOut()

Retrieves the interface for defining the output of a value that will be written to the stream.

Returns:

The interface to further define the output for the written value.

objectOutput

ObjectOutput objectOutput()

Get the ObjectOutput associated with this WireOut.

Returns:

The ObjectOutput associated with this WireOut.

writeComment

@NotNull
@NotNull WireOut writeComment(CharSequence s)

Writes a comment to the wire. Comments may be useful for debugging or providing context within the wire stream.

Parameters:

s - The comment to be written to the stream.

Returns:

This WireOut instance for method chaining.

addPadding

@NotNull
@NotNull WireOut addPadding(int paddingToAdd)

Adds padding to the wire. This is particularly useful for aligning data.

Parameters:

paddingToAdd - The amount of padding to add.

Returns:

This WireOut instance for method chaining.

padToCacheAlign

@NotNull
default @NotNull WireOut padToCacheAlign()

Ensures that the wire's output aligns with cache boundaries. If the current write position is close to the end of a cache line, this method will pad the wire such that a subsequent 4-byte integer won't span across cache lines, optimizing cache performance.

Returns:

This WireOut instance for method chaining.

writeAlignTo

@NotNull
default @NotNull WireOut writeAlignTo(int alignment,
                                               int plus)

Aligns the write position to the provided alignment boundary, taking into account the specified offset (plus). Padding will be added as necessary.

Parameters:

alignment - The alignment boundary.

plus - Additional offset to the write position.

Returns:

This WireOut instance for method chaining.

clear

void clear()

Resets both the positions in the wire and the header number.

Specified by:

clear in interface WireCommon

writeDocument

default void writeDocument(boolean metaData,
                           @NotNull
                           @NotNull WriteMarshallable writer)
                    throws net.openhft.chronicle.core.io.InvalidMarshallableException

Writes a document to the wire. This will automatically handle header numbering.

Parameters:

metaData - Indicates if metadata should be written.

writer - The logic for writing the content of the document.

Throws:

net.openhft.chronicle.core.io.InvalidMarshallableException

writingDocument

DocumentContext writingDocument(boolean metaData)

Starts the process of writing a document to the wire with an option for metadata.

Specified by:

writingDocument in interface DocumentWritten

Specified by:

writingDocument in interface MarshallableOut

Parameters:

metaData - If true, the returned document context will be used for writing metadata.

Returns:

A context for the document being written.

writingDocument

@NotNull
default @NotNull DocumentContext writingDocument()

Starts the process of writing a data document (not metadata) to the wire.

Specified by:

writingDocument in interface DocumentWritten

Specified by:

writingDocument in interface MarshallableOut

Returns:

A context for the document being written.

acquireWritingDocument

DocumentContext acquireWritingDocument(boolean metaData)

Retrieves a context for writing either data or metadata, reusing an existing context if available.

Specified by:

acquireWritingDocument in interface DocumentWritten

Specified by:

acquireWritingDocument in interface MarshallableOut

Parameters:

metaData - If true, the returned context will be used for writing metadata.

Returns:

A context for the document being written.

writeNotCompleteDocument

default void writeNotCompleteDocument(boolean metaData,
                                      @NotNull
                                      @NotNull WriteMarshallable writer)
                               throws net.openhft.chronicle.core.io.InvalidMarshallableException

Writes a document to the wire without marking its completion. This is primarily used in networking scenarios, but no longer used for queues.

Parameters:

metaData - If true, metadata will be written instead of regular data.

writer - Logic for writing the content of the document.

Throws:

net.openhft.chronicle.core.io.InvalidMarshallableException

updateHeader

void updateHeader(long position,
                  boolean metaData,
                  int expectedHeader)
           throws StreamCorruptedException

INTERNAL METHOD, call writingDocument instead

Update/end a header for a document

Throws:

StreamCorruptedException

enterHeader

long enterHeader(long safeLength)

INTERNAL METHOD, call writingDocument instead

Start a header for a document

Parameters:

safeLength - ensure there is at least this much space

Returns:

the position of the header

Throws:

WriteAfterEOFException - if you attempt to append an excerpt after an EOF has been written

writeFirstHeader

boolean writeFirstHeader()

INTERNAL METHOD, call writingDocument instead

Start the first header, if there is none This will increment the headerNumber as appropriate if successful

Note: the file might contain other data and the caller has to check this.

Returns:

true if the header needs to be written, false if there is a data already

updateFirstHeader

void updateFirstHeader()

INTERNAL METHOD, call writingDocument instead

update the first header after writing.

updateFirstHeader

void updateFirstHeader(long headerLen)

INTERNAL METHOD, call writingDocument instead

update the first header after writing headerEndPos bytes.

writeEndOfWire

boolean writeEndOfWire(long timeout,
                       TimeUnit timeUnit,
                       long lastPosition)

Write the end of wire marker, unless one is already written. This will increment the headerNumber as appropriate if successful

Parameters:

timeout - throw TimeoutException if it could not write the marker in time.

timeUnit - of the timeout

lastPosition - the end of the wire

Returns:

{code true} if did this method wrote EOF, false if it was already there.

endOfWire

default WireOut.EndOfWire endOfWire(boolean writeEOF,
                                    long timeout,
                                    TimeUnit timeUnit,
                                    long lastPosition)

Check if end of wire marker is present, optionally writing it unless one is already written. This will increment the headerNumber as appropriate if successful

Parameters:

writeEOF - if true, write end of wire marker unless already exists

timeout - throw TimeoutException if it could not write the marker in time.

timeUnit - of the timeout

lastPosition - the end of the wire

Returns:

WireOut.EndOfWire enum corresponding to EOF presence

writeStartEvent

void writeStartEvent()

Start an event object, mostly for internal use.

writeEndEvent

void writeEndEvent()

writeAllAsMap

default <K,V> void writeAllAsMap(Class<K> kClass,
                                 Class<V> vClass,
                                 @NotNull
                                 @NotNull Map<K,V> map)

dropDefault

@NotNull
default @NotNull WireOut dropDefault(boolean dropDefault)

writingIsComplete

default boolean writingIsComplete()

Description copied from interface: RollbackIfNotCompleteNotifier

Checks if the current writing operation is complete. This method can be used to determine if it's safe to proceed with further operations or if a rollback is required.

Specified by:

writingIsComplete in interface RollbackIfNotCompleteNotifier

Returns:

true unless there is an incomplete/chained message