Stand alone operations for Nexus by Evanthx · Pull Request #2872 · temporalio/sdk-java

Evanthx · 2026-05-07T22:53:21Z

What was changed

Why?

Checklist

Closes
How was this tested:

Any docs updates needed?

Quinn-With-Two-Ns · 2026-05-08T11:24:09Z

+  <T> NexusServiceClient<T> newNexusServiceClient(Class<T> serviceInterface, String endpoint);
+
+  /** Start a new standalone Nexus operation execution. */
+  StartNexusOperationExecutionOutput startNexusOperationExecution(


This method should not be on the NexusClient

Quinn-With-Two-Ns · 2026-05-08T11:25:46Z

+      StartNexusOperationExecutionInput input);
+
+  /** List standalone Nexus operation executions matching a query. */
+  ListNexusOperationExecutionsOutput listNexusOperationExecutions(


Client should not be returning interceptor types here, Look at other clients like https://github.com/temporalio/sdk-java/blob/master/temporal-sdk/src/main/java/io/temporal/client/ActivityClient.java#L37

Quinn-With-Two-Ns · 2026-05-08T11:25:54Z

+  ListNexusOperationExecutionsOutput listNexusOperationExecutions(
+      ListNexusOperationExecutionsInput input);
+
+  /** Count standalone Nexus operation executions matching a query. */


Same as https://github.com/temporalio/sdk-java/pull/2872/changes#r3208326494

Quinn-With-Two-Ns · 2026-05-08T11:27:15Z

+ * NexusClientHandle}; obtain a handle via {@link #getHandle}.
+ */
+@Experimental
+public interface NexusClient {


All the methods here should have full Javadocs , see https://github.com/temporalio/sdk-java/blob/master/temporal-sdk/src/main/java/io/temporal/client/ActivityClient.java as an example

Quinn-With-Two-Ns · 2026-05-08T11:29:43Z

+ * type binding to an {@link UntypedNexusClientHandle} (returned by {@link
+ * NexusClient#getHandle(String)}) by calling one of the {@link #fromUntyped} factories.
+ */
+public interface NexusClientHandle<R> extends UntypedNexusClientHandle {


Suggested change

public interface NexusClientHandle<R> extends UntypedNexusClientHandle {

public interface NexusOperationHandle<R> extends UntypedNexusOperationHandle {

Please keep consistent naming with other Handles like https://github.com/temporalio/sdk-java/blob/master/temporal-sdk/src/main/java/io/temporal/client/ActivityHandle.java

Quinn-With-Two-Ns · 2026-05-08T11:30:04Z

+import java.util.concurrent.TimeoutException;
+import javax.annotation.Nullable;
+
+public interface UntypedNexusClientHandle {


Same as https://github.com/temporalio/sdk-java/pull/2872/changes#r3208344747

Quinn-With-Two-Ns · 2026-05-08T11:31:03Z

+
+  void terminate(@Nullable String reason);
+
+  void delete();


Delete shouldn't be included here

Quinn-With-Two-Ns · 2026-05-08T11:33:35Z

+   * List operation executions whose service matches the service this client targets. Any
+   * user-supplied query is ANDed with a {@code Service="..."} filter.
+   */
+  ListNexusOperationExecutionsOutput listNexusOperationExecutions(


Listing should be on the NexusClient client not the service client, it is strictly for stating operations, pleas remove

Quinn-With-Two-Ns · 2026-05-08T11:33:45Z

+   * Count operation executions whose service matches the service this client targets. Any
+   * user-supplied query is ANDed with a {@code Service="..."} filter.
+   */
+  CountNexusOperationExecutionsOutput countNexusOperationExecutions(


Same as https://github.com/temporalio/sdk-java/pull/2872/changes#r3208363703

Quinn-With-Two-Ns · 2026-05-08T11:37:03Z

+    private final String endpoint;
+    private final String service;
+    private final String operation;
+    private final @Nullable Duration scheduleToCloseTimeout;


Don't need to duplicate all the options in NexusClientOperationOptions see ActivityClientCallsInterceptor

Quinn-With-Two-Ns · 2026-05-08T11:37:17Z

+import java.util.List;
+import javax.annotation.Nullable;
+
+public class NexusClientOperationOptions {


Quinn-With-Two-Ns · 2026-05-08T11:38:16Z

 import java.util.Objects;

 /**
- * NexusOperationOptions is used to specify the options for starting a Nexus operation from a


This shouldn't be renamed

Quinn-With-Two-Ns · 2026-05-08T11:40:13Z

+   * Async variant of {@link #start(BiFunction, Object)}. Returns a {@link CompletableFuture} that
+   * completes with the typed handle once the start RPC has acknowledged the operation.
+   */
+  <U, R> CompletableFuture<NexusClientHandle<R>> startAsync(BiFunction<T, U, R> operation, U input);


These variants are not part of proposed API, please remove not every API should have an async variant

Quinn-With-Two-Ns · 2026-05-08T11:46:52Z

+  @Override
+  public <U, R> java.util.concurrent.CompletableFuture<R> executeAsync(
+      BiFunction<T, U, R> operation, U input, NexusOperationOptions options) {
+    return startAsync(operation, input, options).thenCompose(NexusClientHandle::getResultAsync);


Look at how executeAsync is implemented on ActivityClient

Quinn-With-Two-Ns · 2026-05-08T11:50:09Z

+  @Override
+  public <U, R> NexusClientHandle<R> start(
+      BiFunction<T, U, R> operation, U input, NexusOperationOptions options) {
+    OperationCapture<R> capture = captureOperation(operation, input);


Look at how stand alone activities code and the newly added https://github.com/temporalio/sdk-java/blob/master/temporal-sdk/src/main/java/io/temporal/internal/util/MethodExtractor.java we should reuse the utility and not re-implment the same logic

Quinn-With-Two-Ns · 2026-05-08T11:51:16Z

  public void applyOnConflictOptions(@Nonnull StartWorkflowExecutionRequest request) {
    update(
        ctx -> {
-          OnConflictOptions options = request.getOnConflictOptions();


Unnecessary change

Quinn-With-Two-Ns · 2026-05-08T11:53:26Z

+            .build());
+  }
+
+  private Endpoint createEndpoint(String name) {


You shouldn't need to create endpoint or delete them per test, the SDKTestWorkflowRule already creates the endpoint for you, this applies to multiple test files from what I can tell

Quinn-With-Two-Ns · 2026-05-08T11:54:44Z

+          .setTestTimeoutSeconds(120)
+          .build();
+
+  private NexusClient createNexusClient() {


I see multiple tests already need this, I would consider moving it to the SDKTestWorkflowRule

Quinn-With-Two-Ns · 2026-05-08T11:55:36Z

+      SDKTestWorkflowRule.newBuilder()
+          .setWorkflowTypes(NexusClientTest.PlaceholderWorkflowImpl.class)
+          .setNexusServiceImplementation(new TestNexusServiceImpl())
+          // Default is 10s; standalone Nexus dispatch + worker poll can take longer.


It shouldn't take over 120s , the default timeout should be fine since we use the same timeout for in workflow nexus operations

Quinn-With-Two-Ns · 2026-05-08T11:58:06Z

+ * NexusClient#getHandle(String)}: {@code describe()}, {@code cancel()}/{@code cancel(reason)}, and
+ * {@code terminate()}/{@code terminate(reason)}.
+ */
+public class NexusClientHandleTest {


This applies to all your tests, but since the time skipping test server doesn't support stand alone nexus operations you need to skip these tests if we are using the time skipping test server using assumeTrue(SDKTestWorkflowRule.useExternalService) on each test file

Quinn-With-Two-Ns · 2026-05-08T12:02:17Z

+  private final DataConverter dataConverter;
+  private final @Nullable SearchAttributes searchAttributes;
+  private final @Nullable String summary;
+  private final @Nullable NexusOperationIdReusePolicy idReusePolicy;


The options here are not correct, searchAttributes, summary, idReusePolicy, idReusePolicy should be on the per operation options

Quinn-With-Two-Ns · 2026-05-08T12:02:39Z

+import java.util.Collections;
+import java.util.List;
+import javax.annotation.Nullable;
+


Name should be NexusClientOptions

Quinn-With-Two-Ns · 2026-05-08T12:04:37Z

+
+import io.temporal.common.Experimental;
+import io.temporal.serviceclient.WorkflowServiceStubs;
+import io.temporal.workflow.NexusOperationOptions;


We should not be reusing the workflow NexusOperationOptions here, nothing in workflow should really be mentioned outside that package. See how stand alone activities redefined StartActivityOptions

Quinn-With-Two-Ns · 2026-05-08T12:13:05Z

+ * proto requests and delegates the actual gRPC calls to {@link GenericWorkflowClient}.
+ */
+@Experimental
+public class RootNexusClientInvoker implements NexusClientCallsInterceptor {


I believe you are missing Identity here, it should be set on most requests.

Quinn-With-Two-Ns · 2026-05-08T12:14:41Z

+      @Nonnull DescribeNexusOperationExecutionRequest request, @Nonnull Deadline deadline);

-  // ---- Standalone Activity RPCs ----
+  CompletableFuture<DescribeNexusOperationExecutionResponse> describeNexusOperationExecutionAsync(


I think we can remove describeNexusOperationExecutionAsync we should only have APIs here that are actually used by the high level clients/handles

Quinn-With-Two-Ns · 2026-05-08T13:16:49Z

Reviewed most of the public API, didn't get to into the tests or implementation for now since some stuff will likely change.

Evanthx added 13 commits April 28, 2026 15:41

Progress checkin

4ad65fb

Progress checkin

60d8581

Merge remote-tracking branch 'refs/remotes/origin/sano' into sano

6776443

Added RootNexusClientInvoker

85eab3d

Adding a test

1e493f0

Progress checkin

0052e5e

Adding unit tests

8f49ebc

Progress checkin

bc30456

Progress

7cca96f

Progress checkin

7b65472

Moved some files

2d75278

Typo fix

c479493

Added a few checks

c773e26

Evanthx requested a review from a team as a code owner May 7, 2026 22:53

Quinn-With-Two-Ns reviewed May 8, 2026

View reviewed changes

	public interface NexusClientHandle<R> extends UntypedNexusClientHandle {
	public interface NexusOperationHandle<R> extends UntypedNexusOperationHandle {

Conversation

Evanthx commented May 7, 2026

What was changed

Why?

Checklist

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 May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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 commented May 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Quinn-With-Two-Ns May 8, 2026 •

edited

Loading