net.openhft.chronicle.wire

Interface MarshallableOut

All Superinterfaces:

DocumentWritten, RollbackIfNotCompleteNotifier

All Known Subinterfaces:

ChronicleChannel, InternalChronicleChannel, Wire, WireOut

All Known Implementing Classes:

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

public interface MarshallableOut
extends DocumentWritten, RollbackIfNotCompleteNotifier

Defines the contract for objects that can write out Marshallable objects. Implementing classes or interfaces should provide concrete means to serialize and write Marshallable objects.

Use the builder(URL) method to create an instance of MarshallableOutBuilder to help construct appropriate implementations based on provided URLs.

Method Summary

Modifier and Type	Method and Description
DocumentContext	acquireWritingDocument(boolean metaData) Start or reuse an existing a DocumentContext, optionally call close() when done.
static MarshallableOutBuilder	builder(URL url) Creates and returns a new instance of MarshallableOutBuilder initialized with the provided URL.
default <T> T	methodWriter(@NotNull Class<T> tClass, Class<?>... additional) Creates a proxy of the specified interfaces, where each method call on the proxy is written for replay.
default <T> @NotNull net.openhft.chronicle.bytes.MethodWriterBuilder<T>	methodWriterBuilder(boolean metaData, @NotNull Class<T> tClass) Returns a MethodWriterBuilder that can be used to create a proxy for an interface.
default <T> @NotNull net.openhft.chronicle.bytes.MethodWriterBuilder<T>	methodWriterBuilder(@NotNull Class<T> tClass) Returns a MethodWriterBuilder that can be used to create a proxy for an interface.
default boolean	recordHistory()
default void	writeBytes(@NotNull net.openhft.chronicle.bytes.WriteBytesMarshallable marshallable) Serializes a Marshallable object directly to bytes.
default <T> void	writeDocument(T t, @NotNull BiConsumer<ValueOut,T> writer) Writes a provided object using a custom marshalling mechanism specified by a BiConsumer.
default void	writeDocument(@NotNull WriteMarshallable writer) Writes a Marshallable object as a document or message.
default void	writeMap(@NotNull Map<?,?> map) Writes a provided map into the underlying DocumentContext as a marshallable object.
default void	writeMessage(String eventName, Object value) Writes a message with a specified event name and associated object value.
default void	writeMessage(WireKey key, Object value) Write a key and value which could be a scalar or a marshallable.
default void	writeText(@NotNull CharSequence text) Writes a provided text message into the underlying DocumentContext.
default @NotNull DocumentContext	writingDocument() Start a document which is completed when DocumentContext.close() is called.
DocumentContext	writingDocument(boolean metaData) Begins a new document-writing session with the option to include meta-data.

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

rollbackIfNotComplete, writingIsComplete

Method Detail

builder

static MarshallableOutBuilder builder(URL url)

Creates and returns a new instance of MarshallableOutBuilder initialized with the provided URL.

Parameters:

url - The URL which will dictate the specific type of MarshallableOut to create.

Returns:

A new instance of MarshallableOutBuilder.

writingDocument

@NotNull
default @NotNull DocumentContext writingDocument()
                                                   throws UnrecoverableTimeoutException

Start a document which is completed when DocumentContext.close() is called. You can use a

 try(DocumentContext dc = appender.writingDocument()) {
      dc.wire().write("message").text("Hello World");
 }
 

WARNING : any data written inside the writingDocument(), should be performed as quickly as possible because a write lock is held until the DocumentContext is closed by the try-with-resources. For thread safe implementation such as Queue this blocks other appenders. Tailers are never blocked.

 try (DocumentContext dc = appender.writingDocument()) {
      // this should be performed as quickly as possible for implementations that support cocurrent writers
 }
 

Specified by:

writingDocument in interface DocumentWritten

Returns:

A fresh DocumentContext for writing.

Throws:

UnrecoverableTimeoutException

writingDocument

DocumentContext writingDocument(boolean metaData)
                         throws UnrecoverableTimeoutException

Begins a new document-writing session with the option to include meta-data. It is crucial to always close the returned DocumentContext once done writing.

Specified by:

writingDocument in interface DocumentWritten

Parameters:

metaData - Indicates if meta-data should be included in the document.

Returns:

A new instance of DocumentContext.

Throws:

UnrecoverableTimeoutException - if the operation times out in an unrecoverable manner.

acquireWritingDocument

DocumentContext acquireWritingDocument(boolean metaData)
                                throws UnrecoverableTimeoutException

Start or reuse an existing a DocumentContext, optionally call close() when done.

Specified by:

acquireWritingDocument in interface DocumentWritten

Parameters:

metaData - A boolean indicating if metadata should be included during writing.

Returns:

An existing or new DocumentContext tailored to the metadata preference.

Throws:

UnrecoverableTimeoutException - If the operation times out in an unrecoverable manner.

recordHistory

default boolean recordHistory()

Returns:

true if this output is configured to expect the history of the message to be written to.

writeMessage

default void writeMessage(WireKey key,
                          Object value)
                   throws UnrecoverableTimeoutException

Write a key and value which could be a scalar or a marshallable.

Parameters:

key - to write

value - to write with it.

Throws:

UnrecoverableTimeoutException

writeMessage

default void writeMessage(String eventName,
                          Object value)
                   throws UnrecoverableTimeoutException

Writes a message with a specified event name and associated object value. The method manages the lifecycle of the DocumentContext, ensuring it's closed after the message is written or if any exception occurs.

Parameters:

eventName - The name of the event associated with the message.

value - The object value to be written as part of the message.

Throws:

UnrecoverableTimeoutException - if the operation times out in an unrecoverable manner.

writeDocument

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

Writes a Marshallable object as a document or message. This method manages the lifecycle of the DocumentContext, ensuring it's closed after the document is written or if any exception occurs.

Parameters:

writer - An instance of WriteMarshallable that knows how to serialize the object.

Throws:

UnrecoverableTimeoutException - if the operation times out in an unrecoverable manner.

net.openhft.chronicle.core.io.InvalidMarshallableException - if the object cannot be serialized properly.

writeBytes

default void writeBytes(@NotNull
                        @NotNull net.openhft.chronicle.bytes.WriteBytesMarshallable marshallable)
                 throws UnrecoverableTimeoutException,
                        net.openhft.chronicle.core.io.InvalidMarshallableException

Serializes a Marshallable object directly to bytes. This method manages the lifecycle of the DocumentContext, ensuring it's closed after the serialization is done or if any exception occurs.

Parameters:

marshallable - An instance of WriteBytesMarshallable that knows how to serialize the object to bytes.

Throws:

UnrecoverableTimeoutException - if the operation times out in an unrecoverable manner.

net.openhft.chronicle.core.io.InvalidMarshallableException - if the object cannot be serialized properly.

writeDocument

default <T> void writeDocument(T t,
                               @NotNull
                               @NotNull BiConsumer<ValueOut,T> writer)
                        throws UnrecoverableTimeoutException,
                               net.openhft.chronicle.core.io.InvalidMarshallableException

Writes a provided object using a custom marshalling mechanism specified by a BiConsumer. This method allows clients to have custom serialization logic for any object. The method also manages the lifecycle of the DocumentContext, ensuring it's closed after the object is written or if any exception occurs.

Type Parameters:

T - The type of the object to be serialized.

Parameters:

t - The object to be serialized.

writer - A BiConsumer that contains the custom serialization logic.

Throws:

UnrecoverableTimeoutException - if the operation times out in an unrecoverable manner.

net.openhft.chronicle.core.io.InvalidMarshallableException - if the object cannot be serialized properly.

writeText

default void writeText(@NotNull
                       @NotNull CharSequence text)
                throws UnrecoverableTimeoutException

Writes a provided text message into the underlying DocumentContext. The method manages the lifecycle of the context, ensuring it's closed after the text is written or if any exception occurs.

Parameters:

text - The text message to be written.

Throws:

UnrecoverableTimeoutException - if the operation times out in an unrecoverable manner.

writeMap

default void writeMap(@NotNull
                      @NotNull Map<?,?> map)
               throws UnrecoverableTimeoutException

Writes a provided map into the underlying DocumentContext as a marshallable object. Each key-value pair in the map is serialized individually. The method manages the lifecycle of the context, ensuring it's closed after the map is written or if any exception occurs.

Parameters:

map - The map to be serialized and written.

Throws:

UnrecoverableTimeoutException - if the operation times out in an unrecoverable manner.

methodWriter

@NotNull
default <T> T methodWriter(@NotNull
                                    @NotNull Class<T> tClass,
                                    Class<?>... additional)

Creates a proxy of the specified interfaces, where each method call on the proxy is written for replay. The primary interface is always implemented by the proxy, whereas any additional interfaces have to be cast to be accessed on the proxy.

Parameters:

tClass - primary interface

additional - any additional interfaces

Returns:

a proxy which implements the primary interface (additional interfaces have to be cast)

methodWriterBuilder

@NotNull
default <T> @NotNull net.openhft.chronicle.bytes.MethodWriterBuilder<T> methodWriterBuilder(@NotNull
                                                                                                     @NotNull Class<T> tClass)

Returns a MethodWriterBuilder that can be used to create a proxy for an interface. Each message called on the proxy will be written for replay. This is a convenience method that assumes metadata is not required.

Parameters:

tClass - The primary interface that the builder will cater to.

Returns:

A MethodWriterBuilder tailored for the given interface class.

methodWriterBuilder

@NotNull
default <T> @NotNull net.openhft.chronicle.bytes.MethodWriterBuilder<T> methodWriterBuilder(boolean metaData,
                                                                                                     @NotNull
                                                                                                     @NotNull Class<T> tClass)

Returns a MethodWriterBuilder that can be used to create a proxy for an interface. Depending on the metaData parameter, every method may be written as metadata. Each message called on the proxy will be written to a file for method replay.

Parameters:

metaData - If set to true, every method call will be written as metadata.

tClass - The primary interface that the builder will cater to.

Returns:

A MethodWriterBuilder tailored for the given interface class and metadata preference.