Merge branch 'master' into eamsden/skip-yield-on-version-enabled-comment

Author: mjameswh

.github/workflows/ci.yml

@@ -191,7 +191,7 @@ jobs:
       - name: Set up Java
         uses: actions/setup-java@v5
         with:
-          java-version: "11"
+          java-version: "23"
           distribution: "temurin"
 
       - name: Set up Gradle
@@ -200,6 +200,30 @@ jobs:
       - name: Run copyright and code format checks
         run: ./gradlew --no-daemon spotlessCheck
 
+  javadoc:
+    name: Javadoc
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          submodules: recursive
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Set up Java
+        uses: actions/setup-java@v5
+        with:
+          java-version: "23"
+          distribution: "temurin"
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v5
+
+      - name: Run javadoc
+        run: ./gradlew --no-daemon javadoc
+
   build_native_images:
     name: Build native test server
     uses: ./.github/workflows/build-native-image.yml

.gitignore

@@ -18,4 +18,6 @@ src/main/idls/*
 .settings
 .vscode/
 */bin
-/.claude
+/.claude
+mise.local.toml
+**/.factorypath

gradle/java.gradle

@@ -32,9 +32,8 @@ subprojects {
 
     javadoc {
         options.encoding = 'UTF-8'
-        if (JavaVersion.current().isJava8Compatible()) {
-            options.addStringOption('Xdoclint:none', '-quiet')
-        }
+        options.addStringOption('Xdoclint:reference', '-quiet')
+        options.addBooleanOption('Werror', true)
         if (JavaVersion.current().isJava9Compatible()) {
             options.addBooleanOption('html5', true)
         }

releases/v1.34.0

@@ -0,0 +1,106 @@
+# **💥 BREAKING CHANGES**
+
+## Nexus Failure Serialization
+
+The Java SDK now uses Temporal `Failure` protos for Nexus operation and handler task
+failures, instead of the legacy `UnsuccessfulOperationError`/`HandlerError` format.
+This allows `OperationException` and `HandlerException` to carry their own message and
+stack trace independently of their cause.
+
+The SDK automatically falls back to the legacy format when the server does not support
+the new format. However, if your code inspects the raw structure of Nexus failures
+(e.g. via custom interceptors or failure converters), you may need to update it to
+handle the new format. (#2773)
+
+# **Highlights**
+
+## Spring Boot 4 and Jackson 3 Support
+
+Spring Boot 4 is now supported. The Spring Boot autoconfigure module was updated for
+Spring Boot 4 API changes (e.g. updated class references in `MetricsScopeAutoConfiguration`
+and `OpenTracingAutoConfiguration`). No code changes are needed in application code. (#2787)
+
+Jackson 3 is now optionally supported via a multi-release JAR. To opt in, call
+`JacksonJsonPayloadConverter.setDefaultAsJackson3(true, jacksonCompatMode)` at startup.
+Jackson 3 and Jackson 2 converters are wire-compatible. Jackson 3 is an optional
+dependency and is not pulled in automatically. (#2783)
+
+Plugin beans (`WorkflowServiceStubsPlugin`, `WorkflowClientPlugin`, `ScheduleClientPlugin`,
+`WorkerPlugin`) defined in the Spring context are now automatically discovered and wired
+into the Temporal client and worker configuration. Plugins support `@Order` and `@Priority`
+annotations for consistent ordering. (#2766)
+
+## Upgrade-on-ContinueAsNew
+
+PINNED workflows can now upgrade to the latest worker deployment version on
+continue-as-new by setting `initialVersioningBehavior` to `AUTO_UPGRADE` in
+`ContinueAsNewOptions`. A new `WorkflowInfo.isTargetWorkerDeploymentVersionChanged()`
+method lets workflows detect when the target worker deployment version has changed,
+enabling explicit upgrade decisions. (#2811)
+
+## Local Timeout for Activity Heartbeats
+
+Activity heartbeat timeouts are now enforced locally by the SDK, matching the behavior
+of the Core-based SDKs. Previously, only the server enforced heartbeat timeouts; the
+local check reduces the time it takes for a stale activity to be detected and retried.
+This feature applies to heartbeat timeouts only, not overall activity timeouts. (#2804)
+
+## Nexus Caller Timeouts
+
+`ScheduleToStartTimeout` and `StartToCloseTimeout` are now supported for Nexus
+operations, in addition to the existing `ScheduleToCloseTimeout`. The test server was
+updated to enforce all three timeout types and compute the `OPERATION_TIMEOUT` header
+correctly. (#2760)
+
+# **Bugfixes**
+
+## ContextClassLoader Propagation for Poll Tasks
+
+When `PollerBehaviorAutoscaling` is enabled, poll tasks run asynchronously on a
+common `ForkJoinPool`, whose threads use the system class loader by default. This
+caused class-loading failures in frameworks like Spring Boot that rely on a custom
+context class loader (e.g. `LaunchedClassLoader`). The SDK now captures and propagates
+the context class loader from the thread that created the `WorkerFactory` to all
+worker threads. (#2808)
+
+## Workflow Slot Not Marked Used for Async Pollers
+
+When `PollerBehaviorAutoscaling` was enabled, `AsyncWorkflowPollTask` was not calling
+`markSlotUsed` on the `SlotSupplier` after receiving a task. This caused the
+`WORKER_TASK_SLOTS_AVAILABLE` metric to report an incorrectly high value. (#2803)
+
+## Validate `WorkerDeploymentOptions` at Build Time
+
+`WorkerDeploymentOptions.build()` now rejects configurations where
+`defaultVersioningBehavior` is set to anything other than `UNSPECIFIED` when
+`useVersioning` is `false`. Previously such configurations were silently accepted but
+then rejected by the server at workflow task completion, causing workflows to get stuck.
+(#2807)
+
+## Fix Exception Swallowing on `Workflow.getVersion()`
+
+A bug where exceptions thrown by a workflow could be swallowed and replaced by a
+worker-shutdown error when `Workflow.getVersion()` was called is now fixed for all
+new workflows. Existing workflows replay correctly without any changes. (#2819)
+
+# What's Changed
+
+2026-02-26 - 9799bd00 - Add missing apostrophe to WorkflowException message (#2776)
+2026-02-27 - ef194239 - Add headers to cancel nexus task (#2798)
+2026-03-10 - 20fb8520 - Nexus caller timeouts (#2760)
+2026-03-10 - dbd648bd - Update Nexus failure conversion (#2773)
+2026-03-11 - 6ba0947f - Fix async poller workflow slot used (#2803)
+2026-03-13 - 53449bb5 - Introduce local timeout for activity heartbeats (#2804)
+2026-03-16 - 9356745c - Replace docker instructions for running a local server with CLI instructions. (#2806)
+2026-03-17 - 95169659 - Cancel timer when Workflow.await condition is satisfied (#2799)
+2026-03-17 - fb2defd9 - Fix time skipping for dotnet SDK (#2805)
+2026-03-19 - 02182b93 - Support plugins in spring-boot-autoconfigure (#2766)
+2026-03-23 - a714cc10 - Allow poller scale-down on timeout when server supports autoscaling (#2812)
+2026-03-24 - b9c186d1 - Add note about Rosetta for old protoc-gen-rpc-java (#2815)
+2026-03-25 - c195cd1d - Add Spring Boot 4 support (#2787)
+2026-03-25 - fcb4e841 - Add opt-in Jackson 3 support via multi-release JAR (#2783)
+2026-03-27 - 0e1a7a25 - Validate deployment options and test worker with versioning off and custom build ID (#2807)
+2026-03-27 - da5e8a17 - Add upgrade-on-CAN support (#2811)
+2026-03-30 - b9b0f6b5 - Fix ContextClassLoader propagation for poll tasks (#2808)
+2026-03-31 - 5d969b87 - `tryUseSdkFlag(SdkFlag.SKIP_YIELD_ON_VERSION)` so that we default to enabling `SKIP_YIELD_ON_VERSION` when calling `getVersion()` (#2819)
+2026-03-31 - fb87ce6c - Update Temporal Cloud-API to v0.12.0 (#2814)

temporal-envconfig/src/main/java/io/temporal/envconfig/ClientConfig.java

@@ -44,13 +44,16 @@ public static ClientConfig getDefaultInstance() {
   private static String getDefaultConfigFilePath() {
     String userDir = System.getProperty("user.home");
     if (userDir == null || userDir.isEmpty()) {
-      throw new RuntimeException("failed getting user home directory");
+      return null;
     }
     return getDefaultConfigFilePath(userDir, System.getProperty("os.name"), System.getenv());
   }
 
   static String getDefaultConfigFilePath(
       String userDir, String osName, Map<String, String> environment) {
+    if (userDir == null || userDir.isEmpty()) {
+      return null;
+    }
     if (osName != null) {
       String osNameLower = osName.toLowerCase();
       if (osNameLower.contains("mac")) {
@@ -60,7 +63,7 @@ static String getDefaultConfigFilePath(
       if (osNameLower.contains("win")) {
         String appData = environment != null ? environment.get("APPDATA") : null;
         if (appData == null || appData.isEmpty()) {
-          throw new RuntimeException("%APPDATA% is not defined");
+          return null;
         }
         return Paths.get(appData, "temporalio", "temporal.toml").toString();
       }
@@ -122,6 +125,10 @@ public static ClientConfig load(LoadClientConfigOptions options) throws IOExcept
       if (file == null || file.isEmpty()) {
         file = getDefaultConfigFilePath();
       }
+      // No config dir available — return default empty config
+      if (file == null) {
+        return getDefaultInstance();
+      }
       try {
         ClientConfigToml.TomlClientConfig result = reader.readValue(new File(file));
         return new ClientConfig(ClientConfigToml.getClientProfiles(result));
@@ -172,7 +179,7 @@ public static ClientConfig fromToml(byte[] tomlData, ClientConfigFromTomlOptions
    *
    * @param config the client config to convert
    * @return the TOML data as bytes
-   * @apiNote The output will not be identical to the input if the config was loaded from a file
+   *     <p>Note: The output will not be identical to the input if the config was loaded from a file
    *     because comments and formatting are not preserved.
    */
   public static byte[] toTomlAsBytes(ClientConfig config) throws IOException {

temporal-envconfig/src/test/java/io/temporal/envconfig/ClientConfigProfileTest.java

@@ -325,6 +325,22 @@ public void defaultConfigFilePath() {
         ClientConfig.getDefaultConfigFilePath("/home/test", "Linux", Collections.emptyMap()));
   }
 
+  @Test
+  public void loadDefaultConfigMissingHomeDir() throws IOException {
+    String original = System.getProperty("user.home");
+    try {
+      System.setProperty("user.home", "");
+      ClientConfig config =
+          ClientConfig.load(
+              LoadClientConfigOptions.newBuilder().setEnvOverrides(Collections.emptyMap()).build());
+      Assert.assertEquals(ClientConfig.getDefaultInstance(), config);
+    } finally {
+      if (original != null) {
+        System.setProperty("user.home", original);
+      }
+    }
+  }
+
   @Test
   public void parseToml() throws IOException {
     String toml =

temporal-remote-data-encoder/src/main/java/io/temporal/payload/codec/AbstractRemoteDataEncoderCodec.java

@@ -11,8 +11,6 @@
 /**
  * Performs encoding/decoding of the payloads via the Remote Data Encoder (RDE) available over http.
  *
- * <p>
- *
  * <h2>Remote Data Encoder Http Server specification</h2>
  *
  * <p>RDE Server must:

temporal-sdk/src/main/java/io/temporal/activity/ActivityInfo.java

@@ -126,8 +126,8 @@ public interface ActivityInfo {
   /**
    * Return the priority of the activity task.
    *
-   * @apiNote If unset or on an older server version, this method will return {@link
-   *     Priority#getDefaultInstance()}.
+   * <p>Note: If unset or on an older server version, this method will return {@link
+   * Priority#getDefaultInstance()}.
    */
   @Experimental
   @Nonnull

temporal-sdk/src/main/java/io/temporal/activity/ActivityInterface.java

@@ -42,8 +42,6 @@
  * When <code>CImpl</code> instance is registered with the {@link io.temporal.worker.Worker} the
  * following activities are registered:
  *
- * <p>
- *
  * <ul>
  *   <li>B_a
  *   <li>B_b

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

@@ -158,9 +158,8 @@ static WorkflowClient newInstance(WorkflowServiceStubs service, WorkflowClientOp
    * @param workflowId Workflow id.
    * @param runId Run id of the workflow execution.
    * @return Stub that implements workflowInterface and can be used to signal, update, or query it.
-   * @deprecated Use {@link #newWorkflowStub(Class, WorkflowTargetOptions)} instead.
-   * @apiNote This method is deprecated because the returned stub does not properly account for the
-   *     runId.
+   * @deprecated Use {@link #newWorkflowStub(Class, WorkflowTargetOptions)} instead. This method is
+   *     deprecated because the returned stub does not properly account for the runId.
    */
   @Deprecated
   <T> T newWorkflowStub(Class<T> workflowInterface, String workflowId, Optional<String> runId);
@@ -205,9 +204,8 @@ static WorkflowClient newInstance(WorkflowServiceStubs service, WorkflowClientOp
    *     workflowId is assumed.
    * @param workflowType type of the workflow. Optional as it is used for error reporting only.
    * @return Stub that can be used to start workflow and later to signal or query it.
-   * @deprecated Use {@link #newUntypedWorkflowStub(WorkflowTargetOptions, Optional)} instead.
-   * @apiNote This method is deprecated because the returned stub does not properly account for the
-   *     runId.
+   * @deprecated Use {@link #newUntypedWorkflowStub(WorkflowTargetOptions, Optional)} instead. This
+   *     method is deprecated because the returned stub does not properly account for the runId.
    */
   @Deprecated
   WorkflowStub newUntypedWorkflowStub(
@@ -220,9 +218,8 @@ WorkflowStub newUntypedWorkflowStub(
    * @param execution workflow id and optional run id for execution
    * @param workflowType type of the workflow. Optional as it is used for error reporting only.
    * @return Stub that can be used to start workflow and later to signal or query it.
-   * @deprecated Use {@link #newUntypedWorkflowStub(WorkflowTargetOptions, Optional)} instead.
-   * @apiNote This method is deprecated because the returned stub does not properly account for the
-   *     runId.
+   * @deprecated Use {@link #newUntypedWorkflowStub(WorkflowTargetOptions, Optional)} instead. This
+   *     method is deprecated because the returned stub does not properly account for the runId.
    */
   WorkflowStub newUntypedWorkflowStub(WorkflowExecution execution, Optional<String> workflowType);