Port enhanced version control features from Go client

Add support for ExecuteWithVersion and ExecuteWithMinVersion options to getVersion method,
porting functionality from cadence-go-client PRs #1427 and #1428.

Changes:
- Add GetVersionOptions class with builder pattern for version control configuration
- Add executeWithVersion() and executeWithMinVersion() methods to GetVersionOptions
- Add overloaded getVersion() method that accepts GetVersionOptions parameter
- Add convenience methods getVersionWithCustomVersion() and getVersionWithMinVersion()
- Update all workflow interceptor interfaces and implementations to support new options
- Update DecisionContext, ClockDecisionContext, and related classes for version selection logic
- Add testing framework support for enhanced version control features
- Add comprehensive test coverage for new functionality

This enables safer deployment strategies and more granular control over workflow
version execution, allowing developers to:
- Force specific versions instead of max supported version
- Use minimum supported version for backward compatibility
- Test workflows with enhanced version control in test environments

Fixes compilation errors and ensures all existing functionality remains compatible.

Author: pandeyanshuman

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

@@ -33,6 +33,7 @@
 import com.uber.cadence.workflow.ActivityFailureException;
 import com.uber.cadence.workflow.Functions.Func;
 import com.uber.cadence.workflow.Functions.Func1;
+import com.uber.cadence.workflow.GetVersionOptions;
 import java.time.Duration;
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -320,11 +321,16 @@ private void handleVersionMarker(MarkerRecordedEventAttributes attributes) {
 
   GetVersionResult getVersion(
       String changeId, DataConverter converter, int minSupported, int maxSupported) {
-    return getVersion(changeId, converter, minSupported, maxSupported, GetVersionOptions.newBuilder().build());
+    return getVersion(
+        changeId, converter, minSupported, maxSupported, GetVersionOptions.newBuilder().build());
   }
 
   GetVersionResult getVersion(
-      String changeId, DataConverter converter, int minSupported, int maxSupported, GetVersionOptions options) {
+      String changeId,
+      DataConverter converter,
+      int minSupported,
+      int maxSupported,
+      GetVersionOptions options) {
     Predicate<MarkerRecordedEventAttributes> changeIdEquals =
         (attributes) -> {
           MarkerHandler.MarkerInterface markerData =
@@ -373,15 +379,15 @@ private int determineVersionToUse(int minSupported, int maxSupported, GetVersion
     if (isReplaying()) {
       return WorkflowInternal.DEFAULT_VERSION;
     }
-    
+
     if (options.getCustomVersion().isPresent()) {
       return options.getCustomVersion().get();
     }
-    
+
     if (options.isUseMinVersion()) {
       return minSupported;
     }
-    
+
     return maxSupported;
   }
 

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

@@ -25,6 +25,7 @@
 import com.uber.cadence.converter.DataConverter;
 import com.uber.cadence.workflow.Functions.Func;
 import com.uber.cadence.workflow.Functions.Func1;
+import com.uber.cadence.workflow.GetVersionOptions;
 import com.uber.cadence.workflow.Promise;
 import com.uber.m3.tally.Scope;
 import java.time.Duration;
@@ -204,7 +205,12 @@ Optional<byte[]> mutableSideEffect(
    * @param options version control options
    * @return version
    */
-  int getVersion(String changeID, DataConverter dataConverter, int minSupported, int maxSupported, GetVersionOptions options);
+  int getVersion(
+      String changeID,
+      DataConverter dataConverter,
+      int minSupported,
+      int maxSupported,
+      GetVersionOptions options);
 
   Random newRandom();
 

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

@@ -35,6 +35,7 @@
 import com.uber.cadence.internal.worker.SingleWorkerOptions;
 import com.uber.cadence.workflow.Functions.Func;
 import com.uber.cadence.workflow.Functions.Func1;
+import com.uber.cadence.workflow.GetVersionOptions;
 import com.uber.cadence.workflow.Promise;
 import com.uber.cadence.workflow.Workflow;
 import com.uber.m3.tally.Scope;
@@ -304,7 +305,11 @@ public int getVersion(
 
   @Override
   public int getVersion(
-      String changeID, DataConverter converter, int minSupported, int maxSupported, GetVersionOptions options) {
+      String changeID,
+      DataConverter converter,
+      int minSupported,
+      int maxSupported,
+      GetVersionOptions options) {
     final ClockDecisionContext.GetVersionResult results =
         workflowClock.getVersion(changeID, converter, minSupported, maxSupported, options);
     if (results.shouldUpdateCadenceChangeVersion()) {

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

@@ -36,6 +36,7 @@
 import com.uber.cadence.internal.replay.StartChildWorkflowExecutionParameters;
 import com.uber.cadence.workflow.Functions.Func;
 import com.uber.cadence.workflow.Functions.Func1;
+import com.uber.cadence.workflow.GetVersionOptions;
 import com.uber.cadence.workflow.Promise;
 import com.uber.m3.tally.Scope;
 import java.time.Duration;
@@ -695,6 +696,16 @@ public int getVersion(
       throw new UnsupportedOperationException("not implemented");
     }
 
+    @Override
+    public int getVersion(
+        String changeID,
+        DataConverter converter,
+        int minSupported,
+        int maxSupported,
+        GetVersionOptions options) {
+      throw new UnsupportedOperationException("not implemented");
+    }
+
     @Override
     public Random newRandom() {
       throw new UnsupportedOperationException("not implemented");

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

@@ -54,6 +54,7 @@
 import com.uber.cadence.workflow.ContinueAsNewOptions;
 import com.uber.cadence.workflow.Functions;
 import com.uber.cadence.workflow.Functions.Func;
+import com.uber.cadence.workflow.GetVersionOptions;
 import com.uber.cadence.workflow.Promise;
 import com.uber.cadence.workflow.SignalExternalWorkflowException;
 import com.uber.cadence.workflow.Workflow;
@@ -621,7 +622,8 @@ public int getVersion(String changeID, int minSupported, int maxSupported) {
   }
 
   @Override
-  public int getVersion(String changeID, int minSupported, int maxSupported, GetVersionOptions options) {
+  public int getVersion(
+      String changeID, int minSupported, int maxSupported, GetVersionOptions options) {
     return context.getVersion(changeID, converter, minSupported, maxSupported, options);
   }
 

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

@@ -242,6 +242,12 @@ public int getVersion(String changeID, int minSupported, int maxSupported) {
       throw new UnsupportedOperationException("not implemented");
     }
 
+    @Override
+    public int getVersion(
+        String changeID, int minSupported, int maxSupported, GetVersionOptions options) {
+      throw new UnsupportedOperationException("not implemented");
+    }
+
     @Override
     public void continueAsNew(
         Optional<String> workflowType, Optional<ContinueAsNewOptions> options, Object[] args) {

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

@@ -36,6 +36,7 @@
 import com.uber.cadence.workflow.ExternalWorkflowStub;
 import com.uber.cadence.workflow.Functions;
 import com.uber.cadence.workflow.Functions.Func;
+import com.uber.cadence.workflow.GetVersionOptions;
 import com.uber.cadence.workflow.Promise;
 import com.uber.cadence.workflow.QueryMethod;
 import com.uber.cadence.workflow.Workflow;
@@ -255,14 +256,15 @@ public static 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
    */
-  public static int getVersion(String changeID, int minSupported, int maxSupported, GetVersionOptions options) {
+  public static int getVersion(
+      String changeID, int minSupported, int maxSupported, GetVersionOptions options) {
     return getWorkflowInterceptor().getVersion(changeID, minSupported, maxSupported, options);
   }
 

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

@@ -20,89 +20,82 @@
 import java.util.Optional;
 
 /**
- * Options for configuring GetVersion behavior.
- * This class provides a builder pattern for configuring version control options.
- * 
+ * 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 final Optional<Integer> customVersion;
+  private final boolean useMinVersion;
 
-    private GetVersionOptions(Optional<Integer> customVersion, boolean useMinVersion) {
-        this.customVersion = customVersion;
-        this.useMinVersion = 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 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;
 
     /**
-     * Returns true if the minimum version should be used instead of maximum version.
+     * 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 boolean isUseMinVersion() {
-        return useMinVersion;
+    public Builder executeWithVersion(int version) {
+      this.customVersion = Optional.of(version);
+      return this;
     }
 
     /**
-     * Creates a new builder for GetVersionOptions.
+     * Makes GetVersion return minSupported version when executed for the first time, instead of
+     * returning maxSupported version.
+     *
+     * @return this builder
      */
-    public static Builder newBuilder() {
-        return new Builder();
+    public Builder executeWithMinVersion() {
+      this.useMinVersion = true;
+      return this;
     }
 
     /**
-     * Builder for GetVersionOptions.
+     * Builds the GetVersionOptions instance.
+     *
+     * @return the configured 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);
-        }
+    public GetVersionOptions build() {
+      return new GetVersionOptions(customVersion, useMinVersion);
     }
-} 
+  }
+}

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

@@ -1145,16 +1145,18 @@ public static int getVersion(String changeID, int minSupported, int 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.
+   * 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, 
+   * 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());
@@ -1166,38 +1168,39 @@ public static int getVersion(String changeID, int minSupported, int maxSupported
    * @param options version control options
    * @return version
    */
-  public static int getVersion(String changeID, int minSupported, int maxSupported, GetVersionOptions options) {
+  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.
+   * 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();
+  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.
+   * 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();
+    GetVersionOptions options = GetVersionOptions.newBuilder().executeWithMinVersion().build();
     return getVersion(changeID, minSupported, maxSupported, options);
   }
 

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

@@ -129,7 +129,7 @@ <R> R mutableSideEffect(
 
   /**
    * 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