Standalone Activities for Java by GregoryTravis · Pull Request #2858 · temporalio/sdk-java

GregoryTravis · 2026-04-22T14:29:16Z

Add standalone activity API (ActivityClient)

Introduces support for standalone activities — activities that execute independently of any workflow.

New public API surface:

ActivityClient — top-level client for starting, describing,
listing, counting, cancelling, and terminating standalone activities
ActivityHandle<R> / UntypedActivityHandle — typed and untyped
handles returned by ActivityClient.start(); provide getResult(),
getResultAsync(), describe(), cancel(), and terminate()
StartActivityOptions — builder-based options for starting an
activity (id, task queue, timeouts, retry, priority, etc.)
ActivityClientOptions — namespace / data converter / interceptor
configuration for ActivityClient
ActivityExecutionDescription — rich descriptor returned by
describe() and list*(); extends ActivityExecutionMetadata
ActivityExecutionMetadata — lightweight metadata used in list
results
ActivityExecutionCount — result of countActivities()
ActivityListOptions / ActivityListPaginatedOptions — filtering
and pagination options for list operations
ActivityListPage — page of results with continuation token
ActivityAlreadyStartedException — thrown when a duplicate activity
id is rejected by the server
ActivityFailedException — thrown from getResult() when the
activity fails

New interceptor API:

ActivityClientCallsInterceptor — per-call interceptor for all
ActivityClient operations
ActivityClientCallsInterceptorBase — pass-through base
implementation (delegates every method to the next interceptor)
ActivityClientInterceptor — factory interceptor that wraps the
client-level invoker
ActivityClientInterceptorBase — no-op base implementation

ActivityInfo additions:

getActivityRunId() — run-scoped id assigned by the server to each
activity execution
isWorkflowActivity() — distinguishes workflow-dispatched activities
from standalone ones

ActivityCompletionClient additions:

New overloads taking (String activityId, Optional<String> runId, …)
for completing, failing, sending heartbeats, and cancelling standalone
activities without a workflow id

ActivitySerializationContext fix:

workflowId and workflowType are now @Nullable; removed
requireNonNull guards that caused NPEs for standalone activities

Functions.java:

Added Func and VFunc (zero-arg typed/void functional interfaces)
needed by ActivityClient.start() method-reference overloads

CI:

Enable standalone-activity server feature flags in the Temporal CLI
dev server used by unit tests:
frontend.activityAPIsEnabled, activity.enableStandalone,
history.enableChasm, history.enableTransitionHistory

Tests:

StandaloneActivityTest — integration tests against a real server
covering the full activity lifecycle (start, poll, complete, cancel,
terminate, describe, list, heartbeat, async completion)
ActivityClientCallsInterceptorBaseTest — delegation tests for the
base interceptor
ActivityClientCallsInterceptorChainTest — chain ordering tests
ActivityHandleImplTest — unit tests for handle dispatch
ActivityCompletionClientImplTest — unit tests for completion client
ActivityInfoStandaloneTest — unit tests for ActivityInfo in the
standalone context
ActivitySerializationContextTest — confirms nullable workflow fields
StartActivityOptionsTest, ActivityClientOptionsTest,
ActivityExecutionDescriptionTest, ActivityExecutionMetadataTest,
ActivityAlreadyStartedExceptionTest — options and value-type tests

Remove isEmpty() check from isWorkflowActivity.

…nse.

This reverts commit 381e66c.

GregoryTravis · 2026-04-23T18:35:06Z

+
+  @Override
+  public <R> CompletableFuture<R> getResultAsync(Class<R> resultClass, @Nullable Type resultType) {
+    return CompletableFuture.supplyAsync(() -> getResult(resultClass, resultType));


Do we want to set up a separate Executor for this?

We probably do. I think you might need to do something similar to what happens in the workflow client for getting results (and we probably also want overloads that you can give timeouts to, like it has).

@Quinn-With-Two-Ns I'm sure would be able to say something much more intelligent than me about this. I'd ask him.

We also probably want to cache results here rather than re-polling. Looks like the other SDKs are doing that.

Yeah we shouldn't just be calling getResult in supplyAsync , look at how getResultAsync on WorkflowStubImpl works you need to wire the async down to the GRPC layer

and yeah if we cahced results in other SDK's we should here as well

Sushisource

Overall looking pretty good to me! I didn't review the tests (it's a long one!). Just a few things to address (and we'll want more than my stamp).

Sushisource · 2026-04-23T23:57:02Z

+   * {@code captured[0]} when any method is called on it.
+   */
+  @SuppressWarnings("unchecked")
+  private static <I> I createTypeProbe(Class<I> activityInterface, Method[] captured) {


Why is captured an array here? Seems like only one value can ever be written? I guess this is just a workaround for needing some wrapper type, but I wonder if there's something more explicit for that purpose.

Seems like AtomicReference is the standard approach, but I think that has as semantic connotation I don't want to give, so I'm just adding a Box.

Got rid of Box and moved all the logic to MethodExtractor, to reduce boilerplate here.

Sushisource · 2026-04-24T00:05:50Z

+    } catch (Throwable ignored) {
+    }
+    UntypedActivityHandle untyped =
+        start(extractActivityType(activityInterface, captured[0]), options, new Object[0]);


It seems like, in general with these createTypeProbe call sites, we could be doing error handling a bit more robustly. If they pass a method reference that doesn't exist on the class, for example, what kind of error are we gonna throw here?

Will we just end up with an NPE from dereffing captured[0]? We want to provide at least some kind of reasonable user-facing error in that case.

Moved the logic into MethodExtractor, which throws an information RTE if the method doesn't match the activity.

Sushisource · 2026-04-24T00:48:25Z

+ * ActivityHandle#describe()}.
+ */
+@Experimental
+public final class ActivityExecutionDescription extends ActivityExecutionMetadata {


This guy is missing lastFailure() which exists in the other SDKs. Probably also good to expose the raw info too, which I think we typically do?

Sushisource · 2026-04-24T00:56:57Z

+
+  @Override
+  public <R> CompletableFuture<R> getResultAsync(Class<R> resultClass, @Nullable Type resultType) {
+    return CompletableFuture.supplyAsync(() -> getResult(resultClass, resultType));


We probably do. I think you might need to do something similar to what happens in the workflow client for getting results (and we probably also want overloads that you can give timeouts to, like it has).

@Quinn-With-Two-Ns I'm sure would be able to say something much more intelligent than me about this. I'd ask him.

Sushisource · 2026-04-24T00:57:36Z

+
+  @Override
+  public <R> CompletableFuture<R> getResultAsync(Class<R> resultClass, @Nullable Type resultType) {
+    return CompletableFuture.supplyAsync(() -> getResult(resultClass, resultType));


We also probably want to cache results here rather than re-polling. Looks like the other SDKs are doing that.

Sushisource · 2026-04-24T01:01:21Z

+  }
+
+  @Override
+  public DescribeActivityOutput describeActivity(DescribeActivityInput input) {


I think this will need to support the long poll token, which probably also means the describe() on the handle needs an overload to take one too

I thought the SDK wasn't/didn't need to expose the long poll token

Bleh, I forgot that. I was just going on what existed in Go/Python. We can probably leave it out then.

Quinn-With-Two-Ns · 2026-04-24T22:50:55Z

+  /**
+   * Starts a standalone activity using a typed interface and an unbound method reference, and
+   * returns a typed handle. The activity type name is inferred from the method reference at runtime
+   * via a reflection proxy; the result type is captured from the generic type parameter.


Suggested change

* via a reflection proxy; the result type is captured from the generic type parameter.

IMO this is just an implementation detail, I don't think the average user would benefit from that info and might even confuse them since a "reflection proxy" isn't a standard term. The only argument I could see is for GRAAL users, since they do need to know that.

Quinn-With-Two-Ns · 2026-04-24T22:52:09Z

+   *
+   * <p>Example:
+   *
+   * <pre>{@code


nit: I like the examples a lot, but I would make 2 small changes. I would add one for each overload, or ask AI to write them, and have just one example per method.

Quinn-With-Two-Ns · 2026-04-24T22:53:23Z

+   * @param options pagination options such as page size
+   * @return a page of results and a token for the next page
+   */
+  ActivityListPage listExecutionsPaginated(


I don't think we need to expose this? We didn't for other list methods.

Quinn-With-Two-Ns · 2026-04-24T22:54:53Z

+      A2 arg2,
+      A3 arg3)
+      throws ActivityAlreadyStartedException {
+    Method method = MethodExtractor.extract(activityInterface, activity);


@Evanthx FYI your SANO code could copy this pattern.

Quinn-With-Two-Ns · 2026-04-24T22:57:04Z

+   */
+  <I> ActivityHandle<Void> start(
+      Class<I> activityInterface, Functions.Proc1<I> activity, StartActivityOptions options)
+      throws ActivityAlreadyStartedException;


Suggested change

throws ActivityAlreadyStartedException;

Generally the Java SDK does NOT used checked exceptions. I think we should be consistent with other client calls.

Quinn-With-Two-Ns · 2026-04-24T22:58:54Z

+ * StartActivityOptions#getIdConflictPolicy()}).
+ */
+@Experimental
+public final class ActivityAlreadyStartedException extends TemporalException {


For WorkflowExecutionAlreadyStarted we inherit from WorkflowExecution I don't see anything equivalent in this PR.

Quinn-With-Two-Ns · 2026-04-24T22:59:25Z

+   * @param resultType the generic type to use for deserialization; may be {@code null}
+   * @throws ActivityFailedException if the activity failed, timed out, or was cancelled
+   */
+  <R> R getResult(Class<R> resultClass, @Nullable Type resultType) throws ActivityFailedException;


Suggested change

<R> R getResult(Class<R> resultClass, @Nullable Type resultType) throws ActivityFailedException;

<R> R getResult(Class<R> resultClass, @Nullable Type resultType);

Same comment as above about checked exception

Quinn-With-Two-Ns · 2026-04-24T23:00:04Z

+ * cancelled. The original cause can be retrieved via {@link #getCause()}.
+ */
+@Experimental
+public final class ActivityFailedException extends TemporalException {


I think we are missing a common ActivityException base class here that ActivityFailedException and ActivityAlreadyStartedException

Quinn-With-Two-Ns · 2026-04-24T23:00:53Z

+@Experimental
+public interface ActivityClientCallsInterceptor {
+
+  StartActivityOutput startActivity(StartActivityInput input)


nit: we should have Java docs for these. I know some interceptors don't but that is more tech debt then intentional IMO.

Quinn-With-Two-Ns · 2026-04-24T23:04:17Z

+ * ActivityHandle#fromUntyped(UntypedActivityHandle, Class)} or {@link
+ * ActivityHandle#fromUntyped(UntypedActivityHandle, Class, Type)}.
+ */
+final class ActivityHandleWrapper<R> implements ActivityHandle<R> {


Suggested change

final class ActivityHandleWrapper<R> implements ActivityHandle<R> {

final class ActivityHandleImpl<R> implements ActivityHandle<R> {

Was there a reason we used a fifferent naming convention then other classes?

Quinn-With-Two-Ns · 2026-04-24T23:10:20Z

+   * @param resultClass the class to deserialize the result into
+   * @param resultType the generic type to use for deserialization; may be {@code null}
+   */
+  <R> CompletableFuture<R> getResultAsync(Class<R> resultClass, @Nullable Type resultType);


We are missing the timeour overloads for getResultAsync on WorkflowStub

Quinn-With-Two-Ns

I didn't review the test or check more subtle behaviour, overall I think it looks really good! The MethodExtractor was a good idea. A few changes that if I owned the Java SDK I would want changed is:

Mirror the exception hierarchy with WorkflowException
Mirror the getResultAsync overloads in WorkflowStub
Remove the use of checked exceptions, they are not used in the Java SDK like this
Mirror the implementation of getResultAsync from WorkflowStub. getResultAsync should not but be calling getResult in an executor it should flow down to an async gRPC call.

GregoryTravis added 30 commits April 10, 2026 16:14

vc

b4abb30

Integration tests.

d87dbc5

Options .toBuilder() should duplicate 'this'.

40ad564

equals and hashCode for StartActivityOptions

64f5cc9

Only throw ActivityAlreadyStartedException if error detail is present

8c40020

Same for getActivityResult

6794e92

equals/hashcode/tostring for ActivityExecution

d26c527

Remove isEmpty() check from isWorkflowActivity.

use-api-design

6dd4263

match fully

aa4bcf3

More tests

5859bf0

Rename ActivityExecution to ActivityExecutionMetadata.

b4a27a0

Store ActivityExecutionInfo instead of DescribeActivityExecutionRespo…

511f1c1

…nse.

Rename getRetryPolicy to getRetryOptions.

d3ec5c3

Missing methods in ActivityExecutionDescription.

416be5a

Correct naming for interceptor interfaces.

ee1f4df

Update ActivityInfo interface.

282765f

More tests.

262d63d

Tests for standalone completion client methods.

74b48bf

Interceptor tests.

2324e6d

Nullable fields.

8863baf

swap args

d8bf835

Rename IsInWorkflow to IsWorkflowActivity.

2fc4bae

Merge branch 'master' into gmt/java-standalone-activities

007de18

Test: contextPropagatorValueAppearsInStartActivityHeader.

381e66c

Revert "Test: contextPropagatorValueAppearsInStartActivityHeader."

ba898ef

This reverts commit 381e66c.

ActivityClientInterceptor and ActivityClientInterceptorBase.

133770e

Correct order for activity interceptors.

a801751

Rename to initializeClientInvoker.

f10f46f

Javadoc warnings, unused classes, a deprecated method.

44875e3

Remove runtime rethrow.

0ea7377

GregoryTravis added 5 commits April 23, 2026 11:09

Enable SAA in test server.

a2647fc

Remove trivial tests.

0906641

wip

af94c2b

Rename to ActivityClientCallsInterceptorBaseTest.

2076001

Non-mocked completion client tests.

ffd9f71

GregoryTravis changed the title ~~Gmt/java standalone activities~~ Standalone Activities for Java Apr 23, 2026

Tweak javadoc

0068b55

GregoryTravis commented Apr 23, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/client/StartActivityOptions.java

GregoryTravis marked this pull request as ready for review April 23, 2026 18:36

GregoryTravis requested a review from a team as a code owner April 23, 2026 18:36

Sushisource reviewed Apr 24, 2026

View reviewed changes

GregoryTravis added 6 commits April 24, 2026 12:18

Box for capturing

5a839d6

Box for capturing

cd6aa3e

MethodExtractor

e92cef8

All overloads of same

f7ebe1f

Refactor ME

62e9c3b

.start() pulls headers from context propagators.

d4bf5b1

Quinn-With-Two-Ns reviewed Apr 24, 2026

View reviewed changes

Quinn-With-Two-Ns requested changes Apr 24, 2026

View reviewed changes

	<R> R getResult(Class<R> resultClass, @Nullable Type resultType) throws ActivityFailedException;
	<R> R getResult(Class<R> resultClass, @Nullable Type resultType);

	final class ActivityHandleWrapper<R> implements ActivityHandle<R> {
	final class ActivityHandleImpl<R> implements ActivityHandle<R> {

Conversation

GregoryTravis commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Sushisource left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Quinn-With-Two-Ns left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

GregoryTravis commented Apr 22, 2026 •

edited

Loading