Create worker deployment based versioning sample

Sushisource · Sushisource · commit 010681361eab · 2025-09-16T14:30:27.000-07:00
diff --git a/.gitignore b/.gitignore
@@ -17,4 +17,5 @@ target
 .project
 .settings/
 bin/
-core/.vscode/
+core/.vscode/
+.claude/
diff --git a/README.md b/README.md
@@ -108,8 +108,9 @@ See the README.md file in each main sample directory for cut/paste Gradle comman
 
 - [**Custom Annotation**](/core/src/main/java/io/temporal/samples/customannotation): Demonstrates how to create a custom annotation using an interceptor.
 
-- [**Asnyc Packet Delivery**](/core/src/main/java/io/temporal/samples/packetdelivery): Demonstrates running multiple execution paths async within single execution.
+- [**Async Packet Delivery**](/core/src/main/java/io/temporal/samples/packetdelivery): Demonstrates running multiple execution paths async within single execution.
 
+- [**Worker Versioning**](/core/src/main/java/io/temporal/samples/workerversioning): Demonstrates how to use worker versioning to manage workflow code changes.
 
 #### API demonstrations
 
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/Activities.java b/core/src/main/java/io/temporal/samples/workerversioning/Activities.java
@@ -0,0 +1,42 @@
+package io.temporal.samples.workerversioning;
+
+import io.temporal.activity.ActivityInterface;
+import io.temporal.activity.ActivityMethod;
+
+@ActivityInterface
+public interface Activities {
+
+  @ActivityMethod
+  String someActivity(String calledBy);
+
+  @ActivityMethod
+  String someIncompatibleActivity(IncompatibleActivityInput input);
+
+  class IncompatibleActivityInput {
+    String calledBy;
+    String moreData;
+
+    public IncompatibleActivityInput() {}
+
+    public IncompatibleActivityInput(String calledBy, String moreData) {
+      this.calledBy = calledBy;
+      this.moreData = moreData;
+    }
+
+    public String getCalledBy() {
+      return calledBy;
+    }
+
+    public String getMoreData() {
+      return moreData;
+    }
+
+    public void setCalledBy(String calledBy) {
+      this.calledBy = calledBy;
+    }
+
+    public void setMoreData(String moreData) {
+      this.moreData = moreData;
+    }
+  }
+}
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/ActivitiesImpl.java b/core/src/main/java/io/temporal/samples/workerversioning/ActivitiesImpl.java
@@ -0,0 +1,25 @@
+package io.temporal.samples.workerversioning;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class ActivitiesImpl implements Activities {
+
+  private static final Logger logger = LoggerFactory.getLogger(ActivitiesImpl.class);
+
+  @Override
+  public String someActivity(String calledBy) {
+    logger.info("SomeActivity called by {}", calledBy);
+    return "SomeActivity called by " + calledBy;
+  }
+
+  @Override
+  public String someIncompatibleActivity(IncompatibleActivityInput input) {
+    logger.info(
+        "SomeIncompatibleActivity called by {} with {}", input.getCalledBy(), input.getMoreData());
+    return "SomeIncompatibleActivity called by "
+        + input.getCalledBy()
+        + " with "
+        + input.getMoreData();
+  }
+}
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/AutoUpgradingWorkflow.java b/core/src/main/java/io/temporal/samples/workerversioning/AutoUpgradingWorkflow.java
@@ -0,0 +1,15 @@
+package io.temporal.samples.workerversioning;
+
+import io.temporal.workflow.SignalMethod;
+import io.temporal.workflow.WorkflowInterface;
+import io.temporal.workflow.WorkflowMethod;
+
+@WorkflowInterface
+public interface AutoUpgradingWorkflow {
+
+  @WorkflowMethod
+  void run();
+
+  @SignalMethod
+  void doNextSignal(String signal);
+}
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/AutoUpgradingWorkflowV1Impl.java b/core/src/main/java/io/temporal/samples/workerversioning/AutoUpgradingWorkflowV1Impl.java
@@ -0,0 +1,47 @@
+package io.temporal.samples.workerversioning;
+
+import io.temporal.activity.ActivityOptions;
+import io.temporal.common.VersioningBehavior;
+import io.temporal.workflow.Workflow;
+import io.temporal.workflow.WorkflowVersioningBehavior;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import org.slf4j.Logger;
+
+public class AutoUpgradingWorkflowV1Impl implements AutoUpgradingWorkflow {
+
+  private static final Logger logger = Workflow.getLogger(AutoUpgradingWorkflowV1Impl.class);
+
+  private final List<String> signals = new ArrayList<>();
+  private final Activities activities =
+      Workflow.newActivityStub(
+          Activities.class,
+          ActivityOptions.newBuilder().setStartToCloseTimeout(Duration.ofSeconds(10)).build());
+
+  @Override
+  @WorkflowVersioningBehavior(VersioningBehavior.AUTO_UPGRADE)
+  public void run() {
+    logger.info("Changing workflow v1 started. StartTime: {}", Workflow.currentTimeMillis());
+
+    // This workflow will listen for signals from our starter, and upon each signal either run
+    // an activity, or conclude execution.
+    while (true) {
+      Workflow.await(() -> !signals.isEmpty());
+      String signal = signals.remove(0);
+
+      if ("do-activity".equals(signal)) {
+        logger.info("Changing workflow v1 running activity");
+        activities.someActivity("v1");
+      } else {
+        logger.info("Concluding workflow v1");
+        return;
+      }
+    }
+  }
+
+  @Override
+  public void doNextSignal(String signal) {
+    signals.add(signal);
+  }
+}
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/AutoUpgradingWorkflowV1bImpl.java b/core/src/main/java/io/temporal/samples/workerversioning/AutoUpgradingWorkflowV1bImpl.java
@@ -0,0 +1,56 @@
+package io.temporal.samples.workerversioning;
+
+import io.temporal.activity.ActivityOptions;
+import io.temporal.common.VersioningBehavior;
+import io.temporal.workflow.Workflow;
+import io.temporal.workflow.WorkflowVersioningBehavior;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import org.slf4j.Logger;
+
+public class AutoUpgradingWorkflowV1bImpl implements AutoUpgradingWorkflow {
+
+  private static final Logger logger = Workflow.getLogger(AutoUpgradingWorkflowV1bImpl.class);
+
+  private final List<String> signals = new ArrayList<>();
+  private final Activities activities =
+      Workflow.newActivityStub(
+          Activities.class,
+          ActivityOptions.newBuilder().setStartToCloseTimeout(Duration.ofSeconds(10)).build());
+
+  @Override
+  @WorkflowVersioningBehavior(VersioningBehavior.AUTO_UPGRADE)
+  public void run() {
+    logger.info("Changing workflow v1b started. StartTime: {}", Workflow.currentTimeMillis());
+
+    // This workflow will listen for signals from our starter, and upon each signal either run
+    // an activity, or conclude execution.
+    while (true) {
+      Workflow.await(() -> !signals.isEmpty());
+      String signal = signals.remove(0);
+
+      if ("do-activity".equals(signal)) {
+        logger.info("Changing workflow v1b running activity");
+        int version = Workflow.getVersion("DifferentActivity", Workflow.DEFAULT_VERSION, 1);
+        if (version == 1) {
+          activities.someIncompatibleActivity(
+              new Activities.IncompatibleActivityInput("v1b", "hello!"));
+        } else {
+          // Note it is a valid compatible change to alter the input to an activity.
+          // However, because we're using the getVersion API, this branch will never be
+          // taken.
+          activities.someActivity("v1b");
+        }
+      } else {
+        logger.info("Concluding workflow v1b");
+        break;
+      }
+    }
+  }
+
+  @Override
+  public void doNextSignal(String signal) {
+    signals.add(signal);
+  }
+}
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/Constants.java b/core/src/main/java/io/temporal/samples/workerversioning/Constants.java
@@ -0,0 +1,10 @@
+package io.temporal.samples.workerversioning;
+
+public final class Constants {
+  public static final String TASK_QUEUE = "worker-versioning";
+  public static final String DEPLOYMENT_NAME = "my-deployment";
+
+  private Constants() {
+    // Utility class
+  }
+}
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/PinnedWorkflow.java b/core/src/main/java/io/temporal/samples/workerversioning/PinnedWorkflow.java
@@ -0,0 +1,15 @@
+package io.temporal.samples.workerversioning;
+
+import io.temporal.workflow.SignalMethod;
+import io.temporal.workflow.WorkflowInterface;
+import io.temporal.workflow.WorkflowMethod;
+
+@WorkflowInterface
+public interface PinnedWorkflow {
+
+  @WorkflowMethod
+  void run();
+
+  @SignalMethod
+  void doNextSignal(String signal);
+}
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/PinnedWorkflowV1Impl.java b/core/src/main/java/io/temporal/samples/workerversioning/PinnedWorkflowV1Impl.java
@@ -0,0 +1,42 @@
+package io.temporal.samples.workerversioning;
+
+import io.temporal.activity.ActivityOptions;
+import io.temporal.common.VersioningBehavior;
+import io.temporal.workflow.Workflow;
+import io.temporal.workflow.WorkflowVersioningBehavior;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import org.slf4j.Logger;
+
+public class PinnedWorkflowV1Impl implements PinnedWorkflow {
+
+  private static final Logger logger = Workflow.getLogger(PinnedWorkflowV1Impl.class);
+
+  private final List<String> signals = new ArrayList<>();
+  private final Activities activities =
+      Workflow.newActivityStub(
+          Activities.class,
+          ActivityOptions.newBuilder().setStartToCloseTimeout(Duration.ofSeconds(10)).build());
+
+  @Override
+  @WorkflowVersioningBehavior(VersioningBehavior.PINNED)
+  public void run() {
+    logger.info("Pinned Workflow v1 started. StartTime: {}", Workflow.currentTimeMillis());
+
+    while (true) {
+      Workflow.await(() -> !signals.isEmpty());
+      String signal = signals.remove(0);
+      if ("conclude".equals(signal)) {
+        break;
+      }
+    }
+
+    activities.someActivity("Pinned-v1");
+  }
+
+  @Override
+  public void doNextSignal(String signal) {
+    signals.add(signal);
+  }
+}
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/PinnedWorkflowV2Impl.java b/core/src/main/java/io/temporal/samples/workerversioning/PinnedWorkflowV2Impl.java
@@ -0,0 +1,47 @@
+package io.temporal.samples.workerversioning;
+
+import io.temporal.activity.ActivityOptions;
+import io.temporal.common.VersioningBehavior;
+import io.temporal.workflow.Workflow;
+import io.temporal.workflow.WorkflowVersioningBehavior;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import org.slf4j.Logger;
+
+public class PinnedWorkflowV2Impl implements PinnedWorkflow {
+
+  private static final Logger logger = Workflow.getLogger(PinnedWorkflowV2Impl.class);
+
+  private final List<String> signals = new ArrayList<>();
+  private final Activities activities =
+      Workflow.newActivityStub(
+          Activities.class,
+          ActivityOptions.newBuilder().setStartToCloseTimeout(Duration.ofSeconds(10)).build());
+
+  @Override
+  @WorkflowVersioningBehavior(VersioningBehavior.PINNED)
+  public void run() {
+    logger.info("Pinned Workflow v2 started. StartTime: {}", Workflow.currentTimeMillis());
+
+    // Here we call an activity where we didn't before, which is an incompatible change.
+    activities.someActivity("Pinned-v2");
+
+    while (true) {
+      Workflow.await(() -> !signals.isEmpty());
+      String signal = signals.remove(0);
+      if ("conclude".equals(signal)) {
+        break;
+      }
+    }
+
+    // We've also changed the activity type here, another incompatible change
+    activities.someIncompatibleActivity(
+        new Activities.IncompatibleActivityInput("Pinned-v2", "hi"));
+  }
+
+  @Override
+  public void doNextSignal(String signal) {
+    signals.add(signal);
+  }
+}
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/README.md b/core/src/main/java/io/temporal/samples/workerversioning/README.md
@@ -0,0 +1,25 @@
+# Worker Versioning
+
+This sample demonstrates how to use Temporal's Worker Versioning feature to safely deploy updates to workflow and activity code. It shows the difference between auto-upgrading and pinned workflows, and how to manage worker deployments with different build IDs.
+
+The sample creates multiple worker versions (1.0, 1.1, and 2.0) within one deployment and demonstrates:
+- **Auto-upgrading workflows**: Automatically and controllably migrate to newer worker versions
+- **Pinned workflows**: Stay on the original worker version throughout their lifecycle
+- **Compatible vs incompatible changes**: How to make safe updates using `Workflow.getVersion`
+
+## Steps to run this sample:
+
+1) Run a [Temporal service](https://github.com/temporalio/samples-java/tree/main/#how-to-use).
+
+2) Start the main application (this will guide you through the sample):
+    ```bash
+    ./gradlew -q execute -PmainClass=io.temporal.samples.workerversioning.Starter
+    ```
+3) Follow the prompts to start workers in separate terminals:
+   - When prompted, run: `./gradlew -q execute -PmainClass=io.temporal.samples.workerversioning.WorkerV1`
+   - When prompted, run: `./gradlew -q execute -PmainClass=io.temporal.samples.workerversioning.WorkerV1_1`
+   - When prompted, run: `./gradlew -q execute -PmainClass=io.temporal.samples.workerversioning.WorkerV2`
+
+Follow the prompts in the example to observe auto-upgrading workflows migrating to newer workers
+while pinned workflows remain on their original versions.
+
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/Starter.java b/core/src/main/java/io/temporal/samples/workerversioning/Starter.java
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/WorkerV1.java b/core/src/main/java/io/temporal/samples/workerversioning/WorkerV1.java
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/WorkerV1_1.java b/core/src/main/java/io/temporal/samples/workerversioning/WorkerV1_1.java
diff --git a/core/src/main/java/io/temporal/samples/workerversioning/WorkerV2.java b/core/src/main/java/io/temporal/samples/workerversioning/WorkerV2.java
