Skip to main content

Cadence Java Client

Cadence follows semantic versioning and you can find more information about changes between version on the Cadence changelog.

Latest release for General Availability

Release v4.0.0 published on 2025-10-14

Java Compatibility

Java versions 21, 17 and 11 are supported at this time.

Due to backward compatibility, Java versions 17+ require the following JVM flag

--add-opens java.base/java.lang=ALL-UNNAMED

Major Releases​

v4.0.x​

v3.12.x​

v3.11.x​

v3.10.x​

v3.9.x​

v3.8.x​

v3.7.x​

v3.6.x​

v3.5.x​

v3.4.x​

v3.3.x​

v3.2.x​

v3.1.x​

v3.0.x​

v2.7.x​

Release Release v4.0.0 published by shijiesheng on 10/14/2025​

Highlights

Thrift Deprecation

Thrift support is now fully removed in Java client. (See why https://github.com/cadence-workflow/cadence-java-client/issues/985 ).

Migration Guide from V3

User facing APIs on workflow operations are mostly unchanged. But there are some BREAKING changes as list below.

Thrift to new Entities in API calls

For users to migrate easily, we generate a new set of entities with the same import path and similar interfaces.

  1. you can no longer access fields directly but instead have to use getter and setter explicitly.
  2. IWorkflowService will no longer throw TException but instead CadenceError; all other exceptions thrown are kept the same extended from CadenceError
  3. IWorkflowService uses com.uber.cadence.serviceclient.AsyncMethodCallback instead of org.apache.thrift.async.AsyncMethodCallback in callback methods.

Data Converter

If your workflow's input or output contains Thrift entities that extended from TBase, TEnum, TException. This is a BREAKING change. You'll need to add back the thrift adapters in your custom dataconverters. We no longer support them by default.

  1. We removed special TBase and TEnum adapter (first introduced to reduce payload size https://github.com/cadence-workflow/cadence-java-client/pull/263).
  2. We removed the ability to convert TException but instead you'll get a fallback type com.uber.cadence.client.ApplicationFailureException

Construct your client

  1. WorkflowServiceTChannel is now removed and replaced by WorkflowServiceGrpc
  2. If you use Grpc before, instead of new Thrift2ProtoAdapter(IGrpcServiceStubs.newInstance()) you can now use WorkflowServiceGrpc() directly.

What's Changed

New Contributors

Full Changelog: https://github.com/cadence-workflow/cadence-java-client/compare/v3.12.7...v4.0.0


Release Release 3.12.4 published by shijiesheng on 6/12/2024​

3.12.4

  • Fix incorrect span activation for local activities

Release Release 3.12.3 published by shijiesheng on 6/4/2024​

3.12.3

  • Remove unused direct dependency of com.google.http-client
  • Fix context propagation bug that would link two parents in some cases

Release Release 3.12.2 published by shijiesheng on 5/22/2024​

What's Changed

  • downgrade java-jwt dependency to 3.10.2

Release Release 3.12.1 published by abhishekj720 on 5/17/2024​

What's Changed


Release v3.12.0 published by natemort on 5/3/2024​

What's Changed

  • Added support for new Async APIs for starting large numbers of workflows.
  • Added support for two-legged OAuth flow
  • Added support for standard JWT exp and iat claims
  • Updated WorkerOptions to default to the Tracer used to initialize WorkflowClient.
  • Fixed ClassCastException when using Promise#allOf(Promise<?>...)
  • Fixed NullPointerException in ContextPropagation when Header is present but fields is null

New Contributors

Full Changelog: https://github.com/uber/cadence-java-client/compare/v3.11.0...v3.12.0


Release Release 3.11.0 published by shijiesheng on 4/15/2024​

  • added opentracing support in workflow lifecycles
  • Bump io.grpc related dependency versions
  • Added signalWorkflow and tests for both SignalWorkflowExecution and SignalWithStart
  • Updating Docker cassandra version to 4.1.3
  • Add CODEOWNERS file

Release Release 3.10.1-fix published by abhishekj720 on 2/1/2024​

  • Bug Fix:Enhanced Workflow Handling for Existing Instances in New Domains
  • Populate tasklistkind in poll request

Release Release 3.10.1 published by abhishekj720 on 9/29/2023​

  • Added case of workflow already started for migration

Release Release 3.10.0 published by abhishekj720 on 8/25/2023​

  • Added migrationIWorkflowService
  • Added migrationInterceptor
  • Moved out TracingInterceptor from WorkflowTest to a separate package

Release Release 3.9.1 published by abhishekj720 on 8/11/2023​

  • Added initialization of contextPropagators from passed options
  • Updated rpc-caller header of grpc

Release Release 3.9.0 published by Shaddoll on 7/3/2023​

Added

  • Add ability to override activity options
  • Add executeWorkflow method to WorkflowInterceptor
  • Add isolation group to service client options so that requests are populated with isolation group header
  • Add cause tag for transient poll failures
  • Add workflow start event and data converter to workflow info

Changed

  • Update dependencies
  • Remove unused code
  • Remove reflective objects exception due to failing builds
  • Fix the gradle project for M1 macs
  • Add cronschedule to history start event and fix isCron check of listworkflow for test env

Release Release 3.8.1 published by mindaugasbarcauskas on 1/6/2023​

Removed openetelemtry-bom dependency since it is not really needed for a library like cadence-jave-client. it is enough to depend on opentelemetry-api which is just the opentelemetry interface.


Release Release 3.8.0 published by mindaugasbarcauskas on 11/15/2022​

  • Graceful shutdown based on sigterm handler
  • Adding cross domain signal/child workflow creation support
  • Adding open telemetry support so that open telemetry context is propagated to cadence-server
  • Adding dynamic poller support for more efficient resource usage.

Release Release 3.7.3 published by mindaugasbarcauskas on 9/12/2022​

Fix describe domain and update domain grpc calls to include domainConfiguration and replication configuration in response.


Release Release 3.7.2 published by mkolodezny on 8/11/2022​

  • Fix gRPC adapter for List APIs

Release Release 3.7.1 published by mkolodezny on 8/4/2022​

New Features

  • Add gRPC channel to client options (#731 )

Release Release 3.7.0 published by mkolodezny on 8/2/2022​

New Features

  • Add gRPC compatibility layer (#673)

Release Release 3.6.2 published by mkolodezny on 5/5/2022​

  • Add refresh tasks API to provide ability to refresh tasks on stuck workflows

Release Release 3.6.1 published by mkolodezny on 1/19/2022​

Bug fixes

  • Fix a bug for PollOnlyIfExecutorHasCapacity flag about pool size (#666)

Credits

Thank you @spmistry for the contribution!


Release Release 3.6.0 published by mkolodezny on 1/11/2022​

New Features

  • Introduce experimental flag and add logic for capacity based polling.

Credits

Thank you @spmistry for the contribution!


Release Release 3.5.1 published by mkolodezny on 11/24/2021​

New Features

  • Add CadenceChangeVersion support.
  • Allow using other tags in metric reporter.
  • Add metric tag to differentiate long-poll and normal request.

Bug fixes

  • Fix identity for sticky worker.
  • Improve contributing guide.

Release Release v3.5.0 published by mkolodezny on 10/4/2021​

Improvements

  • Fix consistent query interface which caused overloading ambiguity with variable argument (#644)

Release Release v3.4.0 published by mkolodezny on 10/1/2021​

New Features

  • Add Health check API to worker and service interface (#641)
  • Support delay start for cron workflows (#640)

Credits

Thank you @spmistry for the contribution!


Release Release v3.3.0 published by demirkayaender on 9/1/2021​

New Features

  • Added feature flags to ship breaking changes without impacting old behavior. [#633]

Release Release v3.2.0 published by mkolodezny on 8/15/2021​

New Features

  • Add consistent query support (#530 ) The feature requires sever version >= 0.22.0 if enabled feature version checking.
  • Add Health check API to worker and service interface (#617)

Improvements

  • Replace sticky tasklist metrics scope with the same value (#601 )

Credits

Thank you @AngerM-DD for the contribution!


Release Release v3.1.0 published by yux0 on 5/13/2021​

This release contains breaking changes and new features.

New Features

  • Provide Shadowing worker for replay workflow traffic (#598, #600, #604, #603)

Breaking changes

  • Introduce WorkflowExecutionCompletedError in SignalWorkflowExecution/CancelWorkflowExecution/TerminateWorkflowExecution (#606, #611)

Improvements

  • Add all missing version marker before upsert Search Attributes (#608)
  • Add activity worker thread count metrics (#607)
  • Add binaryChecksum support to JDK (#605, #610)
  • Add test coverage report (#599)

Release Release 3.0.0 published by yux0 on 3/5/2021​

This release contains breaking changes and new features.

New Features

  • update idls to use ActivityLocalDispatchInfo for local activity dispatch (#563)
  • Add option to dispatch activity tasks locally (#564)
  • do not dispatch activities locally if taskListActivitiesPerSecond is set (#567)
  • use noop worker when local dispatch disabled (#569)
  • Pass taskListActivitiesPerSecond down to ActivityWorker (#556)
  • Remove default taskListActivitiesPerSecond limit (#578)
  • add missing workflowtype and activitytype metric tags (#581)

Breaking changes

  • Remove disable activity and workflow worker options (#540)
  • Refactor options and worker dependencies (#551)
  • Worker and Options refactoring part 2 (#552)

Bug fixes

  • Fix ACTIVITY_E2E_LATENCY metrics (#537)
  • Switched newProxyInstance to the correct class (#539)
  • Add automerge workflow (#541)
  • Revert "Add automerge workflow (#541)
  • Update buildkite scripts (#542)
  • Cleanup retryer and retry options (#558)
  • Adjust various default timeout values (#568)
  • Improve contribution documentation (#575)
  • Prevent iterator panic and add error log (#576)
  • Updating link to java docs (#580)
  • Clean up workflow query handling (#582)
  • Fix null pointer exception in deserialize blob (#585)

Release Release 2.7.8 published by vancexu on 10/5/2020​

This release contains several bug fixes.

70fe1a7 Fix get raw history (#534) 2790692 Improve signal processing error and log (#535) f984029 Fix replay error when querying workflow that contains activity retry (#532)


Release Release 2.7.6 published by vancexu on 9/22/2020​

cdc5aab Fix start async return (#529) ff05ea1 Fix a bug in setting retry expiration while getting history (#528) 47f7ecf Add missing metrics from go client (#379) (#518) 0dbd1bc Fix RetryOptions.addDoNotRetry (#520) d98d33f Add async signal to untypedstub (#527) 7c0e2ab Fix getVersion override when added new version (#526)


For a comprehensive list of changes and detailed release notes, please visit the Cadence Java Client GitHub Releases page.