Package io.axoniq.framework.workflow.runtime.execution

Interface WorkflowConfigurationRegistry<W extends WorkflowConfigurationRegistry<W>>

Type Parameters:
W - type of the registry.
All Superinterfaces:
DescribableComponent
All Known Implementing Classes:
SimpleWorkflowConfigurationRegistry
public interface WorkflowConfigurationRegistry<W extends WorkflowConfigurationRegistry<W>> extends DescribableComponent
Registry for holding workflow configurations with corresponding start conditions.
Since:
5.4.0
Author:
Simon Zambrovski

  • Field Details

  • Method Details

    • resolveOrFallback

      static WorkflowConfiguration<?> resolveOrFallback(ProcessingContext ctx, String workflowName, String workflowId, String stateVersion, WorkflowConfiguration<?> startConfig)
      Convenience helper that resolves the WorkflowConfiguration for an in-flight workflow's body against the registry stashed on the given ProcessingContext (see RESOURCE_KEY). When the registry is unavailable (e.g. tests that wire the execution directly without one), logs a [registry-missing] routing line and falls back to startConfig.

    • register

      default W register(QualifiedName qualifiedName, WorkflowConfiguration<?> workflowConfiguration)

    • register

      W register(EventCondition eventCondition, WorkflowConfiguration<?> workflowConfiguration)

    • supportedEvents

      Set<QualifiedName> supportedEvents()

    • getWorkflowsConfigurations

      List<WorkflowConfigurationRegistry.PredicatedWorkflowConfiguration> getWorkflowsConfigurations(QualifiedName qualifiedName)

    • getHighestVersionConfigurations

      default List<WorkflowConfigurationRegistry.PredicatedWorkflowConfiguration> getHighestVersionConfigurations(MessageType type)
      Returns the configurations registered for the given event type whose WorkflowConfiguration.workflowVersion() is the highest among all registrations (semver-ordered). Multiple configurations may be returned if duplicates exist at that version (run-in-parallel semantics).

      This is the lookup event-driven callers use, so the event's type reaches the registry whole. It is currently decided on MessageType.qualifiedName() alone, and taking the full type keeps MessageType.version() in reach for when it participates in the decision.

    • getHighestVersionConfigurations

      default List<WorkflowConfigurationRegistry.PredicatedWorkflowConfiguration> getHighestVersionConfigurations(QualifiedName qualifiedName)
      Returns the configurations registered for qualifiedName whose WorkflowConfiguration.workflowVersion() is the highest among all registrations (semver-ordered). Multiple configurations may be returned if duplicates exist at that version (run-in-parallel semantics).

      Event-driven callers should use getHighestVersionConfigurations(MessageType); this variant serves registration-time recomputation, where only a QualifiedName exists.

    • getByVersion

      default Optional<WorkflowConfiguration<?>> getByVersion(QualifiedName qualifiedName, String version)
      Returns the configuration registered for qualifiedName whose WorkflowConfiguration.workflowVersion() equals version (semver-equal). If multiple are registered at that version, returns the first.

    • findByWorkflowNameAndVersion

      default Optional<WorkflowConfiguration<?>> findByWorkflowNameAndVersion(String workflowName, String version)
      Finds a registered configuration by workflowName + version across all qualified names. Used to route an in-flight workflow's execution to the definition matching the version it was started under (as read from state, which sourced it from the started event's MessageType.version()).
      Parameters:
      workflowName - name of the workflow (matches WorkflowConfiguration.workflowName()).
      version - semver version string to match against WorkflowConfiguration.workflowVersion().
      Returns:
      matching configuration, or empty if none registered.

    • getWorkflowConfiguration

      default Optional<WorkflowConfiguration<?>> getWorkflowConfiguration(VersionedType workflowDefinitionId)
      Finds a registered configuration by workflow definition reference.
      Parameters:
      workflowDefinitionId - workflow definition reference to resolve
      Returns:
      matching configuration, or empty if none registered

    • findClosestRegisteredVersion

      default Optional<WorkflowConfiguration<?>> findClosestRegisteredVersion(String workflowName, String version)
      Finds the "best routing match" for a given workflowName + version: the registered configuration whose workflowVersion() is the highest version less than or equal to the requested version (semver-ordered). Used to dispatch a workflow whose state version was bumped mid-flight via ctx.migrateVersion(...) to a value that no exact sibling is registered for - e.g. v1.0.0 + v2.0.0 registered, state recorded "1.0.1", we want to route to the v1.0.0 definition, not jump to v2.0.0.

      Returns empty when no registered version is <= the requested one (the workflow's recorded version is older than anything currently registered).

      Parameters:
      workflowName - name of the workflow.
      version - semver state version to route against.
      Returns:
      the closest matching configuration, or empty if none qualifies.

    • findClosestHigherRegisteredVersion

      default Optional<WorkflowConfiguration<?>> findClosestHigherRegisteredVersion(String workflowName, String version)
      Finds the "next higher" routing match for workflowName + version: the registered configuration whose workflowVersion() is the lowest version strictly greater than the requested version (semver-ordered). Used to route an in-flight workflow forward to a newer definition when the developer bumped @Workflow(workflowVersion=...) past the version recorded in the workflow's state - e.g. instances started at "0.0.1" before the annotation was bumped to "0.0.2" must still find a body to replay against.

      Returns empty when no registered version is > the requested one.

      Parameters:
      workflowName - name of the workflow.
      version - semver state version to route against.
      Returns:
      the closest matching higher configuration, or empty if none qualifies.

    • warnAboutSameVersionDuplicates

      default void warnAboutSameVersionDuplicates()
      Emits a single startup warning per qualified name when multiple workflow definitions are registered at the same highest version. Same-version duplicates run in parallel only if their workflowIdProviders produce distinct ids; otherwise the second start is rejected as a duplicate. Intended to be called once when the engine transitions to live mode.

    • registeredVersions

      default List<String> registeredVersions(String workflowName)
      Returns all workflow versions registered under workflowName in semver ascending order. Used for routing-decision logs.

    • resolveDefinitionForReplay

      default WorkflowConfiguration<?> resolveDefinitionForReplay(String workflowName, String workflowId, String stateVersion, WorkflowConfiguration<?> startConfig)
      Resolves which WorkflowConfiguration should drive an in-flight workflow's body, picking the definition that matches the version recorded in state. Five-pass routing:
      1. exact-match-start-config - start config matches state version.
      2. exact-match-sibling - registry has a sibling at the exact state version.
      3. closest-sibling - highest registered version ≤ state (covers mid-flight ctx.migrateVersion() bumps to a value not statically registered).
      4. closest-higher-sibling - lowest registered version > state (covers the case where @Workflow(workflowVersion=...) has been bumped past the version recorded on the workflow's started event; in-flight instances still find a body to replay).
      5. no-match-fallback - nothing registered for this workflow name. WARN + start config; the drift safety net pauses if step names diverge.
      Unparseable state versions (legacy streams) short-circuit to the start config. Every dispatch decision is logged at INFO; the fallback path logs at WARN.