Skip to main content

Standalone Nexus Operations - Java SDK

SUPPORT, STABILITY, and DEPENDENCY INFO

Temporal Java SDK support for Standalone Nexus Operations is at Pre-release.

All APIs are experimental and may be subject to backwards-incompatible changes.

Standalone Nexus Operations let you run Nexus Operation Executions independently, without being orchestrated by a Workflow. Instead of calling a Nexus Operation from within a Workflow Definition using Workflow.newNexusServiceStub(), you execute a Standalone Nexus Operation directly from a Nexus service client created from a NexusClient using NexusClient.newNexusServiceClient().

Standalone Nexus Operations use the same Nexus Service contract, Operation handlers, and Worker setup as Workflow-driven Operations — only the execution path differs. See the Nexus feature guide for details on defining a Service contract, developing Operation handlers, and registering a Service in a Worker.

This page focuses on the client-side APIs that are unique to Standalone Nexus Operations:

note

This documentation uses source code from the Java Nexus Standalone sample.

Execute a Standalone Nexus Operation​

To execute a Standalone Nexus Operation, first create a NexusClient, then derive a typed NexusServiceClient from it with newNexusServiceClient(), bound to a specific Nexus Endpoint and Service. The endpoint must be pre-created on the server. Then call start() or execute() from application code (for example, a starter program), not from inside a Workflow Definition.

execute() waits for the Operation to complete and returns the result. Both methods take a StartNexusOperationOptions whose id is required — the SDK never generates one for you. scheduleToCloseTimeout is optional and defaults to the maximum allowed by the Temporal server.

NexusClient nexusClient = NexusClient.newInstance(stubs, options);
NexusServiceClient<GreetingNexusService> greetingClient =
    nexusClient.newNexusServiceClient(GreetingNexusService.class, ENDPOINT_NAME);

// Block until the operation completes and return its result.
GreetingOutput greeting =
    greetingClient.execute(
        GreetingNexusService::greet,
        new GreetingInput("World"),
        StartNexusOperationOptions.newBuilder()
            .setId("greet-" + UUID.randomUUID())
            .setScheduleToCloseTimeout(Duration.ofSeconds(10))
            .build());

executeAsync() is the same but returns a CompletableFuture instead of blocking.

CompletableFuture<GreetingOutput> future =
    greetingClient.executeAsync(
        GreetingNexusService::greet, new GreetingInput("World"), options);
GreetingOutput greeting = future.get();

See the full starter sample for a complete example that executes both synchronous and asynchronous Operations, gets their results, and lists and counts Operations.

Start a Standalone Nexus Operation and Wait for the Result​

start() returns a NexusOperationHandle. Use NexusOperationHandle.getResult() to wait until the Operation completes and retrieve its result. This works for both synchronous and asynchronous Operations.

// Start an operation and get a NexusOperationHandle.
NexusOperationHandle<GreetingOutput> handle =
    greetingClient.start(
        GreetingNexusService::startGreeting, new GreetingInput("World"), options);

// Block until the operation completes and retrieve its result.
GreetingOutput greeting = handle.getResult();

If the Operation completed successfully, the result is returned. If the Operation failed, the failure is thrown as a NexusOperationException. Use getResultAsync() for a non-blocking CompletableFuture, or getResult(long timeout, TimeUnit unit) to bound the wait.

List Standalone Nexus Operations​

Use NexusClient.listNexusOperationExecutions() to list Standalone Nexus Operation Executions that match a List Filter query. The result is a Stream of operation metadata entries.

Note that listNexusOperationExecutions() is called on a NexusClient, not on the typed NexusServiceClient.

String query = "Endpoint = \"" + ENDPOINT_NAME + "\"";
nexusClient
    .listNexusOperationExecutions(query)
    .forEach(
        op ->
            System.out.printf(
                "OperationId: %s, Operation: %s, Status: %s%n",
                op.getOperationId(), op.getOperation(), op.getStatus()));

The query parameter accepts List Filter syntax. For example, "Endpoint = 'my-endpoint' AND ExecutionStatus = 'Running'".

Count Standalone Nexus Operations​

Use NexusClient.countNexusOperationExecutions() to count Standalone Nexus Operation Executions that match a List Filter query.

Note that countNexusOperationExecutions() is called on a NexusClient, not on the typed NexusServiceClient.

String query = "Endpoint = \"" + ENDPOINT_NAME + "\"";
NexusOperationExecutionCount count = nexusClient.countNexusOperationExecutions(query);
System.out.println("Total Nexus operations: " + count.getCount());

Passing a GROUP BY query (for example, "GROUP BY ExecutionStatus") returns a count per group, available through NexusOperationExecutionCount.getGroups().

Run Standalone Nexus Operations with Temporal Cloud​

The code samples referenced on this page build their client from a ClientConfigProfile loaded from a TOML profile, so the same code works against Temporal Cloud — just point the profile at your Cloud Namespace (or override the connection via TEMPORAL_* environment variables). No code changes are needed.

For full details on connecting to Temporal Cloud, including Namespace creation, Nexus Endpoint setup, certificate generation, and authentication options, see Make Nexus calls across Namespaces in Temporal Cloud and Connect to Temporal Cloud.