Typed search attributes (#1782)

Author: cretz

temporal-sdk/src/main/java/io/temporal/client/WorkflowExecutionMetadata.java

@@ -25,6 +25,7 @@
 import io.temporal.api.common.v1.WorkflowExecution;
 import io.temporal.api.enums.v1.WorkflowExecutionStatus;
 import io.temporal.api.workflow.v1.WorkflowExecutionInfo;
+import io.temporal.common.SearchAttributes;
 import io.temporal.common.converter.DataConverter;
 import io.temporal.internal.common.ProtobufTimeUtils;
 import io.temporal.internal.common.SearchAttributesUtil;
@@ -96,11 +97,21 @@ public WorkflowExecution getParentExecution() {
     return info.hasParentExecution() ? info.getParentExecution() : null;
   }
 
+  /**
+   * @deprecated use {@link #getTypedSearchAttributes} instead.
+   */
+  @Deprecated
   @Nonnull
   public Map<String, List<?>> getSearchAttributes() {
     return Collections.unmodifiableMap(SearchAttributesUtil.decode(info.getSearchAttributes()));
   }
 
+  /** Get search attributes as a typed set. */
+  @Nonnull
+  public SearchAttributes getTypedSearchAttributes() {
+    return SearchAttributesUtil.decodeTyped(info.getSearchAttributes());
+  }
+
   @Nullable
   public <T> Object getMemo(String key, Class<T> valueClass) {
     return getMemo(key, valueClass, valueClass);

temporal-sdk/src/main/java/io/temporal/client/WorkflowOptions.java

@@ -25,6 +25,7 @@
 import io.temporal.common.CronSchedule;
 import io.temporal.common.MethodRetry;
 import io.temporal.common.RetryOptions;
+import io.temporal.common.SearchAttributes;
 import io.temporal.common.context.ContextPropagator;
 import io.temporal.internal.common.OptionsUtils;
 import io.temporal.worker.WorkerFactory;
@@ -72,6 +73,7 @@ public static WorkflowOptions merge(
         .setCronSchedule(OptionsUtils.merge(cronAnnotation, o.getCronSchedule(), String.class))
         .setMemo(o.getMemo())
         .setSearchAttributes(o.getSearchAttributes())
+        .setTypedSearchAttributes(o.getTypedSearchAttributes())
         .setContextPropagators(o.getContextPropagators())
         .setDisableEagerExecution(o.isDisableEagerExecution())
         .validateBuildWithDefaults();
@@ -99,6 +101,8 @@ public static final class Builder {
 
     private Map<String, ?> searchAttributes;
 
+    private SearchAttributes typedSearchAttributes;
+
     private List<ContextPropagator> contextPropagators;
 
     private boolean disableEagerExecution;
@@ -119,6 +123,7 @@ private Builder(WorkflowOptions options) {
       this.cronSchedule = options.cronSchedule;
       this.memo = options.memo;
       this.searchAttributes = options.searchAttributes;
+      this.typedSearchAttributes = options.typedSearchAttributes;
       this.contextPropagators = options.contextPropagators;
       this.disableEagerExecution = options.disableEagerExecution;
     }
@@ -265,13 +270,40 @@ public Builder setMemo(Map<String, Object> memo) {
      *   <li>OffsetDateTime
      *   <li>{@link Collection} of the types above
      * </ul>
+     *
+     * @deprecated use {@link #setTypedSearchAttributes} instead.
      */
     // Workflow#upsertSearchAttributes docs needs to be kept in sync with this method
+    @Deprecated
     public Builder setSearchAttributes(Map<String, ?> searchAttributes) {
+      if (searchAttributes != null
+          && !searchAttributes.isEmpty()
+          && this.typedSearchAttributes != null) {
+        throw new IllegalArgumentException(
+            "Cannot have search attributes and typed search attributes");
+      }
       this.searchAttributes = searchAttributes;
       return this;
     }
 
+    /**
+     * Specifies Search Attributes that will be attached to the Workflow. Search Attributes are
+     * additional indexed information attributed to workflow and used for search and visibility.
+     *
+     * <p>The search attributes can be used in query of List/Scan/Count workflow APIs. The key and
+     * its value type must be registered on Temporal server side.
+     */
+    public Builder setTypedSearchAttributes(SearchAttributes typedSearchAttributes) {
+      if (typedSearchAttributes != null
+          && searchAttributes != null
+          && !searchAttributes.isEmpty()) {
+        throw new IllegalArgumentException(
+            "Cannot have typed search attributes and search attributes");
+      }
+      this.typedSearchAttributes = typedSearchAttributes;
+      return this;
+    }
+
     /**
      * This list of context propagators overrides the list specified on {@link
      * WorkflowClientOptions#getContextPropagators()}. <br>
@@ -319,6 +351,7 @@ public WorkflowOptions build() {
           cronSchedule,
           memo,
           searchAttributes,
+          typedSearchAttributes,
           contextPropagators,
           disableEagerExecution);
     }
@@ -338,6 +371,7 @@ public WorkflowOptions validateBuildWithDefaults() {
           cronSchedule,
           memo,
           searchAttributes,
+          typedSearchAttributes,
           contextPropagators,
           disableEagerExecution);
     }
@@ -363,6 +397,8 @@ public WorkflowOptions validateBuildWithDefaults() {
 
   private final Map<String, ?> searchAttributes;
 
+  private final SearchAttributes typedSearchAttributes;
+
   private final List<ContextPropagator> contextPropagators;
 
   private final boolean disableEagerExecution;
@@ -378,6 +414,7 @@ private WorkflowOptions(
       String cronSchedule,
       Map<String, Object> memo,
       Map<String, ?> searchAttributes,
+      SearchAttributes typedSearchAttributes,
       List<ContextPropagator> contextPropagators,
       boolean disableEagerExecution) {
     this.workflowId = workflowId;
@@ -390,6 +427,7 @@ private WorkflowOptions(
     this.cronSchedule = cronSchedule;
     this.memo = memo;
     this.searchAttributes = searchAttributes;
+    this.typedSearchAttributes = typedSearchAttributes;
     this.contextPropagators = contextPropagators;
     this.disableEagerExecution = disableEagerExecution;
   }
@@ -430,10 +468,18 @@ public Map<String, Object> getMemo() {
     return memo;
   }
 
+  /**
+   * @deprecated use {@link #getTypedSearchAttributes} instead.
+   */
+  @Deprecated
   public Map<String, ?> getSearchAttributes() {
     return searchAttributes;
   }
 
+  public SearchAttributes getTypedSearchAttributes() {
+    return typedSearchAttributes;
+  }
+
   /**
    * @return the list of context propagators to use during this workflow. This list overrides the
    *     list specified on {@link WorkflowClientOptions#getContextPropagators()}, {@code null} means
@@ -466,6 +512,7 @@ public boolean equals(Object o) {
         && Objects.equal(cronSchedule, that.cronSchedule)
         && Objects.equal(memo, that.memo)
         && Objects.equal(searchAttributes, that.searchAttributes)
+        && Objects.equal(typedSearchAttributes, that.typedSearchAttributes)
         && Objects.equal(contextPropagators, that.contextPropagators)
         && Objects.equal(disableEagerExecution, that.disableEagerExecution);
   }
@@ -483,6 +530,7 @@ public int hashCode() {
         cronSchedule,
         memo,
         searchAttributes,
+        typedSearchAttributes,
         contextPropagators,
         disableEagerExecution);
   }
@@ -513,6 +561,8 @@ public String toString() {
         + memo
         + ", searchAttributes="
         + searchAttributes
+        + ", typedSearchAttributes="
+        + typedSearchAttributes
         + ", contextPropagators="
         + contextPropagators
         + ", disableEagerExecution="

temporal-sdk/src/main/java/io/temporal/common/SearchAttribute.java

@@ -24,6 +24,10 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * @deprecated typed search attributes should be used instead.
+ */
+@Deprecated
 public class SearchAttribute {
   /**
    * Passing this value as a search attribute value into {@link

temporal-sdk/src/main/java/io/temporal/common/SearchAttributeKey.java

@@ -0,0 +1,152 @@
+/*
+ * 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;
+
+import com.google.common.reflect.TypeToken;
+import io.temporal.api.enums.v1.IndexedValueType;
+import java.lang.reflect.Type;
+import java.time.OffsetDateTime;
+import java.util.List;
+import java.util.Objects;
+import javax.annotation.Nonnull;
+
+/** Representation of a typed search attribute key. */
+public class SearchAttributeKey<T> implements Comparable<SearchAttributeKey<T>> {
+  private static final Type KEYWORD_LIST_REFLECT_TYPE = new TypeToken<List<String>>() {}.getType();
+
+  /** Create a search attribute key for a text attribute type. */
+  public static SearchAttributeKey<String> forText(String name) {
+    return new SearchAttributeKey<>(name, IndexedValueType.INDEXED_VALUE_TYPE_TEXT, String.class);
+  }
+
+  /** Create a search attribute key for a keyword attribute type. */
+  public static SearchAttributeKey<String> forKeyword(String name) {
+    return new SearchAttributeKey<>(
+        name, IndexedValueType.INDEXED_VALUE_TYPE_KEYWORD, String.class);
+  }
+
+  /** Create a search attribute key for an int attribute type. */
+  public static SearchAttributeKey<Long> forLong(String name) {
+    return new SearchAttributeKey<>(name, IndexedValueType.INDEXED_VALUE_TYPE_INT, Long.class);
+  }
+
+  /** Create a search attribute key for a double attribute type. */
+  public static SearchAttributeKey<Double> forDouble(String name) {
+    return new SearchAttributeKey<>(name, IndexedValueType.INDEXED_VALUE_TYPE_DOUBLE, Double.class);
+  }
+
+  /** Create a search attribute key for a boolean attribute type. */
+  public static SearchAttributeKey<Boolean> forBoolean(String name) {
+    return new SearchAttributeKey<>(name, IndexedValueType.INDEXED_VALUE_TYPE_BOOL, Boolean.class);
+  }
+
+  /** Create a search attribute key for a datetime attribute type. */
+  public static SearchAttributeKey<OffsetDateTime> forOffsetDateTime(String name) {
+    return new SearchAttributeKey<>(
+        name, IndexedValueType.INDEXED_VALUE_TYPE_DATETIME, OffsetDateTime.class);
+  }
+
+  /** Create a search attribute key for a keyword list attribute type. */
+  public static SearchAttributeKey<List<String>> forKeywordList(String name) {
+    return new SearchAttributeKey<>(
+        name,
+        IndexedValueType.INDEXED_VALUE_TYPE_KEYWORD_LIST,
+        List.class,
+        KEYWORD_LIST_REFLECT_TYPE);
+  }
+
+  private final String name;
+  private final IndexedValueType valueType;
+  private final Class<? super T> valueClass;
+  private final Type valueReflectType;
+
+  private SearchAttributeKey(String name, IndexedValueType valueType, Class<? super T> valueClass) {
+    this(name, valueType, valueClass, valueClass);
+  }
+
+  private SearchAttributeKey(
+      String name, IndexedValueType valueType, Class<? super T> valueClass, Type valueReflectType) {
+    this.name = name;
+    this.valueType = valueType;
+    this.valueClass = valueClass;
+    this.valueReflectType = valueReflectType;
+  }
+
+  /** Get the name of the search attribute. */
+  public String getName() {
+    return name;
+  }
+
+  /** Get the search attribute value type. */
+  public IndexedValueType getValueType() {
+    return valueType;
+  }
+
+  /** Get the class that the search attribute value will be. */
+  public Class<? super T> getValueClass() {
+    return valueClass;
+  }
+
+  /**
+   * Get the reflect type that the search attribute will be. For all key types except keyword list,
+   * this is the same as {@link #getValueType}.
+   */
+  public Type getValueReflectType() {
+    return valueReflectType;
+  }
+
+  /** Create an update that sets a value for this key. */
+  public SearchAttributeUpdate<T> valueSet(@Nonnull T value) {
+    return SearchAttributeUpdate.valueSet(this, value);
+  }
+
+  /** Create an update that unsets a value for this key. */
+  public SearchAttributeUpdate<T> valueUnset() {
+    return SearchAttributeUpdate.valueUnset(this);
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (o == null || getClass() != o.getClass()) return false;
+    SearchAttributeKey<?> that = (SearchAttributeKey<?>) o;
+    return name.equals(that.name)
+        && valueType == that.valueType
+        && valueClass.equals(that.valueClass);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(name, valueType, valueClass);
+  }
+
+  @Override
+  public int compareTo(SearchAttributeKey<T> o) {
+    int c = name.compareTo(o.name);
+    if (c == 0) {
+      c = valueType.compareTo(o.valueType);
+    }
+    if (c == 0) {
+      c = valueClass.getName().compareTo(o.valueClass.getName());
+    }
+    return c;
+  }
+}