Package io.temporal.common.converter

Interface DataConverter

All Known Implementing Classes:

CodecDataConverter, DefaultDataConverter

public interface DataConverter

Used by the framework to serialize/deserialize method parameters that need to be sent over the wire.

Most users should never implement this interface until absolutely needed.

Instead, users should implement

• PayloadConverter to customize Object <-> Payload (bytes) conversion
• PayloadCodec to perform Payload (bytes) <-> Payload (bytes) encoding (like encryption or compression)

A custom PayloadConverter can be registered on DefaultDataConverter instance. For that:

• Obtain DefaultDataConverter instance from DefaultDataConverter.newDefaultInstance(). Register your custom PayloadConverter using DefaultDataConverter.withPayloadConverterOverrides(PayloadConverter...). This way will preserve the standard set of PayloadConverters supplied by Temporal JavaSDK other that the ones that were overridden. See DefaultDataConverter.STANDARD_PAYLOAD_CONVERTERS)
• Pass the custom PayloadConverter directly to DefaultDataConverter(PayloadConverter...) to discard the standard PayloadConverters supplied by Temporal JavaSDK out of the box.

A DataConverter created on previous step may be bundled with PayloadCodecs using CodecDataConverter or used directly if no custom PayloadCodecs are needed.

Method Summary

Modifier and Type	Method	Description
static java.lang.Object[]	arrayFromPayloads(DataConverter converter, java.util.Optional<io.temporal.api.common.v1.Payloads> content, java.lang.Class<?>[] parameterTypes, java.lang.reflect.Type[] genericParameterTypes)	Deprecated. use fromPayloads(int, Optional, Class, Type).
default io.temporal.api.failure.v1.Failure	exceptionToFailure(java.lang.Throwable throwable)	Serialize an existing Throwable object into a Failure object.
default TemporalFailure	failureToException(io.temporal.api.failure.v1.Failure failure)	Instantiate an appropriate Java Exception from a serialized Failure object.
<T> T	fromPayload(io.temporal.api.common.v1.Payload payload, java.lang.Class<T> valueClass, java.lang.reflect.Type valueType)
<T> T	fromPayloads(int index, java.util.Optional<io.temporal.api.common.v1.Payloads> content, java.lang.Class<T> valueType, java.lang.reflect.Type valueGenericType)	Implements conversion of a single Payload from the serialized Payloads.
default java.lang.Object[]	fromPayloads(java.util.Optional<io.temporal.api.common.v1.Payloads> content, java.lang.Class<?>[] parameterTypes, java.lang.reflect.Type[] genericParameterTypes)	Implements conversion of the whole content Payloads into an array of values of different types.
static DataConverter	getDefaultInstance()	Deprecated. use GlobalDataConverter.get()
<T> java.util.Optional<io.temporal.api.common.v1.Payload>	toPayload(T value)
java.util.Optional<io.temporal.api.common.v1.Payloads>	toPayloads(java.lang.Object... values)	Implements conversion of a list of values.
default DataConverter	withContext(SerializationContext context)	A correct implementation of this interface should have a fully functional "contextless" implementation.

Method Detail

getDefaultInstance

@Deprecated
static DataConverter getDefaultInstance()

Deprecated.

use GlobalDataConverter.get()

toPayload

<T> java.util.Optional<io.temporal.api.common.v1.Payload> toPayload(T value)
                                                             throws DataConverterException

Parameters:

value - value to convert

Returns:

a Payload which is a protobuf message containing byte-array serialized representation of value. Optional here is for legacy and backward compatibility reasons. This Optional is expected to always be filled.

Throws:

DataConverterException - if conversion fails

fromPayload

<T> T fromPayload(io.temporal.api.common.v1.Payload payload,
                  java.lang.Class<T> valueClass,
                  java.lang.reflect.Type valueType)
           throws DataConverterException

Throws:

DataConverterException

toPayloads

java.util.Optional<io.temporal.api.common.v1.Payloads> toPayloads(java.lang.Object... values)
                                                           throws DataConverterException

Implements conversion of a list of values.

Parameters:

values - Java values to convert to String.

Returns:

converted value. Return empty Optional if values are empty.

Throws:

DataConverterException - if conversion of the value passed as parameter failed for any reason.

fromPayloads

<T> T fromPayloads(int index,
                   java.util.Optional<io.temporal.api.common.v1.Payloads> content,
                   java.lang.Class<T> valueType,
                   java.lang.reflect.Type valueGenericType)
            throws DataConverterException

Implements conversion of a single Payload from the serialized Payloads.

Parameters:

index - index of the value in the payloads

content - serialized value to convert to Java objects.

valueType - type of the value stored in the content

valueGenericType - generic type of the value stored in the content

Returns:

converted Java object

Throws:

DataConverterException - if conversion of the data passed as parameter failed for any reason.

fromPayloads

default java.lang.Object[] fromPayloads(java.util.Optional<io.temporal.api.common.v1.Payloads> content,
                                        java.lang.Class<?>[] parameterTypes,
                                        java.lang.reflect.Type[] genericParameterTypes)
                                 throws DataConverterException

Implements conversion of the whole content Payloads into an array of values of different types.

Implementation note
This method is expected to return an array of the same length as parameterTypes. If content has not enough Payload elements, this method provides default instances.

Parameters:

content - serialized value to convert to Java objects.

parameterTypes - types of the values stored in the @code content}

genericParameterTypes - generic types of the values stored in the content

Returns:

array if converted Java objects

Throws:

DataConverterException - if conversion of the data passed as parameter failed for any reason.

failureToException

@Nonnull
default TemporalFailure failureToException(@Nonnull
                                           io.temporal.api.failure.v1.Failure failure)

Instantiate an appropriate Java Exception from a serialized Failure object. The default implementation delegates the conversion process to an instance of FailureConverter, using this data converter for payload decoding.

Parameters:

failure - Failure protobuf object to deserialize into an exception

Throws:

java.lang.NullPointerException - if failure is null

exceptionToFailure

@Nonnull
default io.temporal.api.failure.v1.Failure exceptionToFailure(@Nonnull
                                                              java.lang.Throwable throwable)

Serialize an existing Throwable object into a Failure object. The default implementation delegates the conversion process to an instance of FailureConverter, using this data converter for payload encoding.

Parameters:

throwable - a Throwable object to serialize into a Failure protobuf object

Throws:

java.lang.NullPointerException - if throwable is null

withContext

@Nonnull
default DataConverter withContext(@Nonnull
                                  SerializationContext context)

A correct implementation of this interface should have a fully functional "contextless" implementation. Temporal SDK will call this method when a knowledge of the context exists, but DataConverter can be used directly by user code and sometimes SDK itself without any context.

Note: this method is expected to be cheap and fast. Temporal SDK doesn't always cache the instances and may be calling this method very often. Users are responsible to make sure that this method doesn't recreate expensive objects like Jackson's ObjectMapper on every call.

Parameters:

context - provides information to the data converter about the abstraction the data belongs to

Returns:

an instance of DataConverter that may use the provided context for serialization

See Also:

SerializationContext

arrayFromPayloads

@Deprecated
static java.lang.Object[] arrayFromPayloads(DataConverter converter,
                                            java.util.Optional<io.temporal.api.common.v1.Payloads> content,
                                            java.lang.Class<?>[] parameterTypes,
                                            java.lang.reflect.Type[] genericParameterTypes)
                                     throws DataConverterException

Deprecated.

use fromPayloads(int, Optional, Class, Type). This is an SDK implementation detail and never was expected to be exposed to users.

Throws:

DataConverterException