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.

Construction is lazy and performs no network I/O. Every network method requires Server protocol 4. The first network call reads the Server protocol and caches a compatible result. An older Server causes IllegalStateException on that call and on every later call. A Server that requires a newer protocol than this SDK supports causes the same error. A failure to reach the Server during that check throws DexServiceException, as any request does. The next call retries the check. The check counts against the call's request timeout and gRPC Context deadline.

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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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 the Dex Server does not support protocol version 4
      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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      Throws:
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • getAttributes

      public AttributeValues getAttributes(String flowId, AttributeRead<?>... reads)
      Reads committed Attribute and AttributeMap instance values from the current or latest Flow run.

      Use getAttributes to read Flow state from outside the Flow without defining an RPC. Pass one read per value: a singleton Attribute, or an AttributeMap instance selected with AttributeMap.instance(String). To read one value, pass a single read. The returned AttributeValues maps each read to an Optional of its typed value. An unset Attribute or AttributeMap instance reads as Optional.empty().

      The Client sends all keys in one FlowService request, so every value comes from the same committed state. No Worker runs, so the call works while no Worker is available. The read targets the current run, or the latest run when no run is open. A closed run stays readable until Dex purges it. The call sees only committed state. It does not see writes that a running Step or RPC has not committed yet. An Attribute read inside an RPC handler, by contrast, also sees that RPC's own uncommitted writes.

      Hard-delete Attributes from Attribute.hardDeleteOnNull() and AttributeMap.hardDeleteOnNull() are supported. Dex returns their current committed values, and a deleted value reads as Optional.empty(). The Client loads large values through LoadBlobs and its BlobCache, then decodes every value with its definition's value class and the Client's ObjectMapper. The call returns only after every value decodes. On any error it throws and returns no values.

      Every definition must be registered by some Flow in this Client's Registry. Registered means the exact definition object that the Flow's Flow.getPersistenceSchema() returns. Another object with the same name is rejected, even when its value class is the same. A definition created by calling hardDeleteOnNull() again is also another object. The definition need not belong to the target Flow's type, because Dex reads each key by name. A same-named Attribute with an incompatible value class in the target Flow fails to decode. 

      final class OrderFlow implements Flow<Void> {
    final Attribute<String> orderStatus = Attribute.define("order-status", String.class);
    final AttributeMap<Note> notes = AttributeMap.define("notes", Note.class);

    @Override
    public PersistenceSchema getPersistenceSchema() {
        return PersistenceSchema.of(orderStatus, notes);
    }
}

OrderFlow orderFlow = new OrderFlow();
try (Client client = new Client(
        new Registry(Collections.<Flow<?>>singletonList(orderFlow)), blobCache)) {
    AttributeValues values = client.getAttributes(
            "order-42",
            orderFlow.orderStatus,
            orderFlow.notes.instance("n1"));
    String status = values.get(orderFlow.orderStatus).orElse("new");
    Optional<Note> note = values.get(orderFlow.notes.instance("n1"));
} catch (FlowNotFoundException missing) {
    log.info("order-42 does not exist");
}
      Parameters:
      flowId - the non-blank Flow ID
      reads - at least one Attribute or AttributeMapInstance; two reads of the same Attribute or AttributeMap instance are rejected
      Returns:
      the decoded values, with one entry for every read
      Throws:
      IllegalArgumentException - before any request when flowId is blank, no read is passed, a read is null or is not an Attribute or AttributeMapInstance, or two reads select the same physical key
      FlowDefinitionException - before any request when a definition is not registered by a Flow in the Client's Registry, or differs from the registered definition object
      FlowNotFoundException - when the Flow does not exist or its latest run is being purged, including when Dex purges it between the read and the LoadBlobs request
      ValueMappingException - when a stored value cannot be loaded or decoded as its definition's value class
      IllegalStateException - when Dex returns an unexpected key, a duplicate key, or a key without a value, or if the Dex Server does not support protocol version 4
      DexServiceException - for other FlowService failures, including a failed LoadBlobs request; the exception keeps the gRPC code and Dex sub-status, and both its message and its detail start with the call context, such as getAttributes Flow order-42 Attributes order-status, before the Server detail

    • getAttributes

      public AttributeValues getAttributes(String flowId, List<? extends AttributeRead<?>> reads)
      Reads committed values for a list of Attribute and AttributeMap instance reads.

      This overload behaves exactly like getAttributes(String, AttributeRead...). Use it when the reads are assembled at runtime. The list is copied before the request, so later changes to it do not affect the call. 

      List<AttributeRead<?>> reads = new ArrayList<AttributeRead<?>>();
reads.add(orderFlow.orderStatus);
for (String noteId : noteIds) {
    reads.add(orderFlow.notes.instance(noteId));
}
AttributeValues values = client.getAttributes("order-42", reads);
      Parameters:
      flowId - the non-blank Flow ID
      reads - at least one Attribute or AttributeMapInstance; two reads of the same Attribute or AttributeMap instance are rejected
      Returns:
      the decoded values, with one entry for every read
      Throws:
      IllegalArgumentException - before any request when flowId is blank, reads is null or empty, a read is null or is not an Attribute or AttributeMapInstance, or two reads select the same physical key
      FlowDefinitionException - before any request when a definition is not registered by a Flow in the Client's Registry, or differs from the registered definition object
      FlowNotFoundException - when the Flow does not exist or its latest run is being purged, including when Dex purges it between the read and the LoadBlobs request
      ValueMappingException - when a stored value cannot be loaded or decoded as its definition's value class
      IllegalStateException - when Dex returns an unexpected key, a duplicate key, or a key without a value, or if the Dex Server does not support protocol version 4
      DexServiceException - for other FlowService failures, including a failed LoadBlobs request; both its message and its detail start with the call context

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      Throws:
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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
      IllegalStateException - if the Dex Server does not support protocol version 4

    • 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