Package io.axoniq.framework.workflow.dsl.api

Interface WorkflowContext

All Known Implementing Classes:
AbstractWorkflowContext, BaseWorkflowContext, SimpleWorkflowContext
public interface WorkflowContext
Author-facing DSL API based on step definitions.
Since:
5.4.0
Author:
Simon Zambrovski

  • Method Details

    • execute

      WorkflowStepResult execute(ExecuteStepDefinition stepDefinition)
      Executes a step asynchronously from a DSL step definition.

      This method is the bridge between the DSL-facing ExecuteStepDefinition and the runtime command-mode primitive. The provided step definition is translated into the corresponding runtime command and delegated to the execution layer.

      The returned WorkflowStepResult is the durable handle for the started step. Callers may inspect the state asynchronously, wait for completion explicitly, compose it with combinators, or pass it into typed resolution methods built on top of the same handle.

      Parameters:
      stepDefinition - author-facing execute step definition containing step metadata, local payload, action, payload mapping, timing, and retry configuration
      Returns:
      durable asynchronous result handle for the execution step

    • awaitExecute

      Map<String,@Nullable Object> awaitExecute(ExecuteStepDefinition stepDefinition)
      Executes a step synchronously from a DSL step definition and returns the resulting step payload.

      This is the blocking counterpart of execute(ExecuteStepDefinition). It starts the step, waits until the returned WorkflowStepResult completes, propagates any execution error, and then returns the resulting payload map. If the step completes successfully without a result payload, an empty map is returned.

      Parameters:
      stepDefinition - author-facing execute step definition containing step metadata, local payload, action, payload mapping, timing, and retry configuration
      Returns:
      resulting payload map of the completed step, or an empty map when no result payload is produced
      Throws:
      RuntimeException - any exception captured by the durable step result

    • waitForEvent

      WorkflowStepResult waitForEvent(WaitForStepDefinition stepDefinition)
      Starts an asynchronous wait step from a DSL step definition.

      This method translates the provided WaitForStepDefinition into the runtime wait command and delegates it to the execution layer. The returned WorkflowStepResult completes when a matching event is received or the configured timeout expires.

      Parameters:
      stepDefinition - author-facing wait step definition containing step metadata, event condition, payload mapping, and timing
      Returns:
      durable asynchronous result handle representing the active wait step

    • awaitEvent

      Map<String,@Nullable Object> awaitEvent(WaitForStepDefinition stepDefinition)
      Starts a wait step from a DSL step definition and blocks until it completes.

      This is the blocking counterpart of waitForEvent(WaitForStepDefinition). The method waits until the step completes, propagates any failure from the underlying WorkflowStepResult, and returns the resulting payload map. If the completed wait step has no result payload, an empty map is returned.

      Parameters:
      stepDefinition - author-facing wait step definition containing step metadata, event condition, payload mapping, and timing
      Returns:
      resulting payload map of the completed wait step, or an empty map when no result payload is produced
      Throws:
      RuntimeException - any exception captured by the durable step result

    • modifyPayload

      WorkflowStepResult modifyPayload(PayloadStepDefinition stepDefinition)
      Applies a payload modification asynchronously from a DSL step definition.

      This method bridges PayloadStepDefinition to the runtime payload modification primitive. The returned WorkflowStepResult represents the durable completion handle for the modification step.

      Parameters:
      stepDefinition - author-facing payload step definition containing step metadata and payload modification
      Returns:
      durable asynchronous result handle for the payload modification step

    • awaitModifyPayload

      void awaitModifyPayload(PayloadStepDefinition stepDefinition)
      Applies a payload modification from a DSL step definition and blocks until it completes.

      This is the blocking counterpart of modifyPayload(PayloadStepDefinition). The method waits for the returned WorkflowStepResult to complete and propagates any failure from the underlying step.

      Parameters:
      stepDefinition - author-facing payload step definition containing step metadata and payload modification
      Throws:
      RuntimeException - any exception captured by the durable step result

    • migrateVersion

      boolean migrateVersion(VersionStepDefinition stepDefinition)
      Migrates the workflow to the version carried by stepDefinition for the given changeId and returns whether the new branch is in effect for this workflow:
      • Migration step already recorded → returns true iff the recorded version is >= the requested version.
      • No step recorded yet, workflow already at the requested version → returns true without publishing a redundant step.
      • No step recorded yet, requested version strictly greater than current → publishes the migration step and returns true; if the replay-drift guard fires (in-flight workflow already ran past this point), returns false and emits nothing.
      • Downgrade attempt (requested < current, no step recorded) → throws IllegalArgumentException.
      Parameters:
      stepDefinition - author-facing version step definition.
      Returns:
      true iff the workflow has committed to (or is past) the requested version for this changeId; false if it stays on the legacy branch.

    • publish

      WorkflowStepResult publish(PublishStepDefinition stepDefinition)
      Publishes a business event as a durable workflow step from a DSL step definition.

      This method bridges PublishStepDefinition to the runtime publish primitive. Exactly one event is appended: the definition's event enriched with workflow metadata, acting as both the business event and the replay-safe checkpoint of the step. The returned WorkflowStepResult represents the durable completion handle for the publish step.

      Parameters:
      stepDefinition - author-facing publish step definition containing step metadata and the event to publish
      Returns:
      durable asynchronous result handle for the publish step

    • awaitPublish

      void awaitPublish(PublishStepDefinition stepDefinition)
      Publishes a business event from a DSL step definition and blocks until the step is recorded.

      This is the blocking counterpart of publish(PublishStepDefinition). The method waits for the returned WorkflowStepResult to complete and propagates any failure from the underlying step.

      Parameters:
      stepDefinition - author-facing publish step definition containing step metadata and the event to publish
      Throws:
      RuntimeException - any exception captured by the durable step result

    • fail

      void fail(FailWorkflowDefinition definition)
      Terminates the workflow with failure from a DSL step definition.

      The provided FailWorkflowDefinition is translated into the runtime termination command and delegated to the execution layer.

      Parameters:
      definition - author-facing failure definition containing step metadata and failure cause
      Throws:
      WorkflowFailedException - always, after the failure event is published

    • cancel

      void cancel(CancelWorkflowDefinition definition)
      Terminates the workflow with cancellation from a DSL definition.

      The provided CancelWorkflowDefinition is translated into the runtime termination command and delegated to the execution layer.

      Parameters:
      definition - author-facing cancellation definition containing step metadata and optional cause
      Throws:
      WorkflowCancelledException - always, after the cancellation event is published

    • cancelStep

      void cancelStep(CancelStepDefinition definition)
      Terminates the step with cancellation from a DSL definition.

      The provided CancelStepDefinition is translated into the runtime termination command and delegated to the execution layer.

      Parameters:
      definition - author-facing cancellation definition containing step metadata and optional cause
      Throws:
      WorkflowCancelledException - always, after the cancellation event is published

    • allMatch

      CombinatorWorkflowStepResult allMatch(Predicate<WorkflowStepResult> predicate, WorkflowStepResult... results)
      Returns a result that completes successfully when every supplied result matches the predicate.
      Parameters:
      predicate - condition each result must satisfy
      results - results to combine
      Returns:
      combined result

    • anyMatch

      CombinatorWorkflowStepResult anyMatch(Predicate<WorkflowStepResult> predicate, WorkflowStepResult... results)
      Returns a result that completes successfully when any supplied result matches the predicate.
      Parameters:
      predicate - condition a result must satisfy
      results - results to combine
      Returns:
      combined result

    • noneMatch

      CombinatorWorkflowStepResult noneMatch(Predicate<WorkflowStepResult> predicate, WorkflowStepResult... results)
      Returns a result that completes successfully when no supplied result matches the predicate.
      Parameters:
      predicate - condition no result may satisfy
      results - results to combine
      Returns:
      combined result

    • resolveComponent

      <T> T resolveComponent(Class<T> componentType)
      Resolves a component from the processing context of this workflow invocation.
      Type Parameters:
      T - type of component to resolve
      Parameters:
      componentType - type of component to resolve
      Returns:
      the resolved component
      Throws:
      ComponentNotFoundException - is component doesn't exist.

    • workflowId

      String workflowId()
      Returns the unique workflow execution identifier.
      Returns:
      workflow identifier

    • workflowDefinitionId

      VersionedType workflowDefinitionId()
      Returns the workflow definition identity, including its current definition version.

      Use VersionedType.version() to obtain the definition version.

      Returns:
      workflow definition identity

    • workflowStepNames

      List<String> workflowStepNames()
      Retrieves a list of step names in the workflow execution.
      Returns:
      list of step names

    • getStep

      @Nullable WorkflowStep getStep(String stepName)
      Retrieves a step by name.
      Parameters:
      stepName - name of the step
      Returns:
      workflow step

    • containsStep

      boolean containsStep(String stepName)
      Checks if a step with the given name exists in the workflow execution.
      Parameters:
      stepName - name of the step
      Returns:
      true if the step exists, false otherwise

    • workflowStatus

      WorkflowStatus workflowStatus()
      Returns the status of the workflow execution.
      Returns:
      workflow status

    • workflowPayload

      Map<String,@Nullable Object> workflowPayload()
      Returns the current workflow payload.
      Returns:
      the workflow payload