github temporalio/sdk-java v1.41.0

one hour ago

💥 Breaking Changes

  • WorkflowOutboundCallsInterceptor has new sleep(Duration, TimerOptions) and
    await(Duration, TimerOptions, String, Supplier) methods. Implementations that don't extend
    WorkflowOutboundCallsInterceptorBase need to add them, and Base subclasses override them to see calls with options.
  • Experimental: A @TemporalOperation handler can now send only one signal per operation invocation; signal
    and signalWithStart count toward the same limit. While the first signal is in flight, or after it succeeds, a
    second signal to any workflow throws a BAD_REQUEST HandlerException. If the first signal fails, the handler can
    signal again. signalWithStart from such a handler also requires an explicit workflow ID, since a defaulted ID
    differs on each retried Nexus task and would start another workflow.
  • Workers now retryably fail a workflow or activity task whose payloads exceed the namespace's size
    limit, instead of sending it to the server. Disable with
    WorkerOptions.Builder.setDisablePayloadErrorLimit; tune warnings with the experimental
    WorkflowServiceStubsOptions.Builder.setPayloadLimits.

Added

  • Tracing options and ContextPropagator.encodeHeaders() can opt into header processing using
    the configured client's payload codec. Only opted-in producers' output is encoded, while
    application-supplied wire-ready headers are unchanged. Receiving consumers use private decoded
    views. Existing propagators default to false; custom converter wrappers can expose their codec
    through PayloadCodecProvider.
  • Poller pools now report their poller target to the server on each poll and in the worker
    heartbeat, covering workflow, sticky workflow, activity, and Nexus pools. An autoscaling pool
    reports its current target, a fixed-size pool its configured size. (We'll use this count on the
    server side for now for load balancing pollers between workers, and for creating a per-worker
    poller count metric.)
  • Applications can use the experimental @TransferTypeConvertible annotation and
    TransferTypeConverter interface to convert top-level model values to transfer types. The SDK
    applies this conversion to workflow, activity, Nexus, and schedule payloads, including failure
    details. WorkflowClient.getOptions().getDataConverter() returns the transfer-aware converter
    that the client uses.
  • Worker heartbeats now report detected Graal native-image and Kotlin runtimes alongside the JVM
    version. Detection is best effort and respects the worker environment information opt-out.
    Factory registration overloads accept an implementation class for runtime detection, including
    Spring Boot workflow registrations.
  • Added experimental Copyable<T> for isolated in-process copies. Local activities copy
    eligible inputs for each attempt and outputs for live execution, preserving history serialization
    and replay. Deeply immutable values may return themselves.
  • Added experimental ChildWorkflowOptions.Builder.setVersioningOverride and
    VersioningOverride.OneTimeVersioningOverride for explicit pinned, auto-upgrade, and one-time
    child workflow routing. Invalid child overrides are reported as InvalidVersioningOverrideFailure
    under ChildWorkflowFailure.
    Child workflow overrides and one-time routing require Temporal Server 1.32.0 or later.
  • Added experimental client config extensions to temporal-envconfig. Extensions implement
    ClientConfigExtension, read their own config from profile.<profile>.ext.<name> TOML tables
    (exposed as ClientConfigProfile.getExt()) and env vars, and are passed via
    LoadClientConfigProfileOptions.Builder.setExtensions to contribute service stubs plugins to
    ClientConfigProfile.toWorkflowServiceStubsOptions(). Strict mode does not reject keys under
    ext.
  • WorkerFactoryOptions.Builder.setLoggerTagPrefix that can be used to customized structured logging tags (MDC keys)
    set by Temporal SDK in worker context.
  • Spring Boot: the workers attribute of @WorkflowImpl, @ActivityImpl and @NexusServiceImpl now resolves property
    placeholders such as ${my.worker.name}, as taskQueues already does.
  • Workflow.sleep(Duration, TimerOptions) and Workflow.await(Duration, TimerOptions, Supplier) let workflows set a
    summary on the timer behind a sleep or a timed await, like Workflow.newTimer(Duration, TimerOptions) already does.
  • Add nonblocking Async.await overloads whose promises complete when a workflow condition becomes true or a timeout expires.
  • Workflow tasks taking longer than 5 seconds now log a [TMPRL1104] warning reporting the task duration and the
    external storage downloads and uploads that contributed to it. The threshold is configurable with the
    TEMPORAL_WORKFLOW_TASK_DURATION_WARN_SECONDS environment variable.
  • Nexus operation handlers now forward inbound callback links to the workflows and signals they start, instead of
    dropping them.
  • Nexus handlers now propagate NexusSerializationContext to the workflows, workflow updates, and
    standalone activities they start. These use it only for their results and failures, which are
    returned to the Nexus caller. Standalone activities also use it for their heartbeat details, which
    the server includes in their timeout failures.
    To complete such an activity asynchronously, read the context from
    ActivityInfo.getNexusSerializationContext(), store it with the task token, and pass it to
    ActivityCompletionClient.withContext(NexusSerializationContext).
  • Experimental: ActivityClient and ScheduleClient now support external storage when configured with
    ActivityClientOptions.Builder.setExternalStorage or ScheduleClientOptions.Builder.setExternalStorage.
  • Experimental: StorageDriverStoreContext and StorageDriverSelectContext now have getNamespace(), returning
    the namespace of the client or worker performing the store.

Changed

  • Experimental: The S3 storage driver now writes payloads stored without a workflow or activity target under
    v0/ns/{namespace}/d/sha256/{hash}, using the namespace of the storing client or worker (null when it is
    unknown), instead of v0/d/sha256/{hash}. Existing objects remain retrievable.
  • Experimental: signal and signalWithStart called from a @TemporalOperation handler now reuse the
    operation's request ID, so a retried Nexus task no longer delivers the same signal twice. Signals sent from other
    Nexus operation handlers keep an independent request ID per call and are not deduplicated.
  • Moved the Spring AI integration to temporalio/ai-integrations.
    io.temporal:temporal-spring-ai now publishes a one-time relocation POM to io.temporal:spring-ai:0.1.0;
    the integration is versioned independently of the SDK. The standalone release requires Java 17+, Spring AI 2,
    Spring Boot 4, and Temporal Java SDK 1.40.0+. Spring AI 1 / Spring Boot 3 applications should remain on
    io.temporal:temporal-spring-ai:1.40.x until they migrate. Existing Spring AI 1 workflow histories are not
    replay-compatible; complete those executions or use separate worker deployments.
  • Release notes for all future releases are now in a single CHANGELOG.md file. releases directory with old release
    notes is kept for historical reference.
  • Added versioned scheduling for asynchronous Temporal stub calls. When enabled, switching between a stub method
    reference such as Async.function(activities::first) and an equivalent lambda such as
    Async.function(() -> activities.first()) preserves command order during replay. The call runs on a workflow thread,
    so workflow outbound interceptors can wait while scheduling it. The flag remains disabled by default, and existing
    unflagged histories retain their previous behavior.
  • TemporalDevServer, TemporalDevServerOptions, TestWorkflowEnvironment.startLocal, and the useDevServer methods
    of TestWorkflowRule and TestWorkflowExtension are no longer marked experimental. TemporalDevServerOptions remain
    specific to the Temporal CLI dev server implementation and may no longer be valid if that implementation changes.

Fixed

  • Skipped Workflow.mutableSideEffect calls made with the new recovery flag enabled no longer
    leave invalid marker commands after cache eviction or a worker restart. The flag remains disabled
    by default in this release to preserve replay compatibility during SDK rollout.
  • RetryOptions.merge now accepts partially configured policies, preserving unset initial intervals
    and backoff coefficients until validation or annotation merging supplies them.
  • Fixed workflow task completion pagination, which threw UnsupportedOperationException before
    sending the first page. A completion that needed pagination timed out on every attempt instead
    of being sent. The same fix lets RpcRetryOptions.newBuilder(options).addDoNotRetry(...) extend
    existing options, which also threw UnsupportedOperationException.
  • RpcRetryOptions no longer changes when the builder that created it is reused. Previously,
    addDoNotRetry calls made after build() or validateBuildWithDefaults() also appeared in
    the options already built.
  • Schedule action headers are now preserved when describing and updating a schedule.
  • ActivityClient now sends the temporal-namespace gRPC header like WorkflowClient and ScheduleClient do,
    so standalone activity calls are no longer rejected with PERMISSION_DENIED by namespace-scoped auth (e.g.
    Temporal Cloud API keys).
  • The Java 8 entry of Jackson3JsonPayloadConverter in the multi-release jar now declares the same public API as the
    Java 17 class, including the JsonMapper constructor and newDefaultJsonMapper(boolean). Tools that compile against
    the base entry, such as IntelliJ's build system, no longer reject new Jackson3JsonPayloadConverter(mapper).
  • Kotlin Async method references compiled with Kotlin 2.4 now retain their inline behavior,
    preventing NonDeterministicException when replaying workflows started with Kotlin 2.2. For
    workflows already started with Kotlin 2.4 and SDK 1.40 or earlier, set the
    temporal.kotlin.disableStaticAdapterUnwrapping JVM system property to preserve the previous
    behavior during replay.
  • Test server now honors retry expiration deadlines that fall exactly on a whole second. Previously such deadlines were
    ignored and retries were scheduled past them instead of failing with RETRY_STATE_TIMEOUT.
  • Worker heartbeats now list each plugin name once. Previously a plugin registered on both the
    WorkflowClient and the WorkerFactory was listed twice.
  • Activity workers now report activity_schedule_to_start_latency once per activity task, measured up to the time the
    worker receives the task. Previously each task reported it twice, once with the activity type and workflow type tags,
    and measured it up to the server start time.

Don't miss a new sdk-java release

NewReleases is sending notifications on new releases.