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 implementPayloadConverter
to customize Object <-> Payload (bytes) conversionPayloadCodec
to perform Payload (bytes) <-> Payload (bytes) encoding (like encryption or compression)
PayloadConverter
can be registered onDefaultDataConverter
instance. For that:- Obtain
DefaultDataConverter
instance fromDefaultDataConverter.newDefaultInstance()
. Register your customPayloadConverter
usingDefaultDataConverter.withPayloadConverterOverrides(PayloadConverter...)
. This way will preserve the standard set ofPayloadConverter
s supplied by Temporal JavaSDK other that the ones that were overridden. SeeDefaultDataConverter.STANDARD_PAYLOAD_CONVERTERS
) - Pass the custom
PayloadConverter
directly toDefaultDataConverter(PayloadConverter...)
to discard the standardPayloadConverter
s supplied by Temporal JavaSDK out of the box.
DataConverter
created on previous step may be bundled withPayloadCodec
s usingCodecDataConverter
or used directly if no customPayloadCodec
s are needed.
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods 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)
io.temporal.api.failure.v1.Failure
exceptionToFailure(java.lang.Throwable throwable)
Serialize an existing Throwable object into a Failure object.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 an array of values of different types.static DataConverter
getDefaultInstance()
Deprecated.<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.
-
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 ofvalue
. 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 an array of values of different types. Useful for deserializing arguments of function invocations.- Parameters:
index
- index of the value in the payloadscontent
- serialized value to convert to Java objects.valueType
- type of the value stored in the contentvalueGenericType
- 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.
-
failureToException
@Nonnull 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 ofFailureConverter
, 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 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 ofFailureConverter
, 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
-
arrayFromPayloads
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
- Throws:
DataConverterException
-
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, butDataConverter
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
-
-