Interface Context

public interface Context
Exposes invocation metadata and durable state operations to Step and RPC code.

A context belongs to one worker invocation and must not be retained or used from another thread after the method returns. Attribute and Channel helpers are also available directly on their typed definitions; the context methods are useful for framework-style code. Values passed with a Class must use concrete, non-parameterized types. Wrap a parameterized value in a concrete holder class, or use an array such as String[] instead of List<String>. 

public StepDecision execute(Context context, Order input) {
    int attempt = context.getAttempt();
    status.set(context, "processed-on-attempt-" + attempt);
    context.recordEvent("order-processed", input, Order.class);
    return StepDecision.gracefulComplete();
}

  • Method Details

    • getFlowId

      String getFlowId()
      Returns the Flow ID for the current invocation.
      Returns:
      the Flow ID

    • getRunId

      String getRunId()
      Returns the current Flow run ID.
      Returns:
      the run ID

    • getFlowStartedAt

      Instant getFlowStartedAt()
      Returns when the current Flow execution started.
      Returns:
      the Flow start timestamp

    • getStepExecutionId

      String getStepExecutionId()
      Returns the server-assigned identifier of the current Step execution.
      Returns:
      the Step execution ID

    • getFromStepExecutionId

      String getFromStepExecutionId()
      Returns the Step execution that scheduled the current Step.
      Returns:
      the originating Step execution ID, or an empty value when none exists

    • getRecoveryError

      RecoveryErrorInfo getRecoveryError()
      Returns the previous Step method failure that caused this recovery invocation.

      For wait-for recovery, execute receives the failed wait-for method's final error. For an execute recovery Step, both wait-for and execute receive the failed execute method's final error. A recovery Step whose own wait-for fails receives that newer failure in execute.

      Returns:
      the recovery error, or null for a normal Step or RPC invocation

    • getFirstAttemptAt

      Instant getFirstAttemptAt()
      Returns when the first attempt of the current method began.
      Returns:
      the first-attempt timestamp

    • getAttempt

      int getAttempt()
      Returns the one-based attempt number of the current method invocation.
      Returns:
      the current attempt number

    • isCancellationRequested

      boolean isCancellationRequested()
      Reports whether Dex requested cancellation of the current Step execution.

      When cancellation reaches the Java Worker, Dex cancels the handler task and interrupts its thread. Blocking handlers should return when they receive InterruptedException. CPU-bound or batch-oriented handlers may check this method at natural work boundaries; they do not need to poll continuously. Neither thread interruption nor this method makes external side effects atomic. Use timeouts, idempotency, or compensation when required.

      Returns:
      true after cancellation is requested or the handler thread is interrupted

    • hasTimerFired

      boolean hasTimerFired()
      Reports whether any timer condition in the current wait has fired.
      Returns:
      true when at least one timer fired

    • hasTimerFired

      boolean hasTimerFired(int index)
      Reports whether the timer at a specific condition index fired.
      Parameters:
      index - the zero-based timer condition index
      Returns:
      true when that timer fired

    • waitForMethodFailed

      boolean waitForMethodFailed()
      Reports whether execute is running after a failed wait-for method.

      This can be true only when the Step uses WaitForFailurePolicy.PROCEED.

      Returns:
      true when wait-for retries were exhausted before execute

    • recordHeartbeat

      void recordHeartbeat(Object value)
      Sends a best-effort heartbeat for the current Step method or Flow timeout attempt.

      Dex persists a nonnull value with the activity heartbeat and supplies it to a later attempt through getLastHeartbeatValue(Class). Passing null sends a heartbeat without details, clearing any value previously reported during the current attempt. A Stream write also acts as a heartbeat and preserves the most recently reported details. Heartbeats are ignored while an asynchronous Step runs as a local activity. This method sends directly on the invocation's response stream and must be called only from the handler thread. 

      public StepDecision execute(Context context, Batch input) {
    for (int index = 0; index < input.items().size(); index++) {
        process(input.items().get(index));
        context.recordHeartbeat(index + 1);
    }
    return StepDecision.gracefulComplete();
}
      Parameters:
      value - the checkpoint to persist, or null to send no heartbeat details
      Throws:
      IllegalStateException - if called from an RPC
      io.grpc.StatusRuntimeException - if the invocation is canceled or transport fails
      ValueMappingException - if a nonnull value cannot be encoded

    • hasLastHeartbeatValue

      boolean hasLastHeartbeatValue()
      Reports whether Dex restored heartbeat details from an earlier attempt.
      Returns:
      true when getLastHeartbeatValue(Class) can decode a restored value

    • getLastHeartbeatValue

      <T> T getLastHeartbeatValue(Class<T> valueType)
      Decodes heartbeat details restored from an earlier attempt.

      Call hasLastHeartbeatValue() to distinguish an absent checkpoint. Values passed with a Class must use concrete, non-parameterized types.

      Type Parameters:
      T - the checkpoint type
      Parameters:
      valueType - the concrete Java class used to decode the checkpoint
      Returns:
      the decoded checkpoint, or null when no checkpoint was restored
      Throws:
      ValueMappingException - if the value cannot be decoded

    • setStepExecutionLocal

      <T> void setStepExecutionLocal(String key, T value, Class<T> valueType)
      Stores a value scoped to the current Step execution.

      Step-execution locals allow Step.waitFor(Context, I) to pass durable data to Step.execute(Context, I) for the same execution.

      Type Parameters:
      T - the local value type
      Parameters:
      key - the local value key
      value - the value to serialize
      valueType - the concrete Java value class

    • getStepExecutionLocal

      <T> T getStepExecutionLocal(String key, Class<T> valueType)
      Reads a value scoped to the current Step execution.
      Type Parameters:
      T - the local value type
      Parameters:
      key - the local value key
      valueType - the concrete Java class used to decode the value
      Returns:
      the decoded value, or null when the key is absent

    • recordEvent

      <T> void recordEvent(String name, T value, Class<T> valueType)
      Appends a named user event to the Flow execution history.
      Type Parameters:
      T - the event payload type
      Parameters:
      name - the event name
      value - the event payload
      valueType - the concrete Java payload class

    • getAttribute

      <T> T getAttribute(Attribute<T> attribute)
      Reads an Attribute.
      Type Parameters:
      T - the Attribute value type
      Parameters:
      attribute - the registered typed Attribute
      Returns:
      the current value, or null when absent

    • getAttribute

      <T> T getAttribute(AttributeMap<T> attribute, String instance)
      Reads one Attribute-map instance.
      Type Parameters:
      T - the Attribute value type
      Parameters:
      attribute - the registered typed Attribute map
      instance - the map instance
      Returns:
      the current value, or null when absent

    • setAttribute

      <T> void setAttribute(Attribute<T> attribute, T value)
      Writes an Attribute.
      Type Parameters:
      T - the Attribute value type
      Parameters:
      attribute - the registered typed Attribute
      value - the value to persist

    • setAttribute

      <T> void setAttribute(AttributeMap<T> attribute, String instance, T value)
      Writes one Attribute-map instance.
      Type Parameters:
      T - the Attribute value type
      Parameters:
      attribute - the registered typed Attribute map
      instance - the map instance
      value - the value to persist

    • deleteAttribute

      void deleteAttribute(Attribute<?> attribute)
      Deletes an Attribute.
      Parameters:
      attribute - the registered Attribute

    • deleteAttribute

      void deleteAttribute(AttributeMap<?> attribute, String instance)
      Deletes one Attribute-map instance.
      Parameters:
      attribute - the registered Attribute map
      instance - the map instance

    • publish

      <T> void publish(Channel<T> channel, T value)
      Publishes one message to a Channel.
      Type Parameters:
      T - the Channel message type
      Parameters:
      channel - the registered typed Channel
      value - the message value

    • publish

      <T> void publish(ChannelMap<T> channel, String instance, T value)
      Publishes one message to a Channel-map instance.
      Type Parameters:
      T - the Channel message type
      Parameters:
      channel - the registered typed Channel map
      instance - the map instance
      value - the message value

    • deleteChannelMessage

      void deleteChannelMessage(Channel<?> channel, String messageId)
      Stages deletion of one pending singleton Channel message from an RPC.
      Parameters:
      channel - the registered singleton Channel
      messageId - the nonblank server-assigned message ID

    • deleteChannelMessage

      void deleteChannelMessage(ChannelMap<?> channel, String instance, String messageId)
      Stages deletion of one pending Channel-map message from an RPC.
      Parameters:
      channel - the registered Channel map
      instance - the nonblank Channel-map instance
      messageId - the nonblank server-assigned message ID

    • channelSize

      int channelSize(Channel<?> channel)
      Returns the visible message count for a Channel.
      Parameters:
      channel - the registered Channel
      Returns:
      the visible message count

    • channelSize

      int channelSize(ChannelMap<?> channel, String instance)
      Returns the visible message count for one Channel-map instance.
      Parameters:
      channel - the registered Channel map
      instance - the map instance
      Returns:
      the visible message count

    • pendingChannelMessages

      <T> List<ChannelMessage<T>> pendingChannelMessages(Channel<T> channel)
      Returns a singleton Channel's loaded pending-message snapshot in FIFO order.
      Type Parameters:
      T - the Channel message type
      Parameters:
      channel - the registered typed Channel selected by invocation options
      Returns:
      immutable pending message IDs and decoded values
      Throws:
      ChannelMessagesNotLoadedException - if the invocation did not load its messages

    • pendingChannelMessages

      <T> List<ChannelMessage<T>> pendingChannelMessages(ChannelMap<T> channel, String instance)
      Returns one ChannelMap instance's loaded pending-message snapshot in FIFO order.
      Type Parameters:
      T - the Channel message type
      Parameters:
      channel - the registered typed ChannelMap selected by invocation options
      instance - the logical map instance
      Returns:
      immutable pending message IDs and decoded values
      Throws:
      ChannelMessagesNotLoadedException - if the invocation did not load its messages

    • channelResults

      <T> List<T> channelResults(Channel<T> channel)
      Returns condition results for a Channel.
      Type Parameters:
      T - the Channel message type
      Parameters:
      channel - the registered typed Channel
      Returns:
      the typed messages consumed by the satisfied condition

    • channelResults

      <T> List<T> channelResults(ChannelMap<T> channel, String instance)
      Returns condition results for one Channel-map instance.
      Type Parameters:
      T - the Channel message type
      Parameters:
      channel - the registered typed Channel map
      instance - the map instance used by the condition
      Returns:
      the typed messages consumed by the satisfied condition

    • writeStream

      <T> void writeStream(Stream<T> stream, T value)
      Appends one immediate best-effort Stream message.

      The write emits a frame on the current Step method response stream and does not wait for storage acknowledgement. Multiple writes to the same Stream are allowed. Dex may discard a message when its Stream Store is unavailable or rejects the write.

      Type Parameters:
      T - the Stream message type
      Parameters:
      stream - the Stream registered by the current Flow
      value - the typed message to append
      Throws:
      IllegalStateException - if called from an RPC
      io.grpc.StatusRuntimeException - if the invocation is canceled or transport fails
      ValueMappingException - if the value cannot be encoded