Port go-client changes to support the enhanced versioning feature

Author: pandeyanshuman

src/main/java/com/uber/cadence/internal/replay/ClockDecisionContext.java

@@ -320,6 +320,11 @@ private void handleVersionMarker(MarkerRecordedEventAttributes attributes) {
 
   GetVersionResult getVersion(
       String changeId, DataConverter converter, int minSupported, int maxSupported) {
+    return getVersion(changeId, converter, minSupported, maxSupported, GetVersionOptions.newBuilder().build());
+  }
+
+  GetVersionResult getVersion(
+      String changeId, DataConverter converter, int minSupported, int maxSupported, GetVersionOptions options) {
     Predicate<MarkerRecordedEventAttributes> changeIdEquals =
         (attributes) -> {
           MarkerHandler.MarkerInterface markerData =
@@ -328,6 +333,9 @@ GetVersionResult getVersion(
         };
     decisions.addAllMissingVersionMarker(true, Optional.of(changeIdEquals));
 
+    // Determine which version to use based on options
+    int versionToUse = determineVersionToUse(minSupported, maxSupported, options);
+
     final MarkerHandler.HandleResult result =
         versionHandler.handle(
             changeId,
@@ -336,14 +344,14 @@ GetVersionResult getVersion(
               if (stored.isPresent()) {
                 return Optional.empty();
               }
-              return Optional.of(converter.toData(maxSupported));
+              return Optional.of(converter.toData(versionToUse));
             });
 
     final boolean isNewlyAdded = result.isNewlyStored();
     Map<String, Object> searchAttributesForChangeVersion = null;
     if (isNewlyAdded) {
       searchAttributesForChangeVersion =
-          createSearchAttributesForChangeVersion(changeId, maxSupported, versionMap);
+          createSearchAttributesForChangeVersion(changeId, versionToUse, versionMap);
     }
 
     Integer version = versionMap.get(changeId);
@@ -361,6 +369,22 @@ GetVersionResult getVersion(
     return new GetVersionResult(version, isNewlyAdded, searchAttributesForChangeVersion);
   }
 
+  private int determineVersionToUse(int minSupported, int maxSupported, GetVersionOptions options) {
+    if (isReplaying()) {
+      return WorkflowInternal.DEFAULT_VERSION;
+    }
+    
+    if (options.getCustomVersion().isPresent()) {
+      return options.getCustomVersion().get();
+    }
+    
+    if (options.isUseMinVersion()) {
+      return minSupported;
+    }
+    
+    return maxSupported;
+  }
+
   private void validateVersion(String changeID, int version, int minSupported, int maxSupported) {
     if ((version < minSupported || version > maxSupported)
         && version != WorkflowInternal.DEFAULT_VERSION) {

src/main/java/com/uber/cadence/internal/replay/DecisionContext.java

@@ -194,6 +194,18 @@ Optional<byte[]> mutableSideEffect(
    */
   int getVersion(String changeID, DataConverter dataConverter, int minSupported, int maxSupported);
 
+  /**
+   * Enhanced version of getVersion with additional options for version control.
+   *
+   * @param changeID identifier of a particular change
+   * @param dataConverter data converter for serialization
+   * @param minSupported min version supported for the change
+   * @param maxSupported max version supported for the change
+   * @param options version control options
+   * @return version
+   */
+  int getVersion(String changeID, DataConverter dataConverter, int minSupported, int maxSupported, GetVersionOptions options);
+
   Random newRandom();
 
   /** @return scope to be used for metrics reporting. */

src/main/java/com/uber/cadence/internal/replay/DecisionContextImpl.java

@@ -302,6 +302,19 @@ public int getVersion(
     return results.getVersion();
   }
 
+  @Override
+  public int getVersion(
+      String changeID, DataConverter converter, int minSupported, int maxSupported, GetVersionOptions options) {
+    final ClockDecisionContext.GetVersionResult results =
+        workflowClock.getVersion(changeID, converter, minSupported, maxSupported, options);
+    if (results.shouldUpdateCadenceChangeVersion()) {
+      upsertSearchAttributes(
+          InternalUtils.convertMapToSearchAttributes(
+              results.getSearchAttributesForChangeVersion()));
+    }
+    return results.getVersion();
+  }
+
   @Override
   public long currentTimeMillis() {
     return workflowClock.currentTimeMillis();

src/main/java/com/uber/cadence/internal/sync/SyncDecisionContext.java

@@ -620,6 +620,11 @@ public int getVersion(String changeID, int minSupported, int maxSupported) {
     return context.getVersion(changeID, converter, minSupported, maxSupported);
   }
 
+  @Override
+  public int getVersion(String changeID, int minSupported, int maxSupported, GetVersionOptions options) {
+    return context.getVersion(changeID, converter, minSupported, maxSupported, options);
+  }
+
   void fireTimers() {
     timers.fireTimers(context.currentTimeMillis());
   }

src/main/java/com/uber/cadence/internal/sync/WorkflowInternal.java

@@ -253,6 +253,19 @@ public static int getVersion(String changeID, int minSupported, int maxSupported
     return getWorkflowInterceptor().getVersion(changeID, minSupported, maxSupported);
   }
 
+  /**
+   * Enhanced version of getVersion with additional options for version control.
+   * 
+   * @param changeID identifier of a particular change
+   * @param minSupported min version supported for the change
+   * @param maxSupported max version supported for the change
+   * @param options version control options
+   * @return version
+   */
+  public static int getVersion(String changeID, int minSupported, int maxSupported, GetVersionOptions options) {
+    return getWorkflowInterceptor().getVersion(changeID, minSupported, maxSupported, options);
+  }
+
   public static <U> Promise<List<U>> promiseAllOf(Collection<Promise<U>> promises) {
     return new AllOfPromise<>(promises);
   }

src/main/java/com/uber/cadence/workflow/GetVersionOptions.java

@@ -0,0 +1,108 @@
+/*
+ *  Copyright 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 file except in compliance with the License. A copy of the License is
+ *  located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ *  or in the "license" file accompanying this file. This file 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 com.uber.cadence.workflow;
+
+import java.util.Optional;
+
+/**
+ * Options for configuring GetVersion behavior.
+ * This class provides a builder pattern for configuring version control options.
+ * 
+ * <p>Example usage:
+ * <pre><code>
+ * // Force a specific version
+ * GetVersionOptions options = GetVersionOptions.newBuilder()
+ *     .executeWithVersion(2)
+ *     .build();
+ * 
+ * // Use minimum supported version
+ * GetVersionOptions options = GetVersionOptions.newBuilder()
+ *     .executeWithMinVersion()
+ *     .build();
+ * </code></pre>
+ */
+public final class GetVersionOptions {
+    private final Optional<Integer> customVersion;
+    private final boolean useMinVersion;
+
+    private GetVersionOptions(Optional<Integer> customVersion, boolean useMinVersion) {
+        this.customVersion = customVersion;
+        this.useMinVersion = useMinVersion;
+    }
+
+    /**
+     * Returns the custom version if specified, otherwise empty.
+     */
+    public Optional<Integer> getCustomVersion() {
+        return customVersion;
+    }
+
+    /**
+     * Returns true if the minimum version should be used instead of maximum version.
+     */
+    public boolean isUseMinVersion() {
+        return useMinVersion;
+    }
+
+    /**
+     * Creates a new builder for GetVersionOptions.
+     */
+    public static Builder newBuilder() {
+        return new Builder();
+    }
+
+    /**
+     * Builder for GetVersionOptions.
+     */
+    public static class Builder {
+        private Optional<Integer> customVersion = Optional.empty();
+        private boolean useMinVersion = false;
+
+        /**
+         * Forces a specific version to be returned when executed for the first time,
+         * instead of returning maxSupported version.
+         * 
+         * @param version the specific version to use
+         * @return this builder
+         */
+        public Builder executeWithVersion(int version) {
+            this.customVersion = Optional.of(version);
+            return this;
+        }
+
+        /**
+         * Makes GetVersion return minSupported version when executed for the first time,
+         * instead of returning maxSupported version.
+         * 
+         * @return this builder
+         */
+        public Builder executeWithMinVersion() {
+            this.useMinVersion = true;
+            return this;
+        }
+
+        /**
+         * Builds the GetVersionOptions instance.
+         * 
+         * @return the configured GetVersionOptions
+         */
+        public GetVersionOptions build() {
+            return new GetVersionOptions(customVersion, useMinVersion);
+        }
+    }
+} 

src/main/java/com/uber/cadence/workflow/Workflow.java

@@ -353,7 +353,7 @@
  *       executed in parallel.
  *   <li>Do not call any non deterministic functions like non seeded random or {@link
  *       UUID#randomUUID()} directly form the workflow code. Always do this in activities.
- *   <li>Don’t perform any IO or service calls as they are not usually deterministic. Use activities
+ *   <li>Don't perform any IO or service calls as they are not usually deterministic. Use activities
  *       for this.
  *   <li>Only use {@link #currentTimeMillis()} to get the current time inside a workflow.
  *   <li>Do not use native Java {@link Thread} or any other multi-threaded classes like {@link
@@ -369,7 +369,7 @@
  *   <li>Use {@link WorkflowQueue} instead of {@link java.util.concurrent.BlockingQueue}.
  *   <li>Don't change workflow code when there are open workflows. The ability to do updates through
  *       visioning is TBD.
- *   <li>Don’t access configuration APIs directly from a workflow because changes in the
+ *   <li>Don't access configuration APIs directly from a workflow because changes in the
  *       configuration might affect a workflow execution path. Pass it as an argument to a workflow
  *       function or use an activity to load it.
  * </ul>
@@ -1123,15 +1123,15 @@ public static <R> R mutableSideEffect(
    * </code></pre>
    *
    * The reason to keep it is: 1) it ensures that if there is older version execution still running,
-   * it will fail here and not proceed; 2) if you ever need to make more changes for “fooChange”,
+   * it will fail here and not proceed; 2) if you ever need to make more changes for "fooChange",
    * for example change activity3 to activity4, you just need to update the maxVersion from 2 to 3.
    *
    * <p>Note that, you only need to preserve the first call to GetVersion() for each changeID. All
    * subsequent call to GetVersion() with same changeID are safe to remove. However, if you really
    * want to get rid of the first GetVersion() call as well, you can do so, but you need to make
-   * sure: 1) all older version executions are completed; 2) you can no longer use “fooChange” as
+   * sure: 1) all older version executions are completed; 2) you can no longer use "fooChange" as
    * changeID. If you ever need to make changes to that same part, you would need to use a different
-   * changeID like “fooChange-fix2”, and start minVersion from DefaultVersion again.
+   * changeID like "fooChange-fix2", and start minVersion from DefaultVersion again.
    *
    * @param changeID identifier of a particular change. All calls to getVersion that share a
    *     changeID are guaranteed to return the same version number. Use this to perform multiple
@@ -1144,6 +1144,63 @@ public static int getVersion(String changeID, int minSupported, int maxSupported
     return WorkflowInternal.getVersion(changeID, minSupported, maxSupported);
   }
 
+  /**
+   * Enhanced version of {@code getVersion} with additional options for version control.
+   * This method provides more granular control over version execution and enables safer deployment strategies.
+   *
+   * <p>Example usage with custom version:
+   * <pre><code>
+   * int version = Workflow.getVersion("changeId", 1, 3, 
+   *     GetVersionOptions.newBuilder().executeWithVersion(2).build());
+   * </code></pre>
+   *
+   * <p>Example usage with minimum version:
+   * <pre><code>
+   * int version = Workflow.getVersion("changeId", 1, 3,
+   *     GetVersionOptions.newBuilder().executeWithMinVersion().build());
+   * </code></pre>
+   *
+   * @param changeID identifier of a particular change
+   * @param minSupported min version supported for the change
+   * @param maxSupported max version supported for the change
+   * @param options version control options
+   * @return version
+   */
+  public static int getVersion(String changeID, int minSupported, int maxSupported, GetVersionOptions options) {
+    return WorkflowInternal.getVersion(changeID, minSupported, maxSupported, options);
+  }
+
+  /**
+   * Convenience method that forces a specific version to be returned when executed for the first time.
+   *
+   * @param changeID identifier of a particular change
+   * @param minSupported min version supported for the change
+   * @param maxSupported max version supported for the change
+   * @param customVersion the specific version to use
+   * @return version
+   */
+  public static int getVersionWithCustomVersion(String changeID, int minSupported, int maxSupported, int customVersion) {
+    GetVersionOptions options = GetVersionOptions.newBuilder()
+        .executeWithVersion(customVersion)
+        .build();
+    return getVersion(changeID, minSupported, maxSupported, options);
+  }
+
+  /**
+   * Convenience method that makes GetVersion return minSupported version when executed for the first time.
+   *
+   * @param changeID identifier of a particular change
+   * @param minSupported min version supported for the change
+   * @param maxSupported max version supported for the change
+   * @return version
+   */
+  public static int getVersionWithMinVersion(String changeID, int minSupported, int maxSupported) {
+    GetVersionOptions options = GetVersionOptions.newBuilder()
+        .executeWithMinVersion()
+        .build();
+    return getVersion(changeID, minSupported, maxSupported, options);
+  }
+
   /**
    * Get scope for reporting business metrics in workflow logic. This should be used instead of
    * creating new metrics scopes as it is able to dedup metrics during replay.

src/main/java/com/uber/cadence/workflow/WorkflowInterceptor.java

@@ -127,6 +127,17 @@ <R> R mutableSideEffect(
 
   int getVersion(String changeID, int minSupported, int maxSupported);
 
+  /**
+   * Enhanced version of getVersion with additional options for version control.
+   * 
+   * @param changeID identifier of a particular change
+   * @param minSupported min version supported for the change
+   * @param maxSupported max version supported for the change
+   * @param options version control options
+   * @return version
+   */
+  int getVersion(String changeID, int minSupported, int maxSupported, GetVersionOptions options);
+
   void continueAsNew(
       Optional<String> workflowType, Optional<ContinueAsNewOptions> options, Object[] args);
 

src/main/java/com/uber/cadence/workflow/WorkflowInterceptorBase.java

@@ -134,6 +134,11 @@ public int getVersion(String changeID, int minSupported, int maxSupported) {
     return next.getVersion(changeID, minSupported, maxSupported);
   }
 
+  @Override
+  public int getVersion(String changeID, int minSupported, int maxSupported, GetVersionOptions options) {
+    return next.getVersion(changeID, minSupported, maxSupported, options);
+  }
+
   @Override
   public void continueAsNew(
       Optional<String> workflowType, Optional<ContinueAsNewOptions> options, Object[] args) {