Automatic transitions

An automatic edge is one the machine takes on its own. After a commit moves an entity, the entity runs its automatic chain, unless a failure route that does not continue moved it: while its state has an automatic edge, it makes an attempt, which runs the first of those edges that its guards admit. advance(entity) makes one attempt on request, for an entity whose data changed without a transition. The guards already say when an entity may go on, so the application writes no loop of its own: no list of operations to try, no rejections to ignore and no bound against a loop that never ends.

The library reports and the caller decides. What goes wrong in a chain never throws, an Error aside, to the caller whose call committed: its outcome carries the failure, the abort or the guard that stopped the chain, and the application answers with its own error or calls advance later. The examples come from the onboarding of the example module, whose tests are in OnboardingFlowTest.

Contents

Declare automatic edges

An account sets its password through an operation, and every step after that is automatic. The facade, Accounts, marks those edges on the interface:

@AccountsGraph.Transition(id = COMPLETE_INFO, from = PASSWORD_SET, to = INFO_SET, automatic = true,
        guards = AccountActionsRefs.InfoComplete.class)
@AccountsGraph.Transition(id = COMPLETE_ADDRESS, from = INFO_SET, to = ADDRESS_SET, automatic = true,
        guards = AccountActionsRefs.AddressComplete.class, action = AccountActionsRefs.VerifyAddress.class,
        recoveries = @AccountsGraph.Recovery(kind = AddressFailures.Unverifiable.class, transition = FLAG,
                continueChain = true))
@AccountsGraph.Transition(id = FLAG, from = INFO_SET, to = FLAGGED)
@AccountsGraph.Transition(id = REQUEST_REVIEW, from = FLAGGED, to = REVIEW, automatic = true)
@AccountsGraph.Transition(id = ACTIVATE_PREMIUM, from = ADDRESS_SET, to = PREMIUM, automatic = true,
        guards = AccountActionsRefs.Premium.class)
@AccountsGraph.Transition(id = ACTIVATE, from = ADDRESS_SET, to = ACTIVE, automatic = true)
@AccountsGraph.AutomaticOrder(from = ADDRESS_SET, transitions = {ACTIVATE_PREMIUM, ACTIVATE})
public interface Accounts extends Machine<Account, AccountStatus, AccountTransition> {

    @AccountsGraph.Transition(id = SET_PASSWORD, from = NEW, to = PASSWORD_SET)
    Outcome<Account, AccountStatus, AccountTransition> setPassword(Account account);

automatic = true marks the edge from every state of its from, whether the Transition is written on the interface or on an operation, which then stays callable by hand. An automatic edge needs no operation: the chain and advance take it, and an execute, a cascade or a watch rule can still request its identifier. Here the automatic edges are COMPLETE_INFO, COMPLETE_ADDRESS, REQUEST_REVIEW, ACTIVATE_PREMIUM and ACTIVATE; SET_PASSWORD, TOUCH, a self-loop, and CLOSE are operations, and FLAG is a plain failure route.

A state with one automatic edge declares nothing more. A state with two or more declares the order they are tried in, with the repeatable AutomaticOrder, which names each of them once: ADDRESS_SET tries ACTIVATE_PREMIUM before ACTIVATE. An edge without guards is admitted unless the entity is a child that no parent holds, so it comes last. The automatic edges, together with the jumps of their continuing failure routes, form no cycle, whatever allowsCycle says, so a chain never comes back to a state on its own. A state that holds a sub-machine has no automatic edge, and an automatic edge executes no operation that takes an input, since an attempt carries none. The build checks each of these, as the graph's structural rules list, and definition().automaticFrom(state) returns the automatic edges of a state in the order they are tried.

One attempt

An attempt is a call on an entity whose state has at least one automatic edge. Its candidates are those edges, in their order, and each one gets the admission that an execute of its identifier would get: the binding check of a sub-machine, then its guards in declaration order, with the context they would get there, whose input() is empty. A candidate refused by a guard, or as DETACHED, passes to the next one. The first one admitted runs within the same call as any edge runs, without its guards again: its action, its failure routes, its cascades, the starts and exits of sub-machines, the commit, the hooks and the watch reactions. When no candidate is admitted, the attempt ends in an Ignored with the reason NO_CANDIDATE_ADMITTED, writes nothing, and its rejections() list each refusal in the order tried. An attempt never returns Rejected, since it requests no identifier.

The guards of the onboarding, in AccountActions, refuse with the reason the caller reads:

@GraphGuard
public GuardResult infoComplete(GuardContext<Account, AccountStatus, AccountTransition> ctx) {
    return ctx.entity().infoComplete() ? GuardResult.pass() : GuardResult.reject("personal info is incomplete");
}

@GraphGuard
public GuardResult addressComplete(GuardContext<Account, AccountStatus, AccountTransition> ctx) {
    return ctx.entity().addressComplete() ? GuardResult.pass() : GuardResult.reject("address is incomplete");
}

A guard of a candidate runs once per attempt, and one that throws fails the attempt as it fails an execute. The guards of a refused candidate did run, so keep them free of side effects, as every guard should be. An automatic edge without guards is admitted whenever an attempt reaches it, unless the entity is a sub-machine that no parent holds, which refuses every candidate as DETACHED: an account never stays in FLAGGED, because REQUEST_REVIEW takes it on to REVIEW in the same chain. That holds for an edge that also serves as a failure route or as the target of a watch rule: marked automatic, it is a candidate of every attempt from its origin.

When the chain runs

After the commit of any root call, each entity with a hop or a sub-machine start in that commit runs its chain, in the order of the commit's log. Every call counts: an operation, an execute, a reevaluate, an advance, a watch reaction and an attempt, and so does every entity they move, a peer that a cascade moved, a child that its parent started and a parent that a child's exit moved. A watch reacts only to a peer whose final state differs from its original one, but a chain also runs after a self-loop, such as the account's TOUCH, and after hops that bring the entity back where it started: a self-loop often means that data changed.

The chain starts from the state the commit left the entity in, read from the commit's log, not from the entity. While that state has an automatic edge, it makes an attempt, a root call of its own, which reads the entity's state as any call does, and goes on from the state that attempt's commit left. It stops after an attempt that admits no candidate, after one whose failure takes a route that does not continue, after one that aborts, and after one whose own post-commit ran a call that moved the entity, such as a watch reaction, since that call decided the entity's chain. It ends without an attempt in a state that has no automatic edge.

Automatic chain: the account goes on by itselfAfter setPassword commits the account from NEW to PASSWORD_SET, and once any hooks and watch reactions of that commit ran, the account runs its automatic chain as step 8: COMPLETE_INFO to INFO_SET, COMPLETE_ADDRESS to ADDRESS_SET and, once ACTIVATE_PREMIUM is refused, ACTIVATE to ACTIVE. Each attempt is a call of its own, which automaticSteps() lists. The chain stops when no edge is admitted, when a failure takes a route that does not continue, when an attempt aborts, the limit included, when a call nested in an attempt's post-commit moved the entity, or when no automatic edge is left; automaticFailure(), automaticBlock() and automaticAbort() find what stopped it. GRAPHMAQUINA / AUTOMATIC TRANSITIONS Set the password. The account goes on by itself. Once any hooks and watch reactions of the commit ran, the account it moved runs its chain. setPassword NEW → PASSWORD_SET Hooks Step 6 Watch reactions Step 7 · new root calls Automatic chains Step 8 · one per entity THE ACCOUNT'S CHAIN PASSWORD_SET COMPLETE_INFO attempt 1 INFO_SET COMPLETE_ADDRESS attempt 2 ADDRESS_SET ACTIVATE attempt 3 ACTIVATE_PREMIUM refused first ACTIVE Each attempt is a call of its own: it tries the state's automatic edges in their order, runs the first one admitted, commits, runs its own hooks and reactions, and automaticSteps() lists it. THE CHAIN STOPS no edge admitted · a route that does not continue · an abort, the limit included a call nested in an attempt's post-commit moved the entity · no automatic edge left The library reports, the caller decides: automaticFailure(), automaticBlock() and automaticAbort() find what stopped it.

The chains run as step 8 of the commit sequence, once the commit's hooks ran and its watch reactions were dispatched. So every state an entity commits fires its watches before the entity moves on: an owner that waits for all its items in a state sees each item there, even one that then goes on by itself.

In OnboardingFlowTest, an account whose personal info and address are complete reaches ACTIVE in the call that sets its password. The outcome is the operation's own, to PASSWORD_SET, and its automaticSteps() list the three attempts that followed, the third once ACTIVATE_PREMIUM refused an account that is not premium. A premium account, whose data is otherwise the same, ends in PREMIUM:

Account account = new Account("a1");
account.setInfoComplete(true);
account.setAddressComplete(true);

Outcome<Account, AccountStatus, AccountTransition> outcome = accounts.setPassword(account);

assertThat(outcome).isApplied().movedTo(PASSWORD_SET).hasEntityState(Account::status, ACTIVE);
TypedAutomaticStepsAssert<Account, AccountStatus, AccountTransition> steps =
        assertThat(outcome).automaticSteps().forEntity(AccountsRuntime.KEY, account).hasSize(3);
steps.atIndex(0).isDone().outcome().isApplied().requestedTransition(COMPLETE_INFO).movedTo(INFO_SET);
steps.atIndex(1).isDone().outcome().isApplied().requestedTransition(COMPLETE_ADDRESS).movedTo(ADDRESS_SET);
steps.atIndex(2).isDone().outcome().isApplied().requestedTransition(ACTIVATE).movedTo(ACTIVE);

Account premium = new Account("a2");
premium.setInfoComplete(true);
premium.setAddressComplete(true);
premium.setPremium(true);
accounts.setPassword(premium);
assertEquals(PREMIUM, premium.status());

The deepest commit that moved an entity chains it. When a call made on the same thread inside the post-commit, a hook's call, a watch reaction or an attempt, moved an entity, that call ran or stopped the entity's chain, and the commit around it does not chain the entity again. A call that a hook starts on another thread, through async(), even one the hook waits for with join(), is not nested: the commit around it chains the entity from the state its own log left it in, its attempt reads the live state, and the chain can go on past a failure route that stopped the other call's chain. Start calls from a hook with the synchronous facade. Records, journals and reactions says in which outcome each chain is listed. A new entity has committed nothing, so the automatic edges of its initial state run only when advance asks for them; a child that its parent starts is the exception, since a start counts.

Each attempt is a call of its own. Observers see it, with the origin AUTOMATIC_STEP and the request ADVANCE, inside the AUTOMATIC_STEPS phase of the call that triggered it. It has its own flow and trail, and logs its start as an advance with the trigger= of that call. It is bounded by the asyncTimeout of its machine from the moment it starts, as a watch reaction is, and the chain runs on the thread of the call that triggered it: async().advance(entity) runs the whole call, its chains included, on the executor.

Advance an entity

advance(entity) makes one attempt on the entity's current state. The application calls it when it changed data without a transition. Every facade inherits it from Machine, StateMachine declares it, and the advance of AsyncStateMachine returns a CompletableFuture. Its outcome is the attempt's own, Applied or Failed, and once the attempt committed, the chain of its entity goes on from there, so automaticSteps() starts with the attempt that followed.

When there is nothing to do, it returns Ignored and writes nothing: with NO_AUTOMATIC_TRANSITION when the state has no automatic edge, a terminal state included, where of the machine's callbacks only the state getter ran; and with NO_CANDIDATE_ADMITTED, and its rejections(), when every candidate was refused. It never returns Rejected. A failure throws what execute would throw, an UnhandledFailureException for a domain failure that no route takes included, and a null entity, or a call made where no call may start, is refused before the call starts, as reevaluate refuses them.

In OnboardingFlowTest, an account stopped at INFO_SET for want of its address goes on once the address arrives, and a second advance, on ACTIVE, has nothing left to do:

Account account = new Account("a5");
account.setInfoComplete(true);
accounts.setPassword(account);
account.setAddressComplete(true);

Outcome<Account, AccountStatus, AccountTransition> outcome = accounts.advance(account);

assertThat(outcome).isApplied().requestedTransition(COMPLETE_ADDRESS).hasEntityState(Account::status, ACTIVE)
        .automaticSteps().forEntity(AccountsRuntime.KEY, account).single().isDone().outcome().isApplied()
        .requestedTransition(ACTIVATE);
assertThat(accounts.advance(account)).isIgnored().hasReason(IgnoreReason.NO_AUTOMATIC_TRANSITION);

An operation that commits a self-loop does the same with a hop of its own: touch moves an account from PASSWORD_SET to itself, and its commit runs the account's chain, as aSelfLoopRunsTheChainToo checks.

Stops, failures and the limit

What an attempt of a chain ends in The chain Its entry in automaticSteps()
The state has no automatic edge makes no attempt none
No candidate admitted, by a guard or as DETACHED stops Done with the Ignored and its rejections()
Applied goes on from the new state Done with the Applied
Failed, by a route that does not continue stops in the recovery state Done with the Failed
Failed, by a route that continues goes on from the recovery state Done with the Failed
An abort before any write: a domain failure that no route takes, a technical failure or any other exception before the first setter stops; the entity stays where the attempt found it Aborted with the attempt's exception
An abort after a write: a hook threw (AfterCommitException) or a setter failed midway (StatesWritten.PARTIAL) stops; the entity may have moved Aborted with the attempt's exception
A candidate admitted past maxAutomaticChain stops before the action runs, without writing Aborted with AutomaticChainExceededException
An Error propagates unchanged to the caller none

An attempt whose hook threw runs neither the watch reactions nor the chains of the entities it moved. When the hook that throws belongs to the call of the application, that call throws AfterCommitException and runs no chain at all. The call of the application follows the rule after a failure too: a Failed by a route that does not continue starts no chain for its entity, which stays in the recovery state until an operation or an advance moves it. The rule is per entity, by the last hop of each in the commit, so the other entities the same commit moved, such as a peer that the recovery action cascaded to, run their chains.

maxAutomaticChain(int), on the set builder and on MachineRegistry.builder(), bounds the attempts that commit something along one path of continuations from a call of the application: 10 by default, and at least 1. The k-th attempt of a chain is at level k, the first attempt of an advance at level 1, and a chain nested in an attempt's commit, such as a peer's, starts from that attempt's level, so twenty items that each take one step after one commit all stay at level 1. The attempt past the limit still selects: it aborts before the action runs, without writing, when it admits a candidate, and ends Ignored as usual when it admits none, so a chain of exactly maxAutomaticChain steps does not abort.

The cycle rule keeps the chain of one entity from coming back to a state on its own, so the limit cuts the paths that cross other entities: cascades, watches and sub-machines. A watch reaction passes on the automatic level it got, and an attempt passes on the watch chain it got, so maxAutomaticChain and maxWatchChain together cut a ping-pong through cascades or watches. Each attempt also runs one level deeper on the thread's stack than the call that triggered it, so the stack bounds a chain too, as build and manage machine sets explains.

A call that a hook starts is a new root: neither limit counts it, and the reactions and attempts it triggers begin chains of their own. A hook whose call runs that same hook again, through automatic attempts included, therefore recurs until the thread's stack overflows, as after-commit hooks warns; the library keeps no count per thread.

Failure routes that continue

A failure route, an onFailure or a recovery rule, stops its entity's chain by default: the entity stays in the recovery state until an operation or an advance moves it. A route declared to continue lets the chain go on from the recovery state instead. It may be declared on any edge, automatic or not: when the call of the application fails by such a route, its entity runs its chain from the recovery state too. With annotations, a Recovery takes continueChain = true, as COMPLETE_ADDRESS declares above, and a Transition takes onFailureContinues = true, which needs an onFailure. A continuing route leads to a state with an automatic edge, or the build fails.

The action of COMPLETE_ADDRESS, in AccountActions, returns the failure kind that the route takes when the verifier cannot verify the address:

@GraphAction
public ActionOutcome verifyAddress(TransitionContext<Account, AccountStatus, AccountTransition> ctx) {
    return verifier.verifies(ctx.entity())
            ? ActionOutcome.ok()
            : ActionOutcome.failed(AddressFailures.Unverifiable.class, "the address cannot be verified");
}

In OnboardingFlowTest, the failure takes FLAG to FLAGGED, the chain goes on through REQUEST_REVIEW, and the account ends in REVIEW. The call's outcome is still Applied, and it carries the failure:

verifier.refuse();
Account account = new Account("a4");
account.setInfoComplete(true);
account.setAddressComplete(true);

Outcome<Account, AccountStatus, AccountTransition> outcome = accounts.setPassword(account);

assertTrue(outcome.automaticFailure().isPresent());
assertThat(outcome).isApplied().hasNoAutomaticBlock().automaticFailure()
        .hasFailureTransition(FLAG).hasFailureKind(AddressFailures.Unverifiable.class).movedTo(FLAGGED);
assertEquals(REVIEW, account.status());

What the caller sees

automaticSteps() lists the attempts that the call's own commit triggered, each chain whole and in order, each attempt an AutomaticStep.Done with its outcome or an AutomaticStep.Aborted with its cause, as records, journals and reactions details. Three methods of every outcome search every attempt that ran for the call, those nested in its reactions and in other attempts included, and return the first that matches: automaticFailure() an attempt that ended in Failed, whether its route stopped the chain or let it go on; automaticBlock() one that admitted no candidate, whose rejections() say why; and automaticAbort() one that aborted. Their types carry wildcards, because the attempts can be of other machines, and find what the automatic steps did gives their search order. A chain that a call started by a hook decided is in that call's own outcome, which only the hook receives, so they do not find it.

In OnboardingFlowTest, an account without its address stops at INFO_SET, and the block says why:

Account account = new Account("a3");
account.setInfoComplete(true);

Outcome<Account, AccountStatus, AccountTransition> outcome = accounts.setPassword(account);

assertEquals(INFO_SET, account.status());
Outcome.Ignored<?, ?, ?> block = outcome.automaticBlock().orElseThrow();
assertEquals("address is incomplete", block.rejections().getFirst().reason());
assertThat(outcome).isApplied().automaticBlock().hasReason(IgnoreReason.NO_CANDIDATE_ADMITTED)
        .rejections().single().transition(COMPLETE_ADDRESS).isRejectedByGuardNamed("addressComplete");

A guard that stops the chain is no error for the library: the application decides. The library depends on no web framework, so the example's OnboardingController throws its own BadRequestException, which a framework's exception handler would turn into a 400: for a call that was rejected, for an automatic step that failed, even by a route that let the chain go on, and for one that stopped at a guard. Otherwise it answers with the state the account reached. theControllerAnswersBadRequest runs each case:

public AccountStatus setPassword(Account account) {
    Outcome<Account, AccountStatus, AccountTransition> outcome = accounts.setPassword(account);
    if (outcome instanceof Outcome.Rejected<Account, AccountStatus, AccountTransition> rejected) {
        throw new BadRequestException(rejected.reason());
    }
    outcome.automaticFailure().ifPresent((Outcome.Failed<?, ?, ?> failure) -> {
        throw new BadRequestException(failure.reason());
    });
    outcome.automaticBlock().ifPresent((Outcome.Ignored<?, ?, ?> block) -> {
        throw new BadRequestException(block.rejections().getFirst().reason());
    });
    return account.status();
}

advance(entity) goes on from where the entity stands: after a Failed, from the recovery state; after an abort before any write, from the state the attempt started in, which it tries again. An aborted attempt's cause is its CallFailedException, whose statesWritten() says whether it wrote: after a setter or a hook threw, the entity may have moved, and advance goes on from whatever state it has.

The application's transaction

GraphMaquina's commit is in memory. When an automatic step fails or stops at a guard, the call and the steps before it have committed, and the outcome says so: the controller above throws while the account stays in INFO_SET or in REVIEW, as its test checks. If the application throws its error inside a database transaction that rolls back on that exception, the database undoes the original call and the earlier steps too, although the outcome says they committed. A Spring @Transactional method, for one, rolls back on an unchecked exception by default. To keep the progress and still answer with an error, configure the transaction so that this exception does not roll it back, or leave the transaction before you throw. Framework and database boundaries covers the rest of what a database transaction does not get from the in-memory commit.

The same graph with the DSL

OnboardingDslTest declares the onboarding's graph with the DSL. It checks that the graph's structural snapshot is the annotated graph's, and that a machine built from it takes a complete account to ACTIVE in the call that sets its password:

static GraphDefinition<Account, AccountStatus, AccountTransition> graph(AccountActions actions) {
    return StateGraph.define(MachineKey.of(Account.class, AccountStatus.class, AccountTransition.class))
            .initial(NEW).terminal(ACTIVE).terminal(PREMIUM).terminal(CLOSED).allowsCycle(PASSWORD_SET)
            .statePolicy(NEW, "a new account sets its password")
            .statePolicy(PASSWORD_SET, "an account completes its personal info")
            .statePolicy(INFO_SET, "an account completes its address")
            .statePolicy(ADDRESS_SET, "an account is activated")
            .statePolicy(FLAGGED, "a flagged account is reviewed")
            .statePolicy(REVIEW, "a reviewed account is closed")
            .transition(SET_PASSWORD, NEW, PASSWORD_SET).endTransition()
            .transition(TOUCH, PASSWORD_SET, PASSWORD_SET).endTransition()
            .transition(COMPLETE_INFO, PASSWORD_SET, INFO_SET).automatic()
                .guard("infoComplete", actions::infoComplete)
                .endTransition()
            .transition(COMPLETE_ADDRESS, INFO_SET, ADDRESS_SET).automatic()
                .guard("addressComplete", actions::addressComplete)
                .action("verifyAddress", actions::verifyAddress)
                .recoverAndContinue(AddressFailures.Unverifiable.class, FLAG)
                .endTransition()
            .transition(FLAG, INFO_SET, FLAGGED).endTransition()
            .transition(REQUEST_REVIEW, FLAGGED, REVIEW).automatic().endTransition()
            .transition(CLOSE, REVIEW, CLOSED).endTransition()
            .transition(ACTIVATE_PREMIUM, ADDRESS_SET, PREMIUM).automatic()
                .guard("premium", actions::premium)
                .endTransition()
            .transition(ACTIVATE, ADDRESS_SET, ACTIVE).automatic().endTransition()
            .automaticOrder(ADDRESS_SET, List.of(ACTIVATE_PREMIUM, ACTIVATE))
            .build();
}

automatic() marks the edge it is called on, and a second mark on one edge is SG507, like a repeated timeout. automaticOrder(state, transitions) declares the order of a state. recoverAndContinue(kind, transition) has the overloads of recover, with one throwable type or a list of them, and declares a rule that continues. onFailureAndContinue(transition) is the edge's onFailure, declared as a route that continues: declaring it together with onFailure is SG507. build() checks the rules of declare automatic edges, and diagnostics lists their codes. A GraphDefinition written by hand implements automaticFrom(state) itself. The runtime asks only that method, so it must agree with the automatic() marks of the edges, which the DSL and the annotations guarantee and a hand-written definition does not. A registry asks it for every state once as it is built, and what it throws there propagates from the build; when no state of any graph in the registry has an automatic edge then, none of the registry's calls runs an automatic chain.

Inspect and test

TransitionSpec.automatic() and onFailureContinues(), and RecoveryRule.continueChain(), read the marks, as read a definition shows. The Graphviz export draws an automatic edge in the theme's automatic color, blue by default, and prints [auto] on the line under the identifier of a state's only automatic edge, [auto 1], [auto 2] and so on, in the declared order, when there are several, and continues in a route that continues. The onboarding's golden diagram and contract snapshot pin its marks and its order. An eligibility check answers for an automatic edge as for any other. The assertions of graphmaquina-test on automatic edges, on automaticSteps() and on the three searches are in testing samples.


Next: Asynchronous work and timeouts. Back to the documentation index.