Package io.axoniq.framework.workflow.dsl.base

Class BaseWorkflowContext

java.lang.Object
io.axoniq.framework.workflow.runtime.execution.AbstractWorkflowContext
io.axoniq.framework.workflow.dsl.base.BaseWorkflowContext
All Implemented Interfaces:
WorkflowContext
Direct Known Subclasses:
SimpleWorkflowContext
public class BaseWorkflowContext extends AbstractWorkflowContext
Base Java DSL entry point for defining workflow steps.

This context exposes the core primitives used by workflow authors: executing external work, waiting for events, mutating workflow payload, publishing events, sleeping, failing, and cancelling. Non-blocking methods return a WorkflowStepResult that can be awaited later, while methods prefixed with await block until the step completes or fails.

Since:
5.4.0
Author:
Simon Zambrovski, Stefan Dragisic, Allrad Buijze, Steven van Beelen

  • Constructor Details

    • BaseWorkflowContext

      public BaseWorkflowContext(String workflowId, Map<String,@Nullable Object> payload, ProcessingContext processingContext, WorkflowConfiguration<?> workflowConfiguration)
      Creates a workflow context for a single workflow instance.

      Applications normally obtain this context from the runtime through a WorkflowDefinition callback instead of constructing it directly.

      Parameters:
      workflowId - unique identifier of the workflow instance
      payload - initial workflow payload
      processingContext - processing context for the current message
      workflowConfiguration - runtime configuration for this workflow

  • Method Details

    • equalsTo

      @Deprecated(since="0.2.0", forRemoval=true) public static Associations.Matcher equalsTo(Object value)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use EventAssociationsUtils.equalsTo(Object) instead.
      Creates a matcher that requires an event association value to equal the given value.
      Parameters:
      value - expected association value
      Returns:
      matcher that can be used when building event conditions

    • payloadProperty

      @Deprecated(since="0.2.0", forRemoval=true) public static ValueRetriever payloadProperty(String propertyName)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use EventAssociationsUtils.payloadProperty(String) instead.
      Creates a payload-property association source for the simple association DSL.
      Parameters:
      propertyName - payload property name
      Returns:
      payload-property retriever

    • metadataProperty

      @Deprecated(since="0.2.0", forRemoval=true) public static ValueRetriever metadataProperty(String propertyName)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use EventAssociationsUtils.metadataProperty(String) instead.
      Creates a metadata-property association source for the simple association DSL.
      Parameters:
      propertyName - metadata key
      Returns:
      metadata-property retriever

    • apply

      public static <T> T apply(T stepDefinition, UnaryOperator<T> customizer)
      Applies a customizer to a step definition after checking both arguments for null. Further customization is possible using the provided customizer unary operator.
      Type Parameters:
      T - concrete step definition type
      Parameters:
      stepDefinition - definition to customize
      customizer - function that mutates or replaces the definition
      Returns:
      customized step definition

    • execute

      public WorkflowStepResult execute(String stepName, Map<String,@Nullable Object> inputPayload, PayloadProcessor processor, UnaryOperator<ExecuteStepDefinition> customizer)
      Starts an execute step that invokes the given payload processor.

      The step is scheduled immediately and returns a handle that can be awaited later. Use the inputPayload to provide step-local input in addition to the current workflow payload. Further customization is possible using the provided customizer unary operator.

      Parameters:
      stepName - logical name of the step
      inputPayload - step-specific input values
      processor - function that performs the step work
      customizer - customizer for timeout, mapping, retries, or metadata
      Returns:
      handle for the running step

    • execute

      public WorkflowStepResult execute(String stepName, Map<String,@Nullable Object> inputPayload, PayloadProcessor processor)
      Starts an execute step with the default step definition settings.
      Parameters:
      stepName - logical name of the step
      inputPayload - step-specific input values
      processor - function that performs the step work
      Returns:
      handle for the running step

    • awaitExecute

      public Map<String,@Nullable Object> awaitExecute(String stepName, Map<String,@Nullable Object> inputPayload, PayloadProcessor processor, UnaryOperator<ExecuteStepDefinition> customizer)
      Starts an execute step and blocks until it completes. Further customization is possible using the provided customizer unary operator.
      Parameters:
      stepName - logical name of the step
      inputPayload - step-specific input values
      processor - function that performs the step work
      customizer - customizer for timeout, mapping, retries, or metadata
      Returns:
      payload produced by the completed step
      See Also:

    • awaitExecute

      public Map<String,@Nullable Object> awaitExecute(String stepName, Map<String,@Nullable Object> inputPayload, PayloadProcessor processor)
      Starts an execute step with default settings and blocks until it completes.
      Parameters:
      stepName - logical name of the step
      inputPayload - step-specific input values
      processor - function that performs the step work
      Returns:
      payload produced by the completed step
      See Also:

    • waitForEvent

      public WorkflowStepResult waitForEvent(String stepName, EventCondition eventCondition, UnaryOperator<WaitForStepDefinition> customizer)
      Starts a wait-for step that completes when a matching event is observed. Further customization is possible using the provided customizer unary operator.
      Parameters:
      stepName - logical name of the waiting step
      eventCondition - event selection criteria
      customizer - customizer for timeout, mapping, or metadata
      Returns:
      handle for the waiting step

    • waitForEvent

      public WorkflowStepResult waitForEvent(String stepName, EventCondition eventCondition)
      Starts a wait-for step with default settings.
      Parameters:
      stepName - logical name of the waiting step
      eventCondition - event selection criteria
      Returns:
      handle for the waiting step

    • awaitEvent

      public Map<String,@Nullable Object> awaitEvent(String stepName, EventCondition eventCondition, UnaryOperator<WaitForStepDefinition> customizer)
      Starts a wait-for step and blocks until a matching event arrives. Further customization is possible using the provided customizer unary operator.
      Parameters:
      stepName - logical name of the waiting step
      eventCondition - event selection criteria
      customizer - customizer for timeout, mapping, or metadata
      Returns:
      payload extracted from the matching event
      See Also:

    • awaitEvent

      public Map<String,@Nullable Object> awaitEvent(String stepName, EventCondition eventCondition)
      Starts a wait-for step with default settings and blocks until a matching event arrives.
      Parameters:
      stepName - logical name of the waiting step
      eventCondition - event selection criteria
      Returns:
      payload extracted from the matching event
      See Also:

    • sleep

      public WorkflowStepResult sleep(String stepName, UnaryOperator<WaitForStepDefinition> customizer)
      Starts a sleep step. Further customization is possible using the provided customizer unary operator.

      The actual delay is usually configured through the supplied customizer by setting a timeout on the step definition.

      Parameters:
      stepName - logical name of the sleep step
      customizer - customizer that typically sets the timeout
      Returns:
      handle for the sleeping step

    • awaitSleep

      public void awaitSleep(String stepName, UnaryOperator<WaitForStepDefinition> customizer)
      Starts a sleep step and blocks until the timeout expires. Further customization is possible using the provided customizer unary operator.
      Parameters:
      stepName - logical name of the sleep step
      customizer - customizer that typically sets the timeout
      See Also:

    • modifyPayload

      public WorkflowStepResult modifyPayload(String stepName, PayloadModification modification, UnaryOperator<PayloadStepDefinition> customizer)
      Starts a step that updates the workflow payload. Further customization is possible using the provided customizer unary operator.
      Parameters:
      stepName - logical name of the payload update step
      modification - transformation to apply to the current payload
      customizer - customizer for step metadata
      Returns:
      handle for the payload update step

    • modifyPayload

      public WorkflowStepResult modifyPayload(String stepName, PayloadModification modification)
      Starts a payload update step with default settings.
      Parameters:
      stepName - logical name of the payload update step
      modification - transformation to apply to the current payload
      Returns:
      handle for the payload update step

    • migrateVersion

      public boolean migrateVersion(String changeId, String newVersion, UnaryOperator<VersionStepDefinition> customizer)
      Migrates this workflow to newVersion for changeId and returns whether the new branch is in effect:
      • Already recorded for this changeId → returns true iff the recorded version is >= newVersion.
      • Not recorded but workflow already at newVersion → returns true without publishing a redundant step.
      • Not recorded and newVersion strictly greater → publishes a migration step and returns true; if the replay-drift guard fires (in-flight workflow ran past this point under old code), returns false.
      Downgrades (requested < current, no recorded step) raise IllegalArgumentException. Call at most once per changeId per workflow body.

      Use it to fork workflow logic safely: 

      
 if (ctx.migrateVersion("payment-redesign", "0.0.2")) {
     ctx.awaitExecute("processPayment", PaymentService::processV2);
 } else {
     ctx.awaitExecute("chargePayment", PaymentService::chargeV1);
 }
      Parameters:
      changeId - developer-chosen identifier describing the change.
      newVersion - new workflow version to record (semver string, e.g. "0.0.2").
      customizer - customizer for the version step definition (e.g. event name customizer).
      Returns:
      true if the workflow is at (or past) newVersion for this changeId; false if it stays on the legacy branch.

    • migrateVersion

      public boolean migrateVersion(String changeId, String newVersion)
      Migrates this workflow to newVersion for changeId with default settings (default event-name customizer).
      Parameters:
      changeId - developer-chosen identifier describing the change.
      newVersion - new workflow version to record (semver string, e.g. "0.0.2").
      Returns:
      true if the workflow is at (or past) newVersion for this changeId.
      See Also:

    • awaitModifyPayload

      public void awaitModifyPayload(String stepName, PayloadModification modification, UnaryOperator<PayloadStepDefinition> customizer)
      Updates the workflow payload and blocks until the change has been applied. Further customization is possible using the provided customizer unary operator.
      Parameters:
      stepName - logical name of the payload update step
      modification - transformation to apply to the current payload
      customizer - customizer for step metadata
      See Also:

    • awaitModifyPayload

      public void awaitModifyPayload(String stepName, PayloadModification modification)
      Updates the workflow payload with default settings and blocks until the change has been applied.
      Parameters:
      stepName - logical name of the payload update step
      modification - transformation to apply to the current payload
      See Also:

    • publish

      public WorkflowStepResult publish(String stepName, EventMessage event, UnaryOperator<PublishStepDefinition> customizer)
      Publishes a business event as a durable workflow step and returns a handle to await later. Further customization is possible using the provided customizer unary operator.

      Exactly one event is appended: the given event enriched with workflow metadata (workflowId, stepName, stepType, stepPrimitive). Its type, payload, identifier and timestamp are published as-is, so the event other handlers and workflows receive is the event you publish. The workflow payload is not modified. On replay the step is found in the workflow state and nothing is published again.

      Parameters:
      stepName - logical name of the publish step
      event - event to publish
      customizer - customizer for the publish step definition
      Returns:
      handle for the publish step

    • awaitPublish

      public void awaitPublish(String stepName, EventMessage event, UnaryOperator<PublishStepDefinition> customizer)
      Publishes a business event as a durable workflow step and blocks until the step is recorded. Further customization is possible using the provided customizer unary operator.
      Parameters:
      stepName - logical name of the publish step
      event - event to publish
      customizer - customizer for the publish step definition
      See Also:

    • fail

      public void fail(Throwable cause, UnaryOperator<FailWorkflowDefinition> customizer)
      Fails the workflow and publishes the configured failure event. Further customization is possible using the provided customizer unary operator.
      Parameters:
      cause - reason the workflow should fail
      customizer - customizer for failure metadata

    • fail

      public void fail(Throwable cause)
      Fails the workflow using the default failure step definition.
      Parameters:
      cause - reason the workflow should fail

    • cancel

      public void cancel(UnaryOperator<CancelWorkflowDefinition> customizer)
      Cancels the workflow and publishes the configured cancellation event. Further customization is possible using the provided customizer unary operator.
      Parameters:
      customizer - customizer for cancellation metadata and cause

    • cancel

      public void cancel()
      Cancels the workflow using the default cancellation step definition.

    • cancelStep

      public void cancelStep(String stepName, UnaryOperator<CancelStepDefinition> customizer)
      Cancels a single running step without terminating the workflow. Further customization is possible using the provided customizer unary operator.
      Parameters:
      stepName - name of the step to cancel
      customizer - customizer for cancellation metadata and cause

    • cancelStep

      public void cancelStep(String stepName)
      Cancels a single running step using the default step cancellation definition.
      Parameters:
      stepName - name of the step to cancel

    • defaultExecuteStepDefinition

      @Internal public ExecuteStepDefinition defaultExecuteStepDefinition(String stepName, Map<String,@Nullable Object> inputPayload, PayloadProcessor processor)
      Creates the default execute step definition used by the convenience overloads in this class.
      Parameters:
      stepName - logical name of the step
      inputPayload - step-specific input values
      processor - function that performs the step work
      Returns:
      default execute step definition

    • defaultWaitForStepDefinition

      @Internal public WaitForStepDefinition defaultWaitForStepDefinition(String stepName, EventCondition eventCondition)
      Creates the default wait-for step definition used by the convenience overloads in this class.
      Parameters:
      stepName - logical name of the waiting step
      eventCondition - event selection criteria
      Returns:
      default wait-for step definition

    • defaultPayloadStepDefinition

      @Internal public PayloadStepDefinition defaultPayloadStepDefinition(String stepName, PayloadModification modification)
      Creates the default payload modification step definition used by the convenience overloads in this class.
      Parameters:
      stepName - logical name of the payload update step
      modification - transformation to apply to the current payload
      Returns:
      default payload step definition

    • defaultPublishStepDefinition

      @Internal public PublishStepDefinition defaultPublishStepDefinition(String stepName, EventMessage event)
      Creates the default publish step definition used by the publish(String, EventMessage, UnaryOperator) convenience overloads.
      Parameters:
      stepName - logical name of the publish step
      event - event to publish
      Returns:
      default publish step definition

    • defaultMigrateVersionStepDefinition

      protected VersionStepDefinition defaultMigrateVersionStepDefinition(String changeId, String newVersion)
      Creates the default version step definition used by the migrateVersion(String, String, UnaryOperator) convenience overloads.
      Parameters:
      changeId - developer-chosen identifier describing the change.
      newVersion - new workflow version to record (semver string).
      Returns:
      default version step definition.

    • defaultFailWorkflowDefinition

      @Internal public FailWorkflowDefinition defaultFailWorkflowDefinition()
      Creates the default workflow failure definition.
      Returns:
      default fail step definition

    • defaultCancelWorkflowDefinition

      @Internal public CancelWorkflowDefinition defaultCancelWorkflowDefinition()
      Creates the default workflow cancellation definition.
      Returns:
      default cancel workflow definition

    • defaultCancelStepDefinition

      @Internal public CancelStepDefinition defaultCancelStepDefinition(String stepName)
      Creates the default single-step cancellation definition.
      Parameters:
      stepName - name of the step to cancel
      Returns:
      default cancel step definition

    • resolve

      protected QualifiedName resolve(Class<?> messageType)
      Resolves the qualified message name for the given message type.
      Parameters:
      messageType - event or command class to resolve
      Returns:
      qualified name for the provided class

    • setDefaultTimeout

      public void setDefaultTimeout(Duration defaultTimeout)
      Sets the timeout applied to newly created execute and wait-for step definitions unless a step-specific customizer overrides it.
      Parameters:
      defaultTimeout - default timeout for newly created steps

    • defaultTimeout

      public Duration defaultTimeout()
      Returns the timeout currently applied to newly created step definitions.
      Returns:
      default timeout for newly created steps

    • setDefaultRetryPolicy

      public void setDefaultRetryPolicy(RetryPolicy defaultRetryPolicy)
      Sets the retry policy applied to newly created execute step definitions unless a customizer overrides it.
      Parameters:
      defaultRetryPolicy - default retry policy for execute steps

    • defaultRetryPolicy

      public RetryPolicy defaultRetryPolicy()
      Returns the retry policy currently applied to newly created execute step definitions.
      Returns:
      default retry policy for execute steps