#156

pending completion

Build # #156

Build Type

push

github-actions

Committed by

web-flow

Commit Message

Provide SerializationContext for PayloadConverter and PayloadCodec (#1695)

Issue #1694

Run Details

497 of 497 new or added lines in 32 files covered. (100.0%)

16928 of 20806 relevant lines covered (81.36%)

0.81 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

71.43

/temporal-sdk/src/main/java/io/temporal/common/converter/DataConverter.java

/*
 * Copyright (C) 2022 Temporal Technologies, Inc. All Rights Reserved.
 *
 * Copyright (C) 2012-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *
 * Modifications copyright (C) 2017 Uber Technologies, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this material except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package io.temporal.common.converter;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.google.common.base.Defaults;
import io.temporal.api.common.v1.Payload;
import io.temporal.api.common.v1.Payloads;
import io.temporal.api.failure.v1.Failure;
import io.temporal.common.Experimental;
import io.temporal.failure.TemporalFailure;
import io.temporal.payload.codec.PayloadCodec;
import io.temporal.payload.context.SerializationContext;
import java.lang.reflect.Type;
import java.util.Arrays;
import java.util.Optional;
import javax.annotation.Nonnull;

/**
 * Used by the framework to serialize/deserialize method parameters that need to be sent over the
 * wire.
 *
 * <h2>Most users should never implement this interface until absolutely needed.</h2>
 *
 * Instead, users should implement
 *
 * <ul>
 *   <li>{@link PayloadConverter} to customize Object &lt;-&gt; Payload (bytes) conversion
 *   <li>{@link PayloadCodec} to perform Payload (bytes) &lt;-&gt; Payload (bytes) encoding (like
 *       encryption or compression)
 * </ul>
 *
 * A custom {@link PayloadConverter} can be registered on {@link DefaultDataConverter} instance. For
 * that:
 *
 * <ul>
 *   <li>Obtain {@link DefaultDataConverter} instance from {@link
 *       DefaultDataConverter#newDefaultInstance()}. Register your custom {@link PayloadConverter}
 *       using {@link DefaultDataConverter#withPayloadConverterOverrides(PayloadConverter...)}. This
 *       way will preserve the standard set of {@link PayloadConverter}s supplied by Temporal
 *       JavaSDK other that the ones that were overridden. See {@link
 *       DefaultDataConverter#STANDARD_PAYLOAD_CONVERTERS})
 *   <li>Pass the custom {@link PayloadConverter} directly to {@link
 *       DefaultDataConverter#DefaultDataConverter(PayloadConverter...)} to discard the standard
 *       {@link PayloadConverter}s supplied by Temporal JavaSDK out of the box.
 * </ul>
 *
 * A {@link DataConverter} created on previous step may be bundled with {@link PayloadCodec}s using
 * {@link CodecDataConverter} or used directly if no custom {@link PayloadCodec}s are needed.
 */
public interface DataConverter {

  /**
   * @deprecated use {@link GlobalDataConverter#get()}
   */
  @Deprecated
  static DataConverter getDefaultInstance() {
    return GlobalDataConverter.get();
  }

  /**
   * @param value value to convert
   * @return a {@link Payload} which is a protobuf message containing byte-array serialized
   *     representation of {@code value}. Optional here is for legacy and backward compatibility
   *     reasons. This Optional is expected to always be filled.
   * @throws DataConverterException if conversion fails
   */
  <T> Optional<Payload> toPayload(T value) throws DataConverterException;

  <T> T fromPayload(Payload payload, Class<T> valueClass, Type valueType)
      throws DataConverterException;

  /**
   * Implements conversion of a list of values.
   *
   * @param values Java values to convert to String.
   * @return converted value. Return empty Optional if values are empty.
   * @throws DataConverterException if conversion of the value passed as parameter failed for any
   *     reason.
   */
  Optional<Payloads> toPayloads(Object... values) throws DataConverterException;

  /**
   * Implements conversion of an array of values of different types. Useful for deserializing
   * arguments of function invocations.
   *
   * @param index index of the value in the payloads
   * @param content serialized value to convert to Java objects.
   * @param valueType type of the value stored in the content
   * @param valueGenericType generic type of the value stored in the content
   * @return converted Java object
   * @throws DataConverterException if conversion of the data passed as parameter failed for any
   *     reason.
   */
  <T> T fromPayloads(
      int index, Optional<Payloads> content, Class<T> valueType, Type valueGenericType)
      throws DataConverterException;

  /**
   * Instantiate an appropriate Java Exception from a serialized Failure object. The default
   * implementation delegates the conversion process to an instance of {@link FailureConverter},
   * using this data converter for payload decoding.
   *
   * @param failure Failure protobuf object to deserialize into an exception
   * @throws NullPointerException if failure is null
   */
  @Nonnull
  TemporalFailure failureToException(@Nonnull Failure failure);

  /**
   * Serialize an existing Throwable object into a Failure object. The default implementation
   * delegates the conversion process to an instance of {@link FailureConverter}, using this data
   * converter for payload encoding.
   *
   * @param throwable a Throwable object to serialize into a Failure protobuf object
   * @throws NullPointerException if throwable is null
   */
  @Nonnull
  Failure exceptionToFailure(@Nonnull Throwable throwable);

  static Object[] arrayFromPayloads(
      DataConverter converter,
      Optional<Payloads> content,
      Class<?>[] parameterTypes,
      Type[] genericParameterTypes)
      throws DataConverterException {
    if (parameterTypes != null
        && (genericParameterTypes == null
            || parameterTypes.length != genericParameterTypes.length)) {
      throw new IllegalArgumentException(
          "parameterTypes don't match length of valueTypes: "
              + Arrays.toString(parameterTypes)
              + "<>"
              + Arrays.toString(genericParameterTypes));
    }

    int length = parameterTypes.length;
    Object[] result = new Object[length];
    if (!content.isPresent()) {
      // Return defaults for all the parameters
      for (int i = 0; i < parameterTypes.length; i++) {
        result[i] = Defaults.defaultValue((Class<?>) genericParameterTypes[i]);
      }
      return result;
    }
    Payloads payloads = content.get();
    int count = payloads.getPayloadsCount();
    for (int i = 0; i < parameterTypes.length; i++) {
      Class<?> pt = parameterTypes[i];
      Type gt = genericParameterTypes[i];
      if (i >= count) {
        result[i] = Defaults.defaultValue((Class<?>) gt);
      } else {
        result[i] = converter.fromPayload(payloads.getPayloads(i), pt, gt);
      }
    }
    return result;
  }

  /**
   * 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
   * {@link DataConverter} can be used directly by user code and sometimes SDK itself without any
   * context.
   *
   * <p>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 {@link ObjectMapper} on every
   * call.
   *
   * @param context provides information to the data converter about the abstraction the data
   *     belongs to
   * @return an instance of DataConverter that may use the provided {@code context} for
   *     serialization
   * @see SerializationContext
   */
  @Experimental
  @Nonnull
  default DataConverter withContext(@Nonnull SerializationContext context) {
    return this;
  }
}

1	/*
2	* Copyright (C) 2022 Temporal Technologies, Inc. All Rights Reserved.
3	*
4	* Copyright (C) 2012-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
5	*
6	* Modifications copyright (C) 2017 Uber Technologies, Inc.
7	*
8	* Licensed under the Apache License, Version 2.0 (the "License");
9	* you may not use this material except in compliance with the License.
10	* You may obtain a copy of the License at
11	*
12	* http://www.apache.org/licenses/LICENSE-2.0
13	*
14	* Unless required by applicable law or agreed to in writing, software
15	* distributed under the License is distributed on an "AS IS" BASIS,
16	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17	* See the License for the specific language governing permissions and
18	* limitations under the License.
19	*/
20
21	package io.temporal.common.converter;
22
23	import com.fasterxml.jackson.databind.ObjectMapper;
24	import com.google.common.base.Defaults;
25	import io.temporal.api.common.v1.Payload;
26	import io.temporal.api.common.v1.Payloads;
27	import io.temporal.api.failure.v1.Failure;
28	import io.temporal.common.Experimental;
29	import io.temporal.failure.TemporalFailure;
30	import io.temporal.payload.codec.PayloadCodec;
31	import io.temporal.payload.context.SerializationContext;
32	import java.lang.reflect.Type;
33	import java.util.Arrays;
34	import java.util.Optional;
35	import javax.annotation.Nonnull;
36
37	/**
38	* Used by the framework to serialize/deserialize method parameters that need to be sent over the
39	* wire.
40	*
41	* <h2>Most users should never implement this interface until absolutely needed.</h2>
42	*
43	* Instead, users should implement
44	*
45	* <ul>
46	* <li>{@link PayloadConverter} to customize Object <-> Payload (bytes) conversion
47	* <li>{@link PayloadCodec} to perform Payload (bytes) <-> Payload (bytes) encoding (like
48	* encryption or compression)
49	* </ul>
50	*
51	* A custom {@link PayloadConverter} can be registered on {@link DefaultDataConverter} instance. For
52	* that:
53	*
54	* <ul>
55	* <li>Obtain {@link DefaultDataConverter} instance from {@link
56	* DefaultDataConverter#newDefaultInstance()}. Register your custom {@link PayloadConverter}
57	* using {@link DefaultDataConverter#withPayloadConverterOverrides(PayloadConverter...)}. This
58	* way will preserve the standard set of {@link PayloadConverter}s supplied by Temporal
59	* JavaSDK other that the ones that were overridden. See {@link
60	* DefaultDataConverter#STANDARD_PAYLOAD_CONVERTERS})
61	* <li>Pass the custom {@link PayloadConverter} directly to {@link
62	* DefaultDataConverter#DefaultDataConverter(PayloadConverter...)} to discard the standard
63	* {@link PayloadConverter}s supplied by Temporal JavaSDK out of the box.
64	* </ul>
65	*
66	* A {@link DataConverter} created on previous step may be bundled with {@link PayloadCodec}s using
67	* {@link CodecDataConverter} or used directly if no custom {@link PayloadCodec}s are needed.
68	*/
69	public interface DataConverter {
70
71	/**
72	* @deprecated use {@link GlobalDataConverter#get()}
73	*/
74	@Deprecated
75	static DataConverter getDefaultInstance() {
76	return GlobalDataConverter.get();	×
77	}
78
79	/**
80	* @param value value to convert
81	* @return a {@link Payload} which is a protobuf message containing byte-array serialized
82	* representation of {@code value}. Optional here is for legacy and backward compatibility
83	* reasons. This Optional is expected to always be filled.
84	* @throws DataConverterException if conversion fails
85	*/
86	<T> Optional<Payload> toPayload(T value) throws DataConverterException;
87
88	<T> T fromPayload(Payload payload, Class<T> valueClass, Type valueType)
89	throws DataConverterException;
90
91	/**
92	* Implements conversion of a list of values.
93	*
94	* @param values Java values to convert to String.
95	* @return converted value. Return empty Optional if values are empty.
96	* @throws DataConverterException if conversion of the value passed as parameter failed for any
97	* reason.
98	*/
99	Optional<Payloads> toPayloads(Object... values) throws DataConverterException;
100
101	/**
102	* Implements conversion of an array of values of different types. Useful for deserializing
103	* arguments of function invocations.
104	*
105	* @param index index of the value in the payloads
106	* @param content serialized value to convert to Java objects.
107	* @param valueType type of the value stored in the content
108	* @param valueGenericType generic type of the value stored in the content
109	* @return converted Java object
110	* @throws DataConverterException if conversion of the data passed as parameter failed for any
111	* reason.
112	*/
113	<T> T fromPayloads(
114	int index, Optional<Payloads> content, Class<T> valueType, Type valueGenericType)
115	throws DataConverterException;
116
117	/**
118	* Instantiate an appropriate Java Exception from a serialized Failure object. The default
119	* implementation delegates the conversion process to an instance of {@link FailureConverter},
120	* using this data converter for payload decoding.
121	*
122	* @param failure Failure protobuf object to deserialize into an exception
123	* @throws NullPointerException if failure is null
124	*/
125	@Nonnull
126	TemporalFailure failureToException(@Nonnull Failure failure);
127
128	/**
129	* Serialize an existing Throwable object into a Failure object. The default implementation
130	* delegates the conversion process to an instance of {@link FailureConverter}, using this data
131	* converter for payload encoding.
132	*
133	* @param throwable a Throwable object to serialize into a Failure protobuf object
134	* @throws NullPointerException if throwable is null
135	*/
136	@Nonnull
137	Failure exceptionToFailure(@Nonnull Throwable throwable);
138
139	static Object[] arrayFromPayloads(
140	DataConverter converter,
141	Optional<Payloads> content,
142	Class<?>[] parameterTypes,
143	Type[] genericParameterTypes)
144	throws DataConverterException {
145	if (parameterTypes != null	1✔
146	&& (genericParameterTypes == null
147	\|\| parameterTypes.length != genericParameterTypes.length)) {
148	throw new IllegalArgumentException(	×
149	"parameterTypes don't match length of valueTypes: "
150	+ Arrays.toString(parameterTypes)	×
151	+ "<>"
152	+ Arrays.toString(genericParameterTypes));	×
153	}
154
155	int length = parameterTypes.length;	1✔
156	Object[] result = new Object[length];	1✔
157	if (!content.isPresent()) {	1✔
158	// Return defaults for all the parameters
159	for (int i = 0; i < parameterTypes.length; i++) {	1✔
160	result[i] = Defaults.defaultValue((Class<?>) genericParameterTypes[i]);	×
161	}
162	return result;	1✔
163	}
164	Payloads payloads = content.get();	1✔
165	int count = payloads.getPayloadsCount();	1✔
166	for (int i = 0; i < parameterTypes.length; i++) {	1✔
167	Class<?> pt = parameterTypes[i];	1✔
168	Type gt = genericParameterTypes[i];	1✔
169	if (i >= count) {	1✔
170	result[i] = Defaults.defaultValue((Class<?>) gt);	1✔
171	} else {
172	result[i] = converter.fromPayload(payloads.getPayloads(i), pt, gt);	1✔
173	}
174	}
175	return result;	1✔
176	}
177
178	/**
179	* A correct implementation of this interface should have a fully functional "contextless"
180	* implementation. Temporal SDK will call this method when a knowledge of the context exists, but
181	* {@link DataConverter} can be used directly by user code and sometimes SDK itself without any
182	* context.
183	*
184	* <p>Note: this method is expected to be cheap and fast. Temporal SDK doesn't always cache the
185	* instances and may be calling this method very often. Users are responsible to make sure that
186	* this method doesn't recreate expensive objects like Jackson's {@link ObjectMapper} on every
187	* call.
188	*
189	* @param context provides information to the data converter about the abstraction the data
190	* belongs to
191	* @return an instance of DataConverter that may use the provided {@code context} for
192	* serialization
193	* @see SerializationContext
194	*/
195	@Experimental
196	@Nonnull
197	default DataConverter withContext(@Nonnull SerializationContext context) {
198	return this;	×
199	}
200	}

temporalio / sdk-java / #156

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous