Class Client

java.lang.Object
io.superdurable.dex.Client
All Implemented Interfaces:
AutoCloseable
public final class Client extends Object implements AutoCloseable
Provides synchronous, strongly typed operations for starting and controlling Dex Flows.

All network methods block the calling thread until the gRPC request completes. Create one client for a registered set of Flow definitions and reuse it across calls; the underlying gRPC channel supports concurrent callers. The supplied BlobCache is borrowed and is not closed by the client. Service failures use typed DexServiceException subclasses. Long-poll operations can throw LongPollTimeoutException. waitForFlow(String) returns a FlowResult for every terminal status. 

Registry registry = new Registry(Collections.<Flow<?>>singletonList(orderFlow));
try (Client client = new Client(registry, blobCache)) {
    String runId = client.startFlow(orderFlow, "order-123", input);
    OrderFlow rpc = client.newRpcStub(OrderFlow.class, "order-123", runId);
    OrderStatus status = client.invokeRPC(rpc::getStatus);
    OrderOutput output = client.waitForFlow("order-123").getSingleOutput(OrderOutput.class);
}

  • Constructor Details

    • Client

      public Client(Registry registry, BlobCache blobCache)
      Creates a client using local development defaults.
      Parameters:
      registry - the nonnull registry of Flow definitions used for typed mapping
      blobCache - the nonnull cache used to hydrate blob-backed values
      Throws:
      IllegalArgumentException - if either argument is null

    • Client

      public Client(Registry registry, BlobCache blobCache, ClientOptions options)
      Creates a client with explicit connection, routing, and serialization options.
      Parameters:
      registry - the nonnull registry of Flow definitions used for typed mapping
      blobCache - the nonnull cache used to hydrate blob-backed values
      options - the nonnull client options
      Throws:
      IllegalArgumentException - if any argument is null

  • Method Details

    • startFlow

      public <I> String startFlow(Flow<I> flow, String flowId, I input)
      Starts a registered Flow using default start options.
      Type Parameters:
      I - the Flow start input type
      Parameters:
      flow - the exact Flow instance registered with this client
      flowId - the nonblank application-assigned Flow ID
      input - the typed start-Step input, or null for a Flow without a start Step
      Returns:
      the server-assigned run ID
      Throws:
      IllegalArgumentException - if the Flow is unregistered, the ID is invalid, or the input does not match the registered start Step
      FlowAlreadyStartedException - if the Flow ID conflicts with an existing execution
      DexServiceException - if Dex otherwise rejects or cannot complete the request

    • startFlow

      public <I> String startFlow(Flow<I> flow, String flowId, I input, StartFlowOptions startOptions)
      Starts a registered Flow with explicit start options.
      Type Parameters:
      I - the Flow start input type
      Parameters:
      flow - the exact Flow instance registered with this client
      flowId - the nonblank application-assigned Flow ID
      input - the typed start-Step input, or null for a Flow without a start Step
      startOptions - timeout, scheduling, initial state, routing, and idempotency settings
      Returns:
      the server-assigned run ID
      Throws:
      IllegalArgumentException - if the Flow, ID, input, or duration settings are invalid, if an initial value targets a Attribute.hardDeleteOnNull() Attribute and maps to a number or a Boolean, or if an initial Attribute's hard-delete setting differs from the definition registered for the Flow
      IllegalStateException - if an initial value targets a hard-delete Attribute and the Server does not support protocol version 3 or later, or the Server protocol cannot be negotiated
      FlowAlreadyStartedException - if the Flow ID conflicts with an existing execution
      DexServiceException - if Dex otherwise rejects or cannot complete the request

    • newRpcStub

      public <T> T newRpcStub(Class<T> rpcClass, String flowId)
      Creates a strongly typed RPC stub targeting the current run of a Flow.
      Type Parameters:
      T - the concrete Flow class
      Parameters:
      rpcClass - the non-final registered Flow class containing RPC methods
      flowId - the target Flow ID
      Returns:
      a constructor-free stub whose RPC methods perform client requests
      Throws:
      IllegalArgumentException - if the class is unregistered, final, or cannot be subclassed

    • newRpcStub

      public <T> T newRpcStub(Class<T> rpcClass, String flowId, String runId)
      Creates a strongly typed RPC stub targeting a specific Flow run.

      Dex subclasses the class with ByteBuddy and allocates the stub without invoking a constructor. RPC methods and the containing class must therefore be non-final. Kotlin classes and methods are final by default and must be declared open.

      Type Parameters:
      T - the concrete Flow class
      Parameters:
      rpcClass - the non-final registered Flow class containing RPC methods
      flowId - the target Flow ID
      runId - the target run ID, or an empty string for the current run
      Returns:
      a constructor-free typed RPC stub
      Throws:
      IllegalArgumentException - if the class is unregistered, final, or cannot be subclassed

    • invokeRPC

      public <I,O> O invokeRPC(RpcDefinitions.RpcFunc1<I,O> rpcStubMethod, I input)
      Invokes a function-style RPC with one input and returns its typed output.

      A non-transactional RPC without Attribute locks starts from a backend query. A retained terminal execution can serve the query when the handler returns no durable effects. Locks, transactional execution, returned effects, or server policy can require an active execution.

      Type Parameters:
      I - the RPC input type
      O - the RPC output type
      Parameters:
      rpcStubMethod - a direct method reference from a stub created by this client
      input - the typed RPC input
      Returns:
      the decoded RPC output
      Throws:
      FlowNotActiveOrNotFoundException - if the Flow is missing or the selected path cannot use its closed execution
      RpcLockConflictException - if the RPC cannot acquire its Attribute locks
      WorkerInvocationException - if worker code fails while executing the RPC
      DexServiceException - if Dex otherwise rejects or cannot complete the RPC

    • invokeRPC

      public <I,O> O invokeRPC(RpcDefinitions.RpcFunc1<I,O> rpcStubMethod, I input, RPCInvokeOptions invokeOptions)
      Invokes a function-style RPC with one input and runtime-selected map instances.
      Type Parameters:
      I - the RPC input type
      O - the RPC output type
      Parameters:
      rpcStubMethod - a direct method reference from a stub created by this client
      input - the typed RPC input
      invokeOptions - additive Attribute-map locks and exact map-instance loads
      Returns:
      the decoded RPC output
      Throws:
      FlowDefinitionException - if an option references a definition outside the RPC Flow
      IllegalArgumentException - if invokeOptions is null
      FlowNotActiveOrNotFoundException - if the Flow is missing or the selected path cannot use its closed execution
      RpcLockConflictException - if the RPC cannot acquire its Attribute locks
      WorkerInvocationException - if worker code fails while executing the RPC
      DexServiceException - if Dex otherwise rejects or cannot complete the RPC

    • invokeRPC

      public <O> O invokeRPC(RpcDefinitions.RpcFunc0<O> rpcStubMethod)
      Invokes a function-style RPC without application input.

      A retained terminal execution can serve a query-only RPC. Locks, transactional execution, returned effects, or server policy can require an active execution.

      Type Parameters:
      O - the RPC output type
      Parameters:
      rpcStubMethod - a direct method reference from a stub created by this client
      Returns:
      the decoded RPC output
      Throws:
      FlowNotActiveOrNotFoundException - if the Flow is missing or the selected path cannot use its closed execution
      RpcLockConflictException - if the RPC cannot acquire its Attribute locks
      WorkerInvocationException - if worker code fails while executing the RPC
      DexServiceException - if Dex otherwise rejects or cannot complete the RPC

    • invokeRPC

      public <O> O invokeRPC(RpcDefinitions.RpcFunc0<O> rpcStubMethod, RPCInvokeOptions invokeOptions)
      Invokes a function-style RPC without application input and adds map-instance selections.
      Type Parameters:
      O - the RPC output type
      Parameters:
      rpcStubMethod - a direct method reference from a stub created by this client
      invokeOptions - additive Attribute-map locks and exact map-instance loads
      Returns:
      the decoded RPC output
      Throws:
      FlowDefinitionException - if an option references a definition outside the RPC Flow
      IllegalArgumentException - if invokeOptions is null
      FlowNotActiveOrNotFoundException - if the Flow is missing or the selected path cannot use its closed execution
      RpcLockConflictException - if the RPC cannot acquire its Attribute locks
      WorkerInvocationException - if worker code fails while executing the RPC
      DexServiceException - if Dex otherwise rejects or cannot complete the RPC

    • invokeRPC

      public <I> void invokeRPC(RpcDefinitions.RpcProc1<I> rpcStubMethod, I input)
      Invokes a procedure-style RPC with one input.

      A retained terminal execution can serve a query-only RPC. Locks, transactional execution, returned effects, or server policy can require an active execution.

      Type Parameters:
      I - the RPC input type
      Parameters:
      rpcStubMethod - a direct method reference from a stub created by this client
      input - the typed RPC input
      Throws:
      FlowNotActiveOrNotFoundException - if the Flow is missing or the selected path cannot use its closed execution
      RpcLockConflictException - if the RPC cannot acquire its Attribute locks
      WorkerInvocationException - if worker code fails while executing the RPC
      DexServiceException - if Dex otherwise rejects or cannot complete the RPC

    • invokeRPC

      public <I> void invokeRPC(RpcDefinitions.RpcProc1<I> rpcStubMethod, I input, RPCInvokeOptions invokeOptions)
      Invokes a procedure-style RPC with one input and runtime-selected map instances.
      Type Parameters:
      I - the RPC input type
      Parameters:
      rpcStubMethod - a direct method reference from a stub created by this client
      input - the typed RPC input
      invokeOptions - additive Attribute-map locks and exact map-instance loads
      Throws:
      FlowDefinitionException - if an option references a definition outside the RPC Flow
      IllegalArgumentException - if invokeOptions is null
      FlowNotActiveOrNotFoundException - if the Flow is missing or the selected path cannot use its closed execution
      RpcLockConflictException - if the RPC cannot acquire its Attribute locks
      WorkerInvocationException - if worker code fails while executing the RPC
      DexServiceException - if Dex otherwise rejects or cannot complete the RPC

    • invokeRPC

      public void invokeRPC(RpcDefinitions.RpcProc0 rpcStubMethod)
      Invokes a procedure-style RPC without application input.

      A retained terminal execution can serve a query-only RPC. Locks, transactional execution, returned effects, or server policy can require an active execution.

      Parameters:
      rpcStubMethod - a direct method reference from a stub created by this client
      Throws:
      FlowNotActiveOrNotFoundException - if the Flow is missing or the selected path cannot use its closed execution
      RpcLockConflictException - if the RPC cannot acquire its Attribute locks
      WorkerInvocationException - if worker code fails while executing the RPC
      DexServiceException - if Dex otherwise rejects or cannot complete the RPC

    • invokeRPC

      public void invokeRPC(RpcDefinitions.RpcProc0 rpcStubMethod, RPCInvokeOptions invokeOptions)
      Invokes a procedure-style RPC without input and adds map-instance selections.
      Parameters:
      rpcStubMethod - a direct method reference from a stub created by this client
      invokeOptions - additive Attribute-map locks and exact map-instance loads
      Throws:
      FlowDefinitionException - if an option references a definition outside the RPC Flow
      IllegalArgumentException - if invokeOptions is null
      FlowNotActiveOrNotFoundException - if the Flow is missing or the selected path cannot use its closed execution
      RpcLockConflictException - if the RPC cannot acquire its Attribute locks
      WorkerInvocationException - if worker code fails while executing the RPC
      DexServiceException - if Dex otherwise rejects or cannot complete the RPC

    • writeStream

      public <T> void writeStream(String flowId, Stream<T> stream, String source, T value)
      Appends one typed best-effort Stream message with producer metadata.

      Each call appends a new message. The source is informational and may be reused, including by concurrent producers. A source may contain #.

      Type Parameters:
      T - the Stream message type
      Parameters:
      flowId - the logical Flow instance ID; the Flow need not exist or be active
      stream - the exact Stream registered in one Flow schema
      source - the nonblank producer description returned with the message
      value - the typed message to append
      Throws:
      FlowDefinitionException - if the Stream is not registered
      IllegalArgumentException - if the Flow ID or source is invalid
      DexServiceException - if Dex cannot append the message

    • readStream

      public <T> StreamMessage<T> readStream(String flowId, Stream<T> stream, String resumeToken)
      Blocks for the next retained Stream message using the server default wait.
      Type Parameters:
      T - the Stream message type
      Parameters:
      flowId - the logical Flow instance ID
      stream - the exact Stream registered in one Flow schema
      resumeToken - the prior token, or empty for the retained head
      Returns:
      the decoded message and resumable metadata

    • readStream

      public <T> StreamMessage<T> readStream(String flowId, Stream<T> stream, String resumeToken, Duration timeout)
      Blocks for the next retained Stream message with an explicit long-poll duration.
      Type Parameters:
      T - the Stream message type
      Parameters:
      flowId - the logical Flow instance ID
      stream - the exact Stream registered in one Flow schema
      resumeToken - the prior token, or empty for the retained head
      timeout - the nonnegative whole-second server wait, or null for its default
      Returns:
      the decoded message and resumable metadata
      Throws:
      LongPollTimeoutException - if no message arrives before the wait expires
      FlowDefinitionException - if the Stream is not registered
      DexServiceException - if Dex cannot read the Stream

    • listStreamMessages

      public <T> StreamMessagesPage<T> listStreamMessages(String flowId, Stream<T> stream, int pageSize, String beforePageToken)
      Returns one newest-first page of retained Stream messages without waiting for writes.

      An empty token starts at the retained tail. Pass the returned next-page token unchanged to read older messages. Stream trimming may remove messages between pages.

      Type Parameters:
      T - the Stream message type
      Parameters:
      flowId - the logical Flow instance ID used as the Stream instance key
      stream - the exact Stream registered in one Flow schema
      pageSize - the positive maximum count within the server-configured limit
      beforePageToken - the preceding page token, or empty for the first page
      Returns:
      decoded messages in newest-first order and the next-page token
      Throws:
      IllegalArgumentException - if pageSize is not positive
      FlowDefinitionException - if the Stream is not registered
      DexServiceException - if Dex cannot list the Stream

    • stopFlow

      public void stopFlow(String flowId)
      Cancels a running Flow without an explicit reason.
      Parameters:
      flowId - the target Flow ID
      Throws:
      FlowNotActiveOrNotFoundException - if the target Flow has no active execution
      DexServiceException - if Dex otherwise cannot stop the Flow

    • stopFlow

      public void stopFlow(String flowId, StopFlowOptions stopOptions)
      Stops a running Flow with explicit terminal behavior.
      Parameters:
      flowId - the target Flow ID
      stopOptions - the stop mode and optional reason
      Throws:
      FlowNotActiveOrNotFoundException - if the target Flow has no active execution
      DexServiceException - if Dex otherwise cannot stop the Flow

    • waitForFlow

      public FlowResult waitForFlow(String flowId)
      Blocks until a Flow reaches any terminal status.
      Parameters:
      flowId - the target Flow ID
      Returns:
      the terminal Flow result
      Throws:
      FlowNotFoundException - if no matching Flow execution exists
      DexServiceException - if Dex otherwise cannot complete the wait request

    • waitForFlow

      public FlowResult waitForFlow(String flowId, Duration timeout)
      Blocks for a bounded duration until a Flow reaches any terminal status.
      Parameters:
      flowId - the target Flow ID
      timeout - the nonnegative whole-second long-poll duration, or null for no bound
      Returns:
      the terminal Flow result
      Throws:
      LongPollTimeoutException - if timeout expires while the Flow remains running
      IllegalArgumentException - if timeout is not a supported whole-second duration
      FlowNotFoundException - if no matching Flow execution exists
      DexServiceException - if Dex otherwise cannot complete the wait request

    • describeFlow

      public FlowInfo describeFlow(String flowId)
      Returns a FlowInfo summary of the current Flow run.

      The summary contains the Flow ID, run ID, Flow type, current status, and start time. It reflects the execution when Dex handles this request; a running Flow may change afterward.

      Parameters:
      flowId - the target Flow ID
      Returns:
      the current Flow run summary
      Throws:
      FlowNotFoundException - if no matching Flow execution exists
      DexServiceException - if Dex otherwise cannot describe the Flow

    • searchFlows

      public SearchFlowsPage searchFlows(String query, int pageSize)
      Searches Flow executions and returns the first page.
      Parameters:
      query - the server search expression, or null for the default search
      pageSize - the nonnegative requested page size; zero uses the server default
      Returns:
      the first immutable search-results page
      Throws:
      IllegalArgumentException - if pageSize is negative
      DexServiceException - if Dex cannot execute the search

    • searchFlows

      public SearchFlowsPage searchFlows(String query, int pageSize, String nextPageToken)
      Searches Flow executions from a continuation token.
      Parameters:
      query - the same server search expression used for the previous page
      pageSize - the nonnegative requested page size; zero uses the server default
      nextPageToken - the prior page's token, or null for the first page
      Returns:
      an immutable search-results page
      Throws:
      IllegalArgumentException - if pageSize is negative
      DexServiceException - if Dex cannot execute the search

    • searchFlows

      public SearchFlowsPage searchFlows(String query, int pageSize, String nextPageToken, SearchFlowsOptions options)
      Searches with inclusion options.
      Parameters:
      query - filter
      pageSize - maximum
      nextPageToken - token
      options - inclusion
      Returns:
      page

    • timeTravel

      public String timeTravel(String flowId, TimeTravelOptions options)
      Creates a new run from a selected point in an existing Flow's history.
      Parameters:
      flowId - the target Flow ID
      options - the time travel point and replay behavior
      Returns:
      the server-assigned run ID of the new execution
      Throws:
      FlowNotFoundException - if no matching Flow execution exists
      DexServiceException - if Dex otherwise rejects or cannot perform time travel

    • skipTimer

      public void skipTimer(String flowId, StepExecutionId stepExecutionId, TimerId timerId)
      Makes one durable timer condition fire immediately.
      Parameters:
      flowId - the target Flow ID
      stepExecutionId - the Step execution containing the timer
      timerId - the timer selected by condition ID or index
      Throws:
      FlowNotActiveOrNotFoundException - if the target Flow has no active execution
      DexServiceException - if Dex otherwise cannot find or skip the timer

    • waitForStepCompletion

      public void waitForStepCompletion(String flowId, StepExecutionId stepExecutionId, WaitForStepCompletionOptions options)
      Blocks until a specific Step execution completes or its caller-visible request expires. The server derives a stable Request ID from the Step execution when none is supplied. Request timeout covers transparent transport reattachments. Internal handler timeout controls Temporal Update generation rollover and does not end this request.
      Parameters:
      flowId - the target Flow ID
      stepExecutionId - the Step execution to observe
      options - the Request ID override and request/handler timeout controls
      Throws:
      IllegalArgumentException - if either timeout is unsupported
      RequestTimeoutException - if a positive request timeout expires first
      FlowNotActiveOrNotFoundException - if the target Flow has no active execution
      DexServiceException - if Dex otherwise cannot complete the wait request

    • waitForAttributeMatch

      public <T> T waitForAttributeMatch(String flowId, Attribute<T> attribute, AttributeMatch<T> match, WaitForAttributeOptions options)
      Blocks until a singleton Attribute satisfies a scalar match or its request timeout expires. The server derives a stable Request ID from the condition when none is supplied. Request timeout covers transparent transport reattachments. Internal handler timeout controls Temporal Update generation rollover and does not end this request.
      Type Parameters:
      T - the Attribute value type
      Parameters:
      flowId - the target Flow ID
      attribute - the registered Attribute definition
      match - the scalar predicate to await
      options - the Request ID override and request/handler timeout controls
      Returns:
      the current Attribute value that satisfied the match
      Throws:
      IllegalArgumentException - if the budget, match operand, or operator is invalid, or if the definition uses Attribute.hardDeleteOnNull() or AttributeMap.hardDeleteOnNull()
      RequestTimeoutException - if a positive request timeout expires first
      FlowNotActiveOrNotFoundException - if the target Flow has no active execution
      DexServiceException - if Dex otherwise cannot complete the wait

    • waitForAttributeMatch

      public <T> T waitForAttributeMatch(String flowId, AttributeMap<T> attribute, String instance, AttributeMatch<T> match, WaitForAttributeOptions options)
      Blocks until an AttributeMap instance satisfies a scalar match.
      Type Parameters:
      T - the Attribute value type
      Parameters:
      flowId - the target Flow ID
      attribute - the registered Attribute-map definition
      instance - the map instance
      match - the scalar predicate to await
      options - the Request ID override and request/handler timeout controls
      Returns:
      the current AttributeMap value that satisfied the match
      Throws:
      IllegalArgumentException - if the budget, match operand, or operator is invalid, or if the definition uses Attribute.hardDeleteOnNull() or AttributeMap.hardDeleteOnNull()
      RequestTimeoutException - if a positive request timeout expires first
      FlowNotActiveOrNotFoundException - if the target Flow has no active execution
      DexServiceException - if Dex otherwise cannot complete the wait

    • updateFlowConfig

      public void updateFlowConfig(String flowId, FlowConfig config)
      Updates the supplied mutable Flow configuration fields for the current run.

      Unset fields retain their existing values. Worker routing remains unchanged.

      Parameters:
      flowId - the target Flow ID
      config - the new Flow configuration
      Throws:
      FlowNotActiveOrNotFoundException - if the target Flow has no active execution
      DexServiceException - if Dex otherwise cannot update the Flow

    • triggerContinueAsNew

      public void triggerContinueAsNew(String flowId)
      Requests that the current Flow run continue as new.
      Parameters:
      flowId - the target Flow ID
      Throws:
      FlowNotActiveOrNotFoundException - if the target Flow has no active execution
      DexServiceException - if Dex otherwise cannot apply the request

    • close

      public void close()
      Shuts down the client's gRPC channel.

      The method waits up to five seconds for channel termination and preserves interruption status. The application owns any supplied Credential and the borrowed BlobCache.

      Specified by:
      close in interface AutoCloseable