Releases: temporalio/sdk-java
v1.32.0
💥 BREAKING CHANGES
Spring Boot
Customizers
The Java SDK Spring Boot integration now allows multiple customizers for the main Namespace. Multi-Namespace support coming as part of #2656.
Highlights
Environment Configuration
Added a new package temporal-envconfig to support Environment Configuration. Environment Configuration provides a way to configure clients using environment variables and TOML configuration files, rather than setting connection options programmatically in your code.
For more please see our docs page here, Java SDK specific docs coming soon.
What's Changed
2025-08-25 - 4ae92d3 - Ensure namespace exists on worker startup (#2609)
2025-08-28 - 31d044c - Make sure workflow_task_queue_poll_succeed is emitted (#2645)
2025-09-02 - eaad70d - Update Spring Boot README.md to link to docs (#2646)
2025-09-13 - bf0b196 - Allow multiple customizers in Springboot (#2649)
2025-09-18 - c67ca60 - Add NexusInfo (#2658)
2025-09-22 - 5629f0c - Don't set error status on otel spans for benign exceptions (#2663)
2025-09-24 - 4631b16 - Add support for environment config (#2660)
2025-09-25 - 785f5cd - Bump dependencies (#2668)
2025-09-26 - a05c855 - Fix UNKNOWN gRPC error on describe (#2672)
2025-10-09 - 6239adb - Use macOS 15 intel runner (#2678)
2025-10-10 - 89c427e - Fix gradle version determination breaking in some environments (#2682)
2025-10-10 - f9a5d74 - fix: set type metadata on search attribute payloads in test server (#2677)
2025-10-15 - 832785d - Add grpc-inprocess, grpc-util to shaded dependencies (#2686)
2025-10-15 - c040f0d - Add separate deployment name and build id fields for spring (#2681)
2025-10-17 - 69d2363 - Remove experimental status from worker tuners (#2683)
2025-10-21 - c46eb46 - Bump gradle action to v5 (#2700)
2025-10-21 - fd0351c - Add javadocs for in-workflow, workflow stubs (#2701)
2025-10-22 - 1b29853 - finish wiring up cancel cause to Workflow cancellation. (#2695)
2025-10-22 - 4e9cc06 - Set worker version on eager start requests (#2704)
2025-10-22 - 850515b - Align workflow_task_schedule_to_start_latency (#2669)
2025-10-22 - 9c7a5d1 - Update Jackson to 2.15.4 (#2691)
2025-10-22 - 9cd7ca8 - Clean up some test assertions and make sure naming is consistent. (#2690)
2025-10-22 - b12ee45 - Add support for FirstExecutionRunId to cancel and terminate (#2692)
2025-10-22 - b160fb0 - improve error messages in RpcRetryOptions (#2708)
2025-10-22 - f864e8a - Correct Preconditions error message in WorkerFactory (#2693)
2025-10-24 - 019ad70 - Replace tctl references with Temporal CLI (#2688)
2025-10-24 - 1c9b007 - Fix resource based tuner metrics missing temporal_ prefix (#2710)
2025-10-27 - e7c0c2a - Fix envconf path (#2715)
2025-10-29 - 9bc29c8 - Set explicit permissions for GitHub Actions workflows
2025-10-29 - fdf9994 - Report cpu/mem metrics on 0-100 range to match core (#2719)
2025-10-30 - a7e38ec - Add summary to side effect and mutable side effect (#2699)
2025-11-06 - 3f41b69 - Remove experimental labels from poller behavior options (#2721)
2025-11-06 - be353bc - add nightly throughput stress (#2717)
2025-11-12 - 5394310 - Set default workflow task failure cause to unhandled failure (#2706)
2025-11-13 - 7577911 - Add new constructor for WorkflowStub to target correct execution (#2709)
v1.31.0
Highlights
Task Queue Fairness (Pre-release)
This release adds support for Task Queue Fairness. Fairness is a new feature of Temporal’s task queues that allows for more control over the order that tasks are dispatched from a backlog. It’s intended to address common situations like multi-tenant applications and reserved capacity bands. For more details see the javadoc's on io.temporal.common.Priority.
Fairness 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 to be enabled once it is available in Temporal Cloud.
Bugfixes
No longer retry "gRPC message size to large" error
The SDK will no longer retry "gRPC message size to large" errors or related errors. These errors occur if the user tries to make a gRPC request that exceeds the Temporal Service limits (typically 4 MB).
What's Changed
2025-06-26 - 68e4c4c - Add defaults for PollerBehaviorAutoscaling (#2574)
2025-06-27 - 4afe41b - Publish to Sonatype central (#2576)
2025-06-27 - a1eb7dc - Don't scale down on error if we have never seen a poller decision (#2575)
2025-07-03 - f919926 - Update snapshot URL (#2577)
2025-07-07 - fd648d1 - Fix flake in testNullTaskReleasesSlot (#2583)
2025-07-08 - 4acf674 - Update test server to v1.4.0 (#2587)
2025-07-08 - d310594 - Add support for activity reset (#2546)
2025-07-08 - d75b253 - Update Proto API to v1.50.0 (#2581)
2025-07-10 - bc5ab1d - When parsing operation token allow a zero version (#2591)
2025-07-10 - ca3a27a - Use correct operation token on OPERATION_TOKEN (#2589)
2025-07-17 - ffb44f9 - Remove @experimental notice from Update-with-start (#2599)
2025-07-22 - 76672fa - Fix ApplicationFailure.Builder handling a null Category (#2602)
2025-08-01 - 26546a7 - Fix using wrong config option for resource controller (#2607)
2025-08-11 - f9580aa - Align Nexus handler failure conversion with other SDKs (#2613)
2025-08-12 - b5057e8 - Fix adding a generic parameter failing (#2619)
2025-08-12 - cd76ad6 - Do not auto-retry gRPC-message-size-too-large errors (#2604)
2025-08-12 - ff939d7 - Nexus - Only pass a completion callback if a completion URL is provided (#2615)
2025-08-13 - 0dd76e0 - Add info on features test issue for CI (#2623)
2025-08-13 - 5b7e82c - Added retry options to ActivityInfo. Added ActivityInfo tests. (#2622)
2025-08-15 - acf7473 - Bump some Github actions (#2628)
2025-08-15 - b854df4 - Clarify NexusOperationCancellationType (#2630)
2025-08-15 - f2475c1 - Bump cloud api version to v0.7.1
2025-08-18 - 71c7426 - Fix Javadoc of io.temporal.workflow.Workflow#getVersion (#2631)
2025-08-19 - b6b4290 - Fairness Keys & Weights (#2633)
2025-08-20 - 943fe2e - Revert removing "Control" field (#2634)
Contributors
Assets 8
v1.30.1
v1.30.0
💥 BREAKING CHANGES
Workflow Metadata (Public Preview)
The built in __temporal_workflow_metadata query now uses io.temporal.common.converter.RawValue for the return type. This should help address issues where users data converters could not properly convert the WorkflowMetadata protobuf type. If you are using a custom data converter that does not support RawValue you will need to update it to support this type.
Note: The built in Temporal DefaultDataConverter already supports RawValue and does not require any changes.
Nexus
When an ApplicationFailure is returned from a Nexus operation handler the SDK will now translate it into an INTERNAL non-retryable error. Previously it was translated to a BAD_REQUEST error. This is to align with the behavior of Nexus operations in other SDKs.
Highlights
Nexus Operation Cancellation Types (Pre-release)
Users can now specify the cancellation type when cancelling a Nexus operations from a workflow. This allows for more granular control over how Nexus operations are cancelled, and how the caller is notified of the cancellation.
Springboot (Pre-release)
-
Temporal Java SDK Springboot integration now automatically registers Temporal interceptors. Interceptors will be registered in the order specified by the
@Orderannotation. -
Temporal Java SDK Springboot integration now applies to Springboot
Environmentwhen discovering workflow implementations. This allows users to use the@Profileannotation to conditionally enable or disable workflow implementations.
Automatic Poller Scaling (Pre-release)
Users can now configure Workers to automatically scale the number of concurrent polls they make. To enable use setWorkflowTaskPollersBehavior, setNexusTaskPollersBehavior, and setActivityTaskPollersBehavior arguments of the WorkerOptions.Builder constructor to PollerBehaviorAutoscaling. You can expect fewer unnecessary polls during low load, and increased polls during high load when they can be used to increase task throughput.
Add ApplicationFailure Category
Add a new category property on ApplicationFailure. This new option allows controlling some of the observability and logging behaviors of the Worker related to a failure thrown from an Activity.
What's Changed
2025-04-21 - afb0183 - ARM64 build for Test Server (#2448)
2025-04-23 - 08d6089 - Remove old workflow run operation token format (#2486)
2025-04-23 - 0f9813c - Handle async completion in TestActivityEnvironment (#2487)
2025-04-24 - 2807771 - Warn if root thread yields (#2483)
2025-04-24 - 620eeaf - Update contrib (#2489)
2025-04-25 - 7460156 - Add application err category (#2485)
2025-04-29 - 3c9e819 - Add RawValue support (#2492)
2025-04-30 - 04fe25a - Fix NPE getting a non existent memo from a schedule. (#2497)
2025-04-30 - f6d4d46 - Make sure user metadata is set on WorkflowExecutionStartedEvent (#2496)
2025-05-01 - 537d99d - Add ApplicationFailure.Builder (#2495)
2025-05-02 - 1feb16f - Remove license in file (#2505)
2025-05-02 - 2e1c89e - Add support for dynamics workflows to Springboot (#2506)
2025-05-05 - 0d539ff - Support WorkflowImplementationOptionsCustomizer (#2503)
2025-05-05 - 0e8ac35 - Make @Profile annotation work (#2501)
2025-05-05 - 8fbb068 - Add interceptor support to springboot integration (#2500)
2025-05-06 - 7a09384 - Update proto v1.49.0 (#2510)
2025-05-07 - 4da87cc - Spring boot: fail creation if duplicate definitions detected (#2511)
2025-05-07 - e5bb3a5 - Bump edge Java SDK test version (#2507)
2025-05-08 - e7a7f0c - Set links in Nexus callback (#2513)
2025-05-09 - 6c961a0 - Make CancellationScopeImpl more deterministic (#2512)
2025-05-13 - b7c72a2 - Add num_pollers metric (#2514)
2025-05-14 - 076f981 - Add test coverage for starting a child workflow from a cancelled work… (#2516)
2025-05-14 - 3f294e1 - Remove license check from contrib (#2522)
2025-05-14 - 58a4200 - RequestIdInfo and links changes in test server (#2515)
2025-05-14 - 7046593 - Add test coverage for cancellation of external workflow (#2517)
2025-05-14 - b9458fc - Wire reason parameter in workflow cancellation request (#2519)
2025-05-14 - e8d9fda - Add API to count workflows (#2518)
2025-05-15 - d01c85b - Add AGENTS.md (#2527)
2025-05-16 - 437c612 - Fix Workflow.getWorkflowExecution for ExternalWorkflowStub (#2529)
2025-05-16 - 95314a2 - Versioning Override support (#2530)
2025-05-16 - e793db8 - Make asyncThrottlerExecutor use a daemon thread (#2528)
2025-05-26 - 2d9b906 - Fix newExternalWorkflowStub on a interfaces without a WorkflowMethod (#2531)
2025-05-26 - f45c947 - Cancel pending heartbeat when activity completes (#2526)
2025-05-27 - 0b88507 - Bump some proto dep. (#2536)
2025-05-27 - 5d64818 - Fix javadoc for ActivityExecutionContext.getHeartbeatDetails (#2525)
2025-05-28 - 44d9abe - Set TemporalChangeVersion when workflow version is updated (#2464)
2025-05-28 - 8613b18 - Fix nexus error translation (#2539)
2025-06-02 - cea73d3 - Add support for calling Workflow.getInfo from query handler (#2541)
2025-06-03 - ed2b8cc - Add an interceptor for listExecutions (#2524)
2025-06-04 - 35386da - Clear MDC context after each task (#2545)
2025-06-04 - dc1e26d - Update cloud ops apis to the latest (#2544)
2025-06-09 - 402392c - Use link from start workflow request for Nexus operations (#2547)
2025-06-10 - 0268390 - __temporal_workflow_metadata query responses should use "RawValue" (#2551)
2025-06-10 - 746d3c3 - Issue #2057: parsing workflow id from WorkflowExecutionStartedEventAttributes (#2542)
2025-06-11 - 4f313bb - Add poller autoscaling (#2535)
2025-06-11 - bdc94f7 - Add native build to CI and MUSL build (#2490)
2025-06-12 - 5978835 - Set deploymentOptions on other types of poll requests (#2555)
2025-06-12 - a25f6ba - Fix ignoreDuplicateDefinitions to log only if we are ignoring (#2553)
2025-06-12 - b581ede - Add poller autoscaling options for Springboot (#2554)
2025-06-12 - e7e3fa6 - Implement Nexus operation cancellation types (#2520)
2025-06-13 - 231c724 - Don't fail Springboot if a bean is specified twice (#2558)
2025-06-17 - 4686691 - Fix some dependency issues with NonRootBeanPostProcessor (#2556)
2025-06-17 - a120887 - Deprecate VersioningIntent (#2561)
2025-06-18 - 4a05f51 - Fix build-native-image action again (#2567)
2025-06-18 - 7e83945 - Release Java SDK v1.30.0-RC1 (#2563)
2025-06-18 - b3757fc - Fix build-native-image (#2566)
2025-06-24 - e6e0867 - Make sure PollerBehavior is marked as Experimental (#2569)
Contributors
Assets 8
v1.30.0-RC1
💥 BREAKING CHANGES
Workflow Metadata (Public Preview)
The built in __temporal_workflow_metadata query now uses io.temporal.common.converter.RawValue for the return type. This should help address issues where users data converters could not properly convert the WorkflowMetadata protobuf type. If you are using a custom data converter that does not support RawValue you will need to update it to support this type.
Note: The built in Temporal DefaultDataConverter already supports RawValue and does not require any changes.
Nexus
When an ApplicationFailure is returned from a Nexus operation handler the SDK will now translate it into an INTERNAL non-retryable error. Previously it was translated to a BAD_REQUEST error. This is to align with the behavior of Nexus operations in other SDKs.
Highlights
Nexus Operation Cancellation Types (Pre-release)
Users can now specify the cancellation type when cancelling a Nexus operations from a workflow. This allows for more granular control over how Nexus operations are cancelled, and how the caller is notified of the cancellation.
Springboot (Pre-release)
Temporal Java SDK Springboot integration now automatically registers Temporal interceptors. Interceptors will be registered in the order specified by the @Order annotation.
Automatic Poller Scaling (Pre-release)
Users can now configure Workers to automatically scale the number of concurrent polls they make. To enable use setWorkflowTaskPollersBehavior, setNexusTaskPollersBehavior, and setActivityTaskPollersBehavior arguments of the WorkerOptions.Builder constructor to PollerBehaviorAutoscaling. You can expect fewer unnecessary polls during low load, and increased polls during high load when they can be used to increase task throughput.
What's Changed
2025-04-21 - afb0183 - ARM64 build for Test Server (#2448)
2025-04-23 - 08d6089 - Remove old workflow run operation token format (#2486)
2025-04-23 - 0f9813c - Handle async completion in TestActivityEnvironment (#2487)
2025-04-24 - 2807771 - Warn if root thread yields (#2483)
2025-04-24 - 620eeaf - Update contrib (#2489)
2025-04-25 - 7460156 - Add application err category (#2485)
2025-04-29 - 3c9e819 - Add RawValue support (#2492)
2025-04-30 - 04fe25a - Fix NPE getting a non existent memo from a schedule. (#2497)
2025-04-30 - f6d4d46 - Make sure user metadata is set on WorkflowExecutionStartedEvent (#2496)
2025-05-01 - 537d99d - Add ApplicationFailure.Builder (#2495)
2025-05-02 - 1feb16f - Remove license in file (#2505)
2025-05-02 - 2e1c89e - Add support for dynamics workflows to Springboot (#2506)
2025-05-05 - 0d539ff - Support WorkflowImplementationOptionsCustomizer (#2503)
2025-05-05 - 0e8ac35 - Make @Profile annotation work (#2501)
2025-05-05 - 8fbb068 - Add interceptor support to springboot integration (#2500)
2025-05-06 - 7a09384 - Update proto v1.49.0 (#2510)
2025-05-07 - 4da87cc - Spring boot: fail creation if duplicate definitions detected (#2511)
2025-05-07 - e5bb3a5 - Bump edge Java SDK test version (#2507)
2025-05-08 - e7a7f0c - Set links in Nexus callback (#2513)
2025-05-09 - 6c961a0 - Make CancellationScopeImpl more deterministic (#2512)
2025-05-13 - b7c72a2 - Add num_pollers metric (#2514)
2025-05-14 - 076f981 - Add test coverage for starting a child workflow from a cancelled work… (#2516)
2025-05-14 - 3f294e1 - Remove license check from contrib (#2522)
2025-05-14 - 58a4200 - RequestIdInfo and links changes in test server (#2515)
2025-05-14 - 7046593 - Add test coverage for cancellation of external workflow (#2517)
2025-05-14 - b9458fc - Wire reason parameter in workflow cancellation request (#2519)
2025-05-14 - e8d9fda - Add API to count workflows (#2518)
2025-05-15 - d01c85b - Add AGENTS.md (#2527)
2025-05-16 - 437c612 - Fix Workflow.getWorkflowExecution for ExternalWorkflowStub (#2529)
2025-05-16 - 95314a2 - Versioning Override support (#2530)
2025-05-16 - e793db8 - Make asyncThrottlerExecutor use a daemon thread (#2528)
2025-05-26 - 2d9b906 - Fix newExternalWorkflowStub on a interfaces without a WorkflowMethod (#2531)
2025-05-26 - f45c947 - Cancel pending heartbeat when activity completes (#2526)
2025-05-27 - 0b88507 - Bump some proto dep. (#2536)
2025-05-27 - 5d64818 - Fix javadoc for ActivityExecutionContext.getHeartbeatDetails (#2525)
2025-05-28 - 44d9abe - Set TemporalChangeVersion when workflow version is updated (#2464)
2025-05-28 - 8613b18 - Fix nexus error translation (#2539)
2025-06-02 - cea73d3 - Add support for calling Workflow.getInfo from query handler (#2541)
2025-06-03 - ed2b8cc - Add an interceptor for listExecutions (#2524)
2025-06-04 - 35386da - Clear MDC context after each task (#2545)
2025-06-04 - dc1e26d - Update cloud ops apis to the latest (#2544)
2025-06-09 - 402392c - Use link from start workflow request for Nexus operations (#2547)
2025-06-10 - 0268390 - __temporal_workflow_metadata query responses should use "RawValue" (#2551)
2025-06-10 - 746d3c3 - Issue #2057: parsing workflow id from WorkflowExecutionStartedEventAttributes (#2542)
2025-06-11 - 4f313bb - Add poller autoscaling (#2535)
2025-06-11 - bdc94f7 - Add native build to CI and MUSL build (#2490)
2025-06-12 - 5978835 - Set deploymentOptions on other types of poll requests (#2555)
2025-06-12 - a25f6ba - Fix ignoreDuplicateDefinitions to log only if we are ignoring (#2553)
2025-06-12 - b581ede - Add poller autoscaling options for Springboot (#2554)
2025-06-12 - e7e3fa6 - Implement Nexus operation cancellation types (#2520)
2025-06-13 - 231c724 - Don't fail Springboot if a bean is specified twice (#2558)
2025-06-17 - 4686691 - Fix some dependency issues with NonRootBeanPostProcessor (#2556)
2025-06-17 - a120887 - Deprecate VersioningIntent (#2561)
Contributors
Assets 8
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
v1.28.3
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
WorkflowClientwhen using the Spring Boot integration. - Fixed an issue where a worker connecting to a Temporal server with an unconnected client would fail to authenticate.