v1.29.0

💥 BREAKING CHANGES

Slot Supplier

The SlotSupplier interface was changed to be async to match other languages and allow for future optimizations in the SDK.

Highlights

Priority (Pre-release)

Users can now set a priority key when scheduling a workflow, activity or child workflow. The priority key will be used to help prioritize certain tasks over others when there is a backlog. Priority is currently not supported in any OSS Temporal release, but support will be coming soon. To experiment with this feature please see the pre-release development server or if you are a Temporal Cloud customer reach out to your SA.

Activity Pause (Pre-release)

The Java SDK now supports activity pause for heart beating activities. If an activity is paused while an attempt is running and the activity is heart-beating the heartbeat will throw an io.temporal.clientActivityPausedException.

Versioning / Safe Deploy (Pre-release)

This release introduces a preview of new APIs that gracefully manage code changes and worker pools that support them. The goal is to better control which workers should execute new, and existing, workflows and activities tasks, based on their code and configuration.

AutoUpgrade and Pinned are two Versioning Behaviors that can be specified on a workflow implementation using @WorkflowVersioningBehavior. Pinned workflows are typically short lived, and are never affected by new versions, i.e., they do not need to use the patch API for compatibility. AutoUpgrade workflows are mostly long running, but they need to use patching to safely transition to new versions. The choice of Pinned vs AutoUpgrade ultimately depends on your willingness to keep old worker fleets running vs the complexity of patching.

To manage Worker Deployments please use the Temporal CLI, or the WorkflowServiceStubs.

What's Changed

2025-03-10 - 73cb1e9 - Fix API key auth (#2438)
2025-03-10 - ff94971 - Release v1.28.1 (#2439)
2025-03-11 - 0271192 - Add OnConflictOptions Support (#2415)
2025-03-11 - 334e129 - Add support for metadata to test server (#2441)
2025-03-13 - f7b8ded - Unblock UseExisting conflict policy for Nexux WorkflowRunOperation (#2440)
2025-03-14 - 2377114 - Fix workflow ID reuse policy and conflict policy handling (#2446)
2025-03-17 - 48b7223 - Fix spring boot api key enable https (#2445)
2025-03-17 - d430114 - Add Summary to Nexus Operations (#2444)
2025-03-19 - 59bbabb - Make sure the Schedule Client has the namespace header injected (#2452)
2025-03-20 - 6c4c183 - Remove experimental tag from Nexus (#2454)
2025-03-24 - ead142e - 💥 [Breaking] Asyncify slot suppliers (#2433)
2025-03-25 - 93f124f - Priorities for Workflows/Activities (#2453)
2025-03-26 - ad4a426 - Ensure heartbeat details aren't cleared (#2460)
2025-03-31 - c9a1502 - Add support for start delay to the time skipping test server (#2462)
2025-04-02 - 75f5d1a - Update Gradle validation action (#2468)
2025-04-02 - b3b7806 - Worker Versioning Annotations & Options (#2463)
2025-04-07 - e3921b6 - Add support for workflow init in Springboot (#2470)
2025-04-15 - 78a766f - Align root workflow execution with real server (#2477)
2025-04-15 - 8808c40 - Add support for activity pause (#2476)
2025-04-15 - b6ae9b5 - De-flake asserting slot metrics (#2478)

v1.28.4

Highlights

• Attaching multiple Nexus callers to an underlying handler Workflow is now available in Pre-release.

What's Changed

2025-04-02 - 6814906 - Ensure heartbeat details aren't cleared (#2460)
2025-04-02 - cdd6497 - Unblock UseExisting conflict policy for Nexus WorkflowRunOperation (#2440)

v1.28.3

What's Changed

2025-03-20 - eed7525 - Revert "Unblock UseExisting conflict policy for Nexux WorkflowRunOperation (#2440)"

v1.28.2

Highlights

Nexus

🎉 Nexus is now generally available 🎉

• Main Nexus APIs are no longer marked as experimental.
• Attaching multiple Nexus callers to an underlying handler Workflow is now Pre-release.

What's Changed

2025-03-20 - 0099134 - Fix workflow ID reuse policy and conflict policy handling (#2446)
2025-03-20 - 0ee60c0 - Unblock UseExisting conflict policy for Nexux WorkflowRunOperation (#2440)
2025-03-20 - 1941d38 - Remove experimental tag from Nexus (#2454)
2025-03-20 - 1f3f068 - Fix spring boot api key enable https (#2445)
2025-03-20 - 26de251 - Make sure the Schedule Client has the namespace header injected (#2452)
2025-03-20 - e3fbdfb - Add OnConflictOptions Support (#2415)

v1.28.1

💥 BREAKING CHANGES

API Keys

The SDK will now automatically set the temporal-namespace header on all gRPC request made by the WorkflowClient. Users
should no longer manually set this header.

To use API keys users should follow this example:

    WorkflowServiceStubs service =
        WorkflowServiceStubs.newServiceStubs(
            WorkflowServiceStubsOptions.newBuilder()
                .addApiKey(
                    () ->
                        <API key>)
                .setTarget(<endpoint>)
                .setEnableHttps(true)
                ...
                .build());

    WorkflowClient client =
        WorkflowClient.newInstance(
            service, WorkflowClientOptions.newBuilder().setNamespace(<namespace_id>.<account_id>).build());

Bugfixes

API Keys

• Fixed an issue where API keys were not being properly set in the WorkflowClient when using the Spring Boot integration.
• Fixed an issue where a worker connecting to a Temporal server with an unconnected client would fail to authenticate.

What's Changed

2025-03-10 - 73cb1e9 - Fix API key auth (#2438)

v1.28.0

💥 BREAKING CHANGES

Nexus (Public Preview)

• ⚠️ IMPORTANT ⚠️ This SDK release requires server >=1.27.0 to properly support the full set of changes from the previous SDK release. Most notably the built-in error translation logic changed in a way that may cause Nexus tasks to retry until the caller specified schedule-to-close timeout on certain failures, see more below.
• Setting WorkflowIDConflictPolicy to WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING has been temporarily disabled, and will fail requests with a retryable internal error.
  • This is to protect users from making a false assumption that the same workflow can be used to back multiple operations. This capability will be enabled in a follow up release.
• WorkflowClientOperationHandlers was renamed to WorkflowRunOperation
• OperationId was renamed to OperationToken and the content for a WorkflowRunOperation of it was changed to a structured token instead of copying the workflow ID directly.
• Removed WorkflowClient from the input of all Temporal nexus handlers, a client can now be accessed by calling Nexus.getOperationContext().getWorkflowClient()
• FailureConverter now supports serializing and deserializing HandlerException . Previously these may have been deserialized as ApplicationFailure .
  • Note: This is can potentially cause Non-Determinism exceptions if users were handling ApplicationFailure .
• The promise returned from NexusOperationHandle.getExecution() now correctly will return the appropriate exception if the underlying nexus fails in a synchronous manner
  • Note: This is can potentially cause Non-Determinism exceptions if users called NexusOperationHandle.getExecution()

Failure Converter

The FailureConverter interface was changed. FailureConverter.failureToException now can return any type implementing RuntimeException instead of just types implementing TemporalFailure

Java Protobuf 3/4 Support

The Temporal Java SDK now supports protobuf-java 3.x and 4.x. To support these, the Temporal Java SDK allows any protobuf library >= 3.25. Temporal strongly recommends using the latest protobuf-java 4.x library unless you absolutely cannot. If you cannot use protobuf-java 3.25 >=, you can try temporal-shaded which includes a shaded version of the protobuf-java library.

Highlights

Spring Boot API Key support

The Java SDK Spring Boot integration now directly supports API key authentication.

For documentation see: https://github.com/temporalio/sdk-java/tree/master/temporal-spring-boot-autoconfigure#api-keys

Spring Boot Multi-Namespace support (Experimental)

The Java SDK Spring Boot integration now has experimental support for running multiple none-root namespace along side the root namespace.

For documentation see: https://github.com/temporalio/sdk-java/tree/master/temporal-spring-boot-autoconfigure#running-multiple-name-space-experimental

What's Changed

2024-12-09 - e1bef89 - Update protocloud submodule (#2344)
2024-12-12 - 53a8af7 - Remove Experimental annotations from Update APIs (#2347)
2024-12-27 - c3e0e77 - Set request Id on SignalWorkflowExecutionRequest (#2352)
2025-01-06 - 82d3c93 - Update Java SDK for Temporal Sever v1.26.2 (#2357)
2025-01-06 - 9a8894a - Set LastHeartbeatDetails on activity failure (#2354)
2025-01-06 - ff333ca - Add javadocs for ActivityCompletionClient (#2353)
2025-01-08 - cf06131 - Test server support for Nexus operation complete before start (#2348)
2025-01-15 - 35e390e - Add method to get workflow client from an activity (#2369)
2025-01-16 - 90e5125 - Fix NDE caused by removing Workflow.getVersion with a succeeding Work… (#2370)
2025-01-16 - b187644 - Add details to manifest (#2355)
2025-01-16 - b593b35 - [OpenTracing] Wrap returned promises in OutboundCallsInterceptor (#2366)
2025-01-17 - 3ad0b0e - Avoid lock up on unexpected ExecutorService errors while executing Local Activities (#2371)
2025-01-22 - b471e13 - Access to workflow/activity instance from context (#2384)
2025-01-22 - c51e5d1 - Upgrade some test dependencies (#2382)
2025-01-22 - cdbc520 - Split up & use more appropriate timeouts for parallel LAs test (#2385)
2025-01-28 - 8b17a52 - Support Proto 3 and 4 (#2383)
2025-01-28 - ce90d24 - Enable speculative workflow tasks (#2390)
2025-01-28 - f93910b - Make sure GetVersion never yields (#2376)
2025-02-03 - de33b3a - Update docs for max workflow task timeout (#2396)
2025-02-04 - fd65ea9 - Inject namespace header (#2400)
2025-02-07 - 32df8d4 - Remove Nexus sync client handler (#2403)
2025-02-07 - 76630fe - Update max task timeout (#2407)
2025-02-10 - 32fbf02 - Fix kotlin child workflow execute varargs (#2395)
2025-02-10 - f9a9cad - Rename WorkflowClientOperationHandlers->WorkflowRunOperation (#2405)
2025-02-10 - fc4d714 - Update proto v1.44.0 (#2406)
2025-02-11 - 00f7dd0 - Add API key property to Springboot (#2408)
2025-02-11 - 24f225c - Java test server support for attaching links to signal and signal with start requests (#2411)
2025-02-12 - c6e0306 - Special behavior for Temporal built-in prefixes (#2409)
2025-02-17 - c6375d6 - feat: multi namespace support (#2378)
2025-02-18 - 436d080 - Add Graal reflection config for UwS (#2363)
2025-02-18 - 6f4621d - Update readme for multi namespace support (#2416)
2025-02-18 - a2455af - Make sure workflow_task_execution_failed always has a failure_reason (#2419)
2025-02-18 - a643a79 - Add nexus configuration to spring boot readme (#2417)
2025-02-20 - f92b53c - 💥 Nexus error rehydration (#2365)
2025-02-21 - 963ea9f - Add sdk name/version to task completions when unset or changed (#2422)
2025-02-24 - 49bd366 - Add support for operation timeout header (#2427)
2025-02-24 - 729e25e - Workflow run token (#2421)
2025-02-24 - d0cf3f3 - Add support for attaching to a running workflow (#2424)
2025-02-25 - 7cd4932 - fix documentation in CapacityConfigurationProperties (#2429)
2025-02-25 - f90c57b - Block using conflict policy UseExisting for Nexus WorkflowRunOperation (#2428)

v1.27.1

Highlights

Fixes an exception when de-serializing a failure from a Nexus operation written by Temporal Sever v1.26.2+.

What's Changed

2024-12-09 - e1bef89 - Update protocloud submodule (#2344)
2024-12-12 - 53a8af7 - Remove Experimental annotations from Update APIs (#2347)
2024-12-27 - c3e0e77 - Set request Id on SignalWorkflowExecutionRequest (#2352)
2025-01-06 - 82d3c93 - Update Java SDK for Temporal Sever v1.26.2 (#2357)

v1.27.0

💥 BREAKING CHANGES

Update With Start (Pre-release)

WorkflowClient

• WorkflowClient.updateWithStart has been renamed to WorkflowClient.startUpdateWithStart.
• Instead of taking the workflow method, workflow arguments and a UpdateWithStartWorkflowOperation, WorkflowClient.startUpdateWithStart now takes the update method, update arguments and a WithStartWorkflowOperation. WithStartWorkflowOperation contains the workflow method and workflow arguments to be executed together with the update request.

WorkflowStub

• WorkflowStub.updateWithStart has been renamed to WorkflowStub.startUpdateWithStart.
• WorkflowStub.startUpdateWithStart now just takes the UpdateOptions, update arguments and workflow arguments.

Update (Public Preview)

• The SDK now preforms more rigorous type validation when registering a Workflow with an @UpdateValidatorMethod to make sure the type parameters match the linked @UpdateMethod.
• The SDK will no longer sometimes throw WorkflowUpdateException when calling WorkflowStub.startUpdate if the update is rejected. WorkflowUpdateException is now consistently throw when getting the result of the update
• UpdateOptionsBuilder no longer generates a update ID when built. Now a unique UUID is generated when the options are used. This is similar to how WorkflowOptions and workflow ID work.

Nexus (Private Preview)

• Workflow started by a Nexus operation now require the Workflow ID to be specified in the WorkflowOptions.
• The SDK now preforms more rigorous type validation when registering a Nexus Service to make sure it implements the service properly.
• All header maps for Nexus operations are now properly case-insensitive.
• Nexus on Temporal is now in Public Preview.

Highlights

Virtual Threads (Public Preview)

The Java SDK now has experimental support for virtual threads when using a JVM with a version of 21 or higher. Virtual threads can be used inside workflows by enabling WorkerFactoryOptions.setUsingVirtualWorkflowThreads. Users can also use virtual threads for task processing in a worker by enabling WorkerOptions.setUsingVirtualThreads.

Nexus (Private Preview)

WorkerInterceptor now has support for intercepting Nexus workers.

Update (Public Preview)

WorkflowClient now has a set of static methods called startUpdate that can be used to start an update, but not immediately wait on the result. This is a type safe analog to WorkflowStub.startUpdate.

Workflow Metadata (Public Preview)

• The Java SDK now exposes a fixed summary option for local and normal activities.
• The Java SDK now support __temporal_workflow_metadata query, this query allows users to get details about a workflow like its’ current description and what signal, update, and query handlers are registered.

What's Changed

2024-10-16 - acfadbf - Avoid spamming retries in nexusOperationApplicationFailureFailureConversion (#2272)
2024-10-16 - eb64ec3 - Fix code coverage (#2275)
2024-10-17 - 25f5536 - Fix Null pointer exception on passing empty search attribute (#2277)
2024-10-21 - 0ce1d6e - Bump edge test dependencies (#2279)
2024-10-21 - 301e129 - Fix test server operation timeout (#2282)
2024-10-21 - ac3526b - Avoid warning from un-accessed operation promise (#2280)
2024-10-22 - 3410677 - Fix UpdateWithStart untyped operation (#2288)
2024-10-22 - 7bcade2 - Fix UpdateWithStart workflow args (#2286)
2024-10-24 - 27d998a - Add failure_reason to nexus_task_execution_failed (#2274)
2024-10-24 - 805833c - Release v1.26.1 (#2293)
2024-10-24 - 93e30d7 - Avoid SyncOperationTimeoutTest spamming the test server (#2292)
2024-10-24 - b8c4b7b - Fix proto decoding in a Nexus Operation (#2281)
2024-10-25 - 2ded985 - Bump Java edge dependency version to 21 (#2296)
2024-10-25 - 6efbde3 - Update gradle 7.6.1 -> 8.10.2 (#2294)
2024-10-29 - 0b192d3 - Fix workflow implementation in springboot failing if no default constructor is present (#2300)
2024-10-30 - c96f8d6 - Add workflow metadata query (#2301)
2024-10-31 - 37081cc - Fix jacoco coverage (#2304)
2024-10-31 - b45e40d - Remove feature branch (#2303)
2024-11-03 - f6bf576 - Add support for virtual workflow threads (#2297)
2024-11-04 - c8a27ce - Add activity summary (#2306)
2024-11-12 - 24990db - Ad support for local activity metadata (#2309)
2024-11-12 - 83f47ef - Make sure workflow options from proxy call are propagated (#2310)
2024-11-12 - b53f304 - Expose fromWorkflowStub (#2311)
2024-11-13 - 02ff5cd - Add timeout to canRunWithResourceBasedTuner (#2313)
2024-11-14 - 4cee4e0 - Validate with generic parameter types for workflow init (#2318)
2024-11-14 - 7ab0f6c - Refactor workflow init validation (#2316)
2024-11-15 - 2a68883 - Generate update ID at call time if not set (#2319)
2024-11-22 - 16b0bb9 - Disable eager activities if task queue rate limits is set (#2325)
2024-11-22 - 1d86a57 - Support toString on workflow proxy types (#2315)
2024-11-22 - c6f0b58 - Do runtime check to ensure update validator has the same parameters as the update it validates (#2323)
2024-11-23 - 74022f1 - Add getResult to WorkflowUpdateHandle (#2324)
2024-11-25 - a2dd369 - Add high-level workflow describe (#2326)
2024-11-26 - 89021d0 - Add type safe API to execute an async update workflow request (#2320)
2024-12-01 - fcc0343 - Fix CI after GHA's drop of node16 actions (#2338)
2024-12-02 - 5212a34 - Skip flaky test (#2334)
2024-12-02 - 7245bf8 - Require workflow ID to be set for Nexus (#2330)
2024-12-02 - e3ef9b4 - Standardized update failure exception (#2339)
2024-12-03 - 8782de3 - Make nexus header check case-insensitive (#2335)
2024-12-03 - cbcf26c - Fix unbalanced locks in test server for Nexus (#2341)
2024-12-04 - c7fcf12 - Make headers in ExecuteNexusOperationInput case insensitive (#2342)
2024-12-06 - 30f391f - Add Nexus Worker interceptor (#2278)
2024-12-06 - 7073375 - Add operation Id to callback headers (#2336)
2024-12-06 - 9ac1af3 - New Update-with-Start API (#2337)

v1.26.2

Bugfixes

Spring Boot

• Fixed an issue where Workflows could not be registered if they used a constructor to autowire.

Nexus

• Fixed an issue where some Workflow options were not passed when using WorkflowClientOperationHandlers.

What's Changed

2024-11-21 - 01530ec - Fix workflow implementation in springboot failing if no default constructor is present (#2300)
2024-11-21 - 8372337 - Make sure workflow options from proxy call are propagated (#2310)

v1.26.1

Bugfixes

Update With Start

• Fixed a issue where Workflow inputs were not being sent properly when using WorkflowClient.updateWithStart.
• Fixed a issue where WorkflowClient.updateWithStart would fail if used with an UpdateWithStartWorkflowOperation created with an update name.

Nexus

• Fixed a issue where the Operations parameter type was not being properly sent to the DataConverter.
• Fixed an exception being thrown if a null result was returned from a sync handlers.
• Fixed a bug where the time skipping test server would instantly timeout an operation if not timeout was set.

What's Changed

2024-10-16 - acfadbf - Avoid spamming retries in nexusOperationApplicationFailureFailureConversion (#2272)
2024-10-16 - eb64ec3 - Fix code coverage (#2275)
2024-10-17 - 25f5536 - Fix Null pointer exception on passing empty search attribute (#2277)
2024-10-21 - 0ce1d6e - Bump edge test dependencies (#2279)
2024-10-21 - 301e129 - Fix test server operation timeout (#2282)
2024-10-21 - ac3526b - Avoid warning from un-accessed operation promise (#2280)
2024-10-22 - 3410677 - Fix UpdateWithStart untyped operation (#2288)
2024-10-22 - 7bcade2 - Fix UpdateWithStart workflow args (#2286)
2024-10-24 - 27d998a - Add failure_reason to nexus_task_execution_failed (#2274)
2024-10-24 - 93e30d7 - Avoid SyncOperationTimeoutTest spamming the test server (#2292)
2024-10-24 - b8c4b7b - Fix proto decoding in a Nexus Operation (#2281)