Add options to GetVersion for executeWithVersion and executeWithMinVersion

[pandeyanshuman]

What changed?

• Added support for enhanced version control options in workflow execution:
  • Introduced GetVersionOptions class with builder pattern for configuring version control behavior
  • Added executeWithVersion(int version) option to force a specific version instead of max supported version
  • Added executeWithMinVersion() option to use min supported version instead of max supported version
  • Enhanced getVersion() method to accept optional GetVersionOptions parameter
  • Added convenience methods getVersionWithCustomVersion() and getVersionWithMinVersion()
  • Updated all workflow interceptor interfaces and implementations to support new options
  • Updated internal replay logic in ClockDecisionContext and DecisionContext for version selection
  • Added comprehensive testing framework support for enhanced version control features
  • Added extensive test coverage including unit tests, integration tests, and TestWorkflowEnvironment tests

Why?

This change ports the enhanced version control functionality from the Go client (PRs #1427 and #1428) to the Java client, enabling safer deployment strategies and more granular control over workflow version execution. The new options allow developers to:

• Separate code deployment from feature activation through controlled version rollouts
• Force specific versions for testing or gradual rollouts
• Use minimum supported versions for backward compatibility scenarios
• Test workflows with enhanced version control in unit test environments

This improves the workflow versioning system by providing more granular control over version execution, enabling safer rollouts of workflow changes.

How did you test it?

• Added comprehensive unit tests in GetVersionOptionsTest.java covering all builder methods and edge cases
• Added integration tests in EnhancedGetVersionTest.java demonstrating real workflow execution with new options
• Added TestWorkflowEnvironmentGetVersionTest.java to verify testing framework support
• Updated existing WorkflowTest.java to ensure backward compatibility
• Verified that all existing getVersion() calls continue to work without modification
• Tested version selection logic in replay mode and non-replay mode
• Validated that convenience methods work correctly and produce expected results
• Ensured TestWorkflowEnvironment properly emulates Cadence worker behavior for enhanced features
• Unit tests docker-compose -f docker-compose.yaml run unit-test-test-service passed

Potential risks

• Low Risk: The changes are fully backward-compatible - existing workflows using getVersion() without options will continue to work exactly as before
• Low Risk: New functionality is additive and doesn't modify existing behavior
• Low Risk: All existing tests continue to pass, indicating no regression in functionality
• Minimal Risk: If the new options are used incorrectly, workflows may behave differently than expected, but this is mitigated by comprehensive documentation and examples

Release notes

This is a notable feature addition that should be mentioned in the release notes:

• New Feature: Enhanced version control for workflows with GetVersionOptions
• New Feature: Added executeWithVersion() and executeWithMinVersion() options to getVersion() method
• New Feature: Added convenience methods getVersionWithCustomVersion() and getVersionWithMinVersion()
• Enhancement: Improved testing framework support for version-controlled workflows
• Compatibility: Fully backward-compatible - no breaking changes

Documentation Changes

Yes, documentation updates should be made to reflect the new version control features:

• Update workflow versioning documentation to include examples of the new GetVersionOptions
• Add examples showing safe deployment strategies using executeWithVersion() and executeWithMinVersion()
• Document the convenience methods and their use cases
• Update testing documentation to show how to test workflows with enhanced version control
• Consider adding a new section on "Safe Deployment Strategies" or "Advanced Version Control"

The documentation should be updated in the Cadence documentation repository to help users understand and adopt these new features effectively.