Interface NexusClient

All Known Implementing Classes:
NexusClientImpl
@Experimental public interface NexusClient
Client for managing standalone Nexus operation executions. Obtain an instance via newInstance(WorkflowServiceStubs) or newInstance(WorkflowServiceStubs, NexusClientOptions). Do not create this object per request; share it for the lifetime of the process.

Standalone Nexus operations run independently of any workflow — they are scheduled, monitored, and managed directly through this client (and the service-bound clients it produces) rather than from within a workflow execution.

To start operations, build a service-bound client and call start/execute: 


 NexusClient client = NexusClient.newInstance(stubs, options);

 // Typed: bind to an @ServiceInterface and invoke a method reference.
 NexusServiceClient<MyService> svc =
     client.newNexusServiceClient(MyService.class, "my-endpoint");
 String result = svc.execute(MyService::greet, "world");

 // Untyped: dispatch by operation name string.
 UntypedNexusServiceClient untyped =
     client.newUntypedNexusServiceClient("my-endpoint", "MyService");
 UntypedNexusOperationHandle handle = untyped.start("greet", null, "world");

To act on an existing operation (describe, cancel, terminate, get result), obtain a handle via getHandle(java.lang.String, java.lang.String): 


 NexusOperationHandle<String> handle = client.getHandle(operationId, runId, String.class);
 String result = handle.getResult();
 handle.cancel("user requested");

For visibility queries across all operations in the namespace, see listNexusOperationExecutions(java.lang.String) and countNexusOperationExecutions(java.lang.String).

See Also:

  • Method Details

    • newInstance

      static NexusClient newInstance(io.temporal.serviceclient.WorkflowServiceStubs service)
      Creates a client with default NexusClientOptions.
      Parameters:
      service - gRPC stubs connected to a Temporal Service endpoint

    • newInstance

      static NexusClient newInstance(io.temporal.serviceclient.WorkflowServiceStubs service, NexusClientOptions options)
      Creates a client with the supplied options.
      Parameters:
      service - gRPC stubs connected to a Temporal Service endpoint
      options - namespace, data converter, interceptors, and defaults applied to operations started through this client

    • getWorkflowServiceStubs

      io.temporal.serviceclient.WorkflowServiceStubs getWorkflowServiceStubs()
      Returns the underlying gRPC stubs this client routes RPCs through.

    • getHandle

      UntypedNexusOperationHandle getHandle(String operationId, @Nullable String runId)
      Returns an untyped handle to an existing operation execution, optionally pinned to a specific run.
      Parameters:
      operationId - the user-assigned operation ID
      runId - the server-assigned run ID, or null to target the latest run
      Returns:
      an untyped handle

    • getHandle

      <R> NexusOperationHandle<R> getHandle(String operationId, @Nullable String runId, Class<R> resultClass)
      Returns a typed handle to an existing operation execution, bound to resultClass.
      Type Parameters:
      R - result type
      Parameters:
      operationId - the user-assigned operation ID
      runId - the server-assigned run ID, or null to target the latest run
      resultClass - expected result type

    • getHandle

      <R> NexusOperationHandle<R> getHandle(String operationId, @Nullable String runId, Class<R> resultClass, @Nullable Type resultType)
      Returns a typed handle to an existing operation execution, bound to resultClass/ resultType. Use the resultType variant when the result is a generic type whose parameters cannot be captured by Class alone (e.g. List<String>).
      Type Parameters:
      R - result type
      Parameters:
      operationId - the user-assigned operation ID
      runId - the server-assigned run ID, or null to target the latest run
      resultClass - expected result class
      resultType - generic type for deserialization; may be null

    • newNexusServiceClient

      <T> NexusServiceClient<T> newNexusServiceClient(Class<T> service, String endpoint)
      Builds a typed service-bound client targeting the given endpoint, dispatching operations by method reference on the @ServiceInterface-annotated service. Reuses this client's stubs, options, and interceptor chain.
      Type Parameters:
      T - the service interface type
      Parameters:
      service - the @ServiceInterface-annotated service type
      endpoint - Nexus endpoint name registered on the Temporal Service

    • newUntypedNexusServiceClient

      UntypedNexusServiceClient newUntypedNexusServiceClient(String endpoint, String serviceName)
      Builds an untyped service-bound client targeting the given endpoint and service. Use this to dispatch operations by name string when no service interface is available.
      Parameters:
      endpoint - Nexus endpoint name registered on the Temporal Service
      serviceName - Nexus service name on that endpoint

    • listNexusOperationExecutions

      Stream<NexusOperationExecutionMetadata> listNexusOperationExecutions(@Nullable String query)
      Returns a stream of standalone Nexus operation executions matching the given visibility query. The stream paginates lazily over server-side results — pages are fetched on demand as the stream is consumed.
      Parameters:
      query - Temporal visibility query string, or null to return all executions in the client namespace
      Returns:
      a lazy stream of matching executions

    • countNexusOperationExecutions

      NexusOperationExecutionCount countNexusOperationExecutions(@Nullable String query)
      Returns the count of standalone Nexus operation executions matching the given visibility query, optionally with aggregation groups.
      Parameters:
      query - Temporal visibility query string, or null to count all executions in the client namespace
      Returns:
      execution count, optionally with aggregation groups when the query uses GROUP BY