You are reading GraphMaquina 2.0.4. The latest version is 2.0.6.

Compose machines

Sub-machines: one payment machine bound in two states of a bookingThe booking machine binds the same payment machine in two of its states, DEPOSIT and BALANCE. Each state is drawn as a cluster that holds the payment graph: AUTHORIZING and its three terminal states CAPTURED, DECLINED and VOIDED. BOOK enters DEPOSIT and starts the deposit payment at AUTHORIZING. A captured deposit exits through DEPOSIT_PAID, which moves the booking to BALANCE and starts the balance payment; a captured balance exits through BALANCE_PAID to CONFIRMED. A declined payment exits through DEPOSIT_DECLINED or BALANCE_DECLINED and a voided one through PAYMENT_VOIDED, both to CANCELLED. CANCEL leaves either state from its border, by an edge of the booking, and runs no exit. Entering a bound state starts the child; a child whose parent does not hold it, as when its booking has left the state, is rejected as DETACHED; the terminal state of the child selects the exit, which commits with the child in the same unit of work. The payment machine knows no parent, and the subscription machine binds it again in RENEWAL. GRAPHMAQUINA / SUB-MACHINES A state can hold a whole machine. Bookings binds the same Payments machine in DEPOSIT and in BALANCE. BOOKINGS the parent machine REQUESTED initial DEPOSIT holds Payments BOOK starts the deposit AUTHORIZING VOIDED DECLINED CAPTURED BALANCE holds Payments DEPOSIT_PAID starts the balance AUTHORIZING VOIDED DECLINED CAPTURED CANCELLED terminal CONFIRMED terminal BOOK DEPOSIT_PAID PAYMENT_VOIDED DEPOSIT_DECLINED PAYMENT_VOIDED BALANCE_DECLINED BALANCE_PAID CANCEL CANCEL Entering starts the child An edge into DEPOSIT or BALANCE starts its payment at AUTHORIZING. Parent elsewhere: DETACHED A payment whose booking has left the state is refused; no edge is looked up. Terminal selects the exit A capture and its DEPOSIT_PAID commit in one unit of work. REUSED Payments knows no parent. Subscriptions binds the same machine in RENEWAL. CANCEL leaves either state by an edge of the booking: no exit runs, and its action voids the payment it leaves.

A state can hold a whole machine of its own: its sub-machine, or child. The repository's billing example, in the package io.github.graphmaquina.example.billing, binds one payment machine three times. A booking pays a deposit in DEPOSIT and then a balance in BALANCE, and a subscription pays each renewal in RENEWAL. The payment machine knows no parent: every binding is declared on the parent's side, so one machine can be bound in several states of several machines. Three rules make the contract:

Contents

Declare a sub-machine

The child is an ordinary machine. Payments declares AUTHORIZING and three terminal states, CAPTURED, DECLINED and VOIDED, and nothing in it names a booking or a subscription. The parent declares the pair with @GraphPeers, as for a watch, and binds the child with the pair's generated Submachine. This is the whole Bookings interface, which imports the BookingStatus constants statically:

/**
 * The booking machine: {@code DEPOSIT} and {@code BALANCE} each hold a payment of {@link Payments},
 * the same machine bound twice. The terminal state each payment reaches selects the exit of its
 * state, and {@code CANCEL} interrupts either one. The processor generates BookingsRuntime.
 *
 * <p>Exits are declared on the interface, not on operations: an exit runs only when its payment
 * ends, so no operation may declare one.</p>
 */
@GenerateGraphApi
@GraphPeers(Payments.class)
@BookingsGraph.Definition(
    initial = REQUESTED,
    terminals = {CONFIRMED, CANCELLED},
    state = BookingRefs.Status.class,
    id = BookingRefs.Id.class)
@BookingsGraph.StatePolicy(state = REQUESTED, otherwise = "a booking is booked first")
@BookingsGraph.StatePolicy(state = DEPOSIT, otherwise = "the deposit payment decides")
@BookingsGraph.StatePolicy(state = BALANCE, otherwise = "the balance payment decides")
// the exit of a captured deposit; when holdRoom fails, NO_ROOM moves to CANCELLED
@BookingsGraph.Transition(
    id = BookingTransition.DEPOSIT_PAID,
    from = DEPOSIT,
    to = BALANCE,
    action = BookingActionsRefs.HoldRoom.class,
    onFailure = BookingTransition.NO_ROOM)
@BookingsGraph.Transition(id = BookingTransition.NO_ROOM, from = DEPOSIT, to = CANCELLED)
@BookingsGraph.Transition(id = BookingTransition.DEPOSIT_DECLINED, from = DEPOSIT, to = CANCELLED)
@BookingsGraph.Transition(id = BookingTransition.BALANCE_PAID, from = BALANCE, to = CONFIRMED)
@BookingsGraph.Transition(id = BookingTransition.BALANCE_DECLINED, from = BALANCE, to = CANCELLED)
@BookingsGraph.Transition(
    id = BookingTransition.PAYMENT_VOIDED,
    from = {DEPOSIT, BALANCE},
    to = CANCELLED)
@BookingsPayments.Submachine(
    state = DEPOSIT,
    child = BookingRefs.Deposit.class,
    parentLookup = BillingLookupsRefs.BookingOf.class,
    exits = {
        @BookingsPayments.Exit(
            on = PaymentStatus.CAPTURED,
            transition = BookingTransition.DEPOSIT_PAID),
        @BookingsPayments.Exit(
            on = PaymentStatus.DECLINED,
            transition = BookingTransition.DEPOSIT_DECLINED),
        @BookingsPayments.Exit(
            on = PaymentStatus.VOIDED,
            transition = BookingTransition.PAYMENT_VOIDED)})
@BookingsPayments.Submachine(
    state = BALANCE,
    child = BookingRefs.Balance.class,
    parentLookup = BillingLookupsRefs.BookingOf.class,
    exits = {
        @BookingsPayments.Exit(
            on = PaymentStatus.CAPTURED,
            transition = BookingTransition.BALANCE_PAID),
        @BookingsPayments.Exit(
            on = PaymentStatus.DECLINED,
            transition = BookingTransition.BALANCE_DECLINED),
        @BookingsPayments.Exit(
            on = PaymentStatus.VOIDED,
            transition = BookingTransition.PAYMENT_VOIDED)})
public interface Bookings extends Machine<Booking, BookingStatus, BookingTransition> {

    @BookingsGraph.Transition(id = BookingTransition.BOOK, from = REQUESTED, to = DEPOSIT)
    Outcome<Booking, BookingStatus, BookingTransition> book(Booking booking);

    @BookingsGraph.Transition(
        id = BookingTransition.CANCEL,
        from = {DEPOSIT, BALANCE},
        to = CANCELLED,
        action = BookingActionsRefs.Cancel.class)
    Outcome<Booking, BookingStatus, BookingTransition> cancel(Booking booking);
}

Submachine is repeatable, so one machine can bind the same child in several states, each binding with its own way to the child and its own exits. Its elements, and those of Exit, take the enums of their side of the pair, so a state or an identifier of the wrong machine is a javac error:

Element Meaning
state The bound state of the parent. A terminal state holds no sub-machine, and another state holds at most one (SG803).
child A property of the parent that returns Optional of the child's entity: Booking.deposit() and Booking.balance() return Optional<Payment>.
parentLookup A @GraphLookup method that finds the parent of a child entity, described below.
parent Instead of parentLookup, a property of the child that returns Optional of the parent's entity. A child over another entity than the parent's needs child and exactly one of parent or parentLookup (SG806).
exits One Exit(on, transition) per terminal state of the child: the identifier of the parent that the terminal state selects, which needs an edge from the bound state (SG801, SG802). Two terminal states may select the same identifier, as DECLINED and VOIDED do in Subscriptions below.

An identifier that an exit names runs from the bound state only when the child ends. No onFailure, recovery rule or rule of that state's watch may name it from there, and no operation of the facade may execute it at all, since an operation requests its identifier from whichever state the machine is in (SG804). The exits of Bookings are therefore declared on the interface, and book and cancel are its only operations. From any other state, the same identifier is an ordinary edge, unless a binding of that state maps it too. A machine's sub-machines never contain the machine again (SG805). Structural rules and graph and declaration diagnostics list every check.

Find the parent with a lookup

A call to a payment has to know whether a parent holds it, so each binding needs the way back from the child. @GraphLookup marks a method of signature Optional<E> name(P child), static or instance, on any class. The generator exports it as a symbol of that class's Refs, such as BillingLookupsRefs.BookingOf, which parentLookup names; the ownerLookup of a watch names one the same way, to find the owner of a peer. These are the two lookups of BillingLookups, which keeps the bookings and subscriptions it registered in two maps by payment id, where an application would ask its repository:

@GraphLookup
public Optional<Booking> bookingOf(Payment payment) {
    return Optional.ofNullable(bookings.get(payment.id()));
}

@GraphLookup
public Optional<Subscription> subscriptionOf(Payment payment) {
    return Optional.ofNullable(subscriptions.get(payment.id()));
}

An empty Optional means that this binding finds no parent. Lookups and the child and parent properties are synchronous and run inside the call. One that returns null instead of an Optional aborts the call, so does one that throws, with what it threw as the cause, and so does a parent or a child whose identity or state cannot be read; execute, reevaluate, advance or eligibility called from one of them throws ReentrantTransitionException, which aborts the call too. An eligibility check that meets any of these fails with an EligibilityCheckException instead.

Build the set

BillingMachines lists Bookings, Subscriptions and Payments, as ShopMachines lists the shop's machines. Its generated builder takes the instance hosts of every machine, here the booking actions and the lookups:

BillingLookups lookups = new BillingLookups();
BillingMachines billing = BillingMachinesRuntime
        .builder(Duration.ofSeconds(10), new BookingActions(desk), lookups)
        .build();

desk is the application's RoomDesk, the port that holdRoom, the action of DEPOSIT_PAID, asks for a room. The first argument is the shared timeout of the set's asynchronous machines, which asynchronous exits explains. The set builds the payment definition once and passes that one instance to the payment machine and to the companions of both parents: BookingsRuntime.graph(...) and SubscriptionsRuntime.graph(...) take the definition of each machine they bind before their hosts. A registry refuses a parent whose child machine it does not hold, or holds built from another definition: MachineRegistry.Builder.build() throws IllegalStateException. A generated set always registers the child with the very definition its parents bind; the check matters when you assemble machines yourself, as with the programmatic DSL.

Enter and exit

A booking holds its two payments, and lookups.register(booking) lets bookingOf find it from either one:

Booking booking = new Booking("b1", new Payment("b1-deposit"), new Payment("b1-balance"));
lookups.register(booking);
Payment deposit = booking.deposit().orElseThrow();

Outcome<Booking, BookingStatus, BookingTransition> booked = billing.bookings().book(booking);
Outcome<Payment, PaymentStatus, PaymentTransition> depositPaid =
        billing.payments().capture(deposit);

book enters DEPOSIT, so its call also starts the deposit at AUTHORIZING. booked.starts() holds one SubmachineStart: the payment machine and the deposit, the state the deposit had and the one it started in, and the booking with its bound state DEPOSIT. The start is logged right after the edge that enters, before that edge's action runs, so an action that cascades into the child finds it at its initial state. A start is no hop: it is not in records(), and it runs no hook. A child whose initial state is terminal enters and exits in that same call.

The two calls as a sequence:

deposit paymentBookingpayments machinebookings machineAppdeposit paymentBookingpayments machinebookings machineAppbook: the edge that enters DEPOSIT starts the childthe start joins BOOK's unit of work, so one commit writes DEPOSIT and AUTHORIZINGcapture: the child's terminal state selects the parent's exitone commit writes CAPTURED, BALANCE and the balance's AUTHORIZINGbook(booking)resolve BOOK from REQUESTED to DEPOSITstart the deposit at AUTHORIZING, in the same unit of workApplied, whose starts() hold the depositcapture(deposit)resolve CAPTURE to CAPTURED, a terminal staterun the exit DEPOSIT_PAID from DEPOSIT, one level deeperDEPOSIT_PAID leads to BALANCE, which starts the balance paymentApplied for the deposit, whose records() hold CAPTURE at depth 0 and DEPOSIT_PAID at depth 1
deposit paymentBookingpayments machinebookings machineAppdeposit paymentBookingpayments machinebookings machineAppbook: the edge that enters DEPOSIT starts the childthe start joins BOOK's unit of work, so one commit writes DEPOSIT and AUTHORIZINGcapture: the child's terminal state selects the parent's exitone commit writes CAPTURED, BALANCE and the balance's AUTHORIZINGbook(booking)resolve BOOK from REQUESTED to DEPOSITstart the deposit at AUTHORIZING, in the same unit of workApplied, whose starts() hold the depositcapture(deposit)resolve CAPTURE to CAPTURED, a terminal staterun the exit DEPOSIT_PAID from DEPOSIT, one level deeperDEPOSIT_PAID leads to BALANCE, which starts the balance paymentApplied for the deposit, whose records() hold CAPTURE at depth 0 and DEPOSIT_PAID at depth 1

capture is a call of the payment machine. Its step ends in CAPTURED, a terminal state, so the call runs the booking's exit DEPOSIT_PAID from DEPOSIT, one level deeper, with the exit's guards and action. depositPaid is the payment's own outcome, an Applied that moved the payment to CAPTURED. Its records() hold the capture at depth 0 and DEPOSIT_PAID at depth 1, in log order, and its starts() hold the balance, because the exit entered BALANCE, which binds a payment too. Capturing the balance then exits through BALANCE_PAID to CONFIRMED. The exits belong to the calls that ran them: an observer sees three calls in all, the booking's book and the two captures. When an exit leaves a parent in a terminal state that a binding of its own parent maps, the grandparent's exit runs next, one level deeper. Each level counts for maxCascadeDepth. Entering a state whose child's initial state is itself bound starts the grandchild too, and starts() lists it with its depth. A child that ends while its parent is still running the edge that entered the state, as when that edge's action captures the payment, exits once that edge's step is over. That exit runs one level below the edge's step, at the same depth as the capture, and counts for maxCascadeDepth at that depth.

In a definition assembled without the DSL, a child that reaches a terminal state its binding maps to no exit aborts the call in ACTION (the terminal <T> of <child machine key> has no exit in <node>), and an exit identifier with no edge from the bound state aborts it as a rejection inside the exit; the DSL and the annotations refuse both graphs.

An exit is an ordinary edge of the parent, so its failure routes apply as on any edge. When the desk answers that no room is left, holdRoom fails: the booking takes the route NO_ROOM to CANCELLED, the whole call commits, and the capture's outcome is still Applied. The payment stays CAPTURED, since the route moves the booking and not the payment, and the balance is not started: the edge that would have entered BALANCE was rolled back with its start. An exit that a guard rejects aborts the call with a TransitionAbortedException whose message includes rejected inside the exit of DEPOSIT by guard ..., and one that fails with no route ends it in an UnhandledFailureException. Either way nothing is written, the capture included. As with a cascade, what an action did outside the machines, such as asking the desk for a room, is not undone.

Interrupt, detach and reserve

A parent can leave a bound state by an edge of its own while the child is still running. cancel leaves DEPOSIT or BALANCE for CANCELLED, and its action voids the payment of the state the booking leaves:

@GraphAction
public ActionOutcome cancel(TransitionContext<Booking, BookingStatus, BookingTransition> ctx) {
    Booking booking = ctx.entity();
    Payment payment = ctx.from() == BookingStatus.DEPOSIT
            ? booking.deposit().orElseThrow()
            : booking.balance().orElseThrow();
    ctx.cascade(Payments.class, payment, PaymentTransition.VOID);
    return ActionOutcome.ok();
}

While the booking leaves the state, the binding still holds the payment, so the cascade runs. The booking is in flight, so the voided payment runs no exit: PAYMENT_VOIDED does not run, and the booking ends in CANCELLED by its own edge. An interruption whose action leaves the child alone leaves it in the state it had reached.

Once the booking is cancelled, its payments are detached. billing.payments().capture(deposit) then returns a Rejected outcome with the code DETACHED and the reason no parent holds it in DEPOSIT or BALANCE, which names the bound state of every binding that found the booking. No guard and no action runs, and the check comes before the edge is looked up, so a detached child is refused as DETACHED even for an identifier it has no edge for. Inside a cascade the refusal aborts the call, like any nested rejection. Entering a bound state again restarts its child at the initial state, whatever state the child had reached: a subscription charges the same renewal payment in every period.

The exits are reserved. In the bound state, only the end of the child runs an identifier that an exit names: a request for DEPOSIT_PAID from DEPOSIT by any other path, such as a cascade or StateMachine.execute on a registry you assembled, is refused as RESERVED_EXIT, with the reason DEPOSIT_PAID leaves DEPOSIT only when its sub-machine ends, and aborts the call inside a cascade. Inspection still lists the edge: transitionsFrom(BookingStatus.DEPOSIT) includes DEPOSIT_PAID.

A child entity has one active parent at a time. When two bindings each find a parent that holds the child in its bound state, or while leaving it, a call to the child aborts with an AmbiguousParentException as its cause. A parent that leaves one bound state for another that binds the same child holds it only in the state it enters, whose entry has just restarted the child, so the action of that edge can cascade into the child.

StateMachine.eligibility(entity, id) asks the same questions without running the edge: where execute would reject a request as DETACHED or RESERVED_EXIT, it answers Ineligible with that kind and that reason, and it starts no child and runs no exit. Where a call to the child would abort with an AmbiguousParentException, it throws an EligibilityCheckException with that cause.

Reuse a machine

Each binding of Bookings reaches its own payment, so the booking holds its deposit only in DEPOSIT and its balance only in BALANCE. Subscriptions binds the same machine once more, with exits of its own:

@GraphPeers(Payments.class)
@SubscriptionsPayments.Submachine(
    state = RENEWAL,
    child = SubscriptionRefs.Renewal.class,
    parentLookup = BillingLookupsRefs.SubscriptionOf.class,
    exits = {
        @SubscriptionsPayments.Exit(
            on = PaymentStatus.CAPTURED,
            transition = SubscriptionTransition.RENEWED),
        @SubscriptionsPayments.Exit(
            on = PaymentStatus.DECLINED,
            transition = SubscriptionTransition.LAPSE),
        @SubscriptionsPayments.Exit(
            on = PaymentStatus.VOIDED,
            transition = SubscriptionTransition.LAPSE)})

DECLINED and VOIDED both select LAPSE. The payment machine keeps one definition for all three bindings, and its definition does not change by being bound.

Sub-machines over the same entity

A child can also govern a second state of the parent's own entity. With annotations, such a Submachine names none of child, parent or parentLookup. In the DSL, submachine(state, child) takes no lookup, since the child entity is the parent itself. In SameEntitySubmachineTest, one of the billing tests, a stay keeps its own status and its payment status in two fields, and a payment graph over Stay governs the second one:

/** Built once: the payment machine must be built from the very definition the stay binds. */
static final GraphDefinition<Stay, PaymentStatus, PaymentTransition> PAYMENT_GRAPH =
        StateGraph.define(STAY_PAYMENTS)
        .initial(PaymentStatus.AUTHORIZING)
        .terminal(PaymentStatus.CAPTURED)
        .terminal(PaymentStatus.DECLINED)
        .terminal(PaymentStatus.VOIDED)
        .statePolicy(PaymentStatus.AUTHORIZING, "an authorization is captured, declined or voided")
        .transition(PaymentTransition.CAPTURE, PaymentStatus.AUTHORIZING, PaymentStatus.CAPTURED)
            .endTransition()
        .transition(PaymentTransition.DECLINE, PaymentStatus.AUTHORIZING, PaymentStatus.DECLINED)
            .endTransition()
        .transition(PaymentTransition.VOID, PaymentStatus.AUTHORIZING, PaymentStatus.VOIDED)
            .endTransition()
        .build();

static final GraphDefinition<Stay, StayStatus, StayTransition> STAY_GRAPH = StateGraph.define(STAYS)
        .initial(StayStatus.REQUESTED)
        .terminal(StayStatus.CONFIRMED)
        .terminal(StayStatus.CANCELLED)
        .statePolicy(StayStatus.REQUESTED, "a stay is booked first")
        .statePolicy(StayStatus.PAYING, "the payment decides")
        .transition(StayTransition.BOOK, StayStatus.REQUESTED, StayStatus.PAYING)
            .endTransition()
        .transition(StayTransition.CONFIRM, StayStatus.PAYING, StayStatus.CONFIRMED)
            .endTransition()
        .transition(StayTransition.CANCEL, StayStatus.PAYING, StayStatus.CANCELLED)
            .endTransition()
        .submachine(StayStatus.PAYING, PAYMENT_GRAPH)
        .exit(PaymentStatus.CAPTURED, StayTransition.CONFIRM)
        .exit(PaymentStatus.DECLINED, StayTransition.CANCEL)
        .exit(PaymentStatus.VOIDED, StayTransition.CANCEL)
        .endSubmachine()
        .build();

STAYS and STAY_PAYMENTS are two keys over Stay, with different state enums, so one registry holds both machines, each with the state accessors of its own field:

private static MachineRegistry registry() {
    return MachineRegistry.builder()
            .add(StateMachines.from(STAY_GRAPH)
                    .state(
                        (Stay stay) -> stay.status,
                        (Stay stay, StayStatus status) -> stay.status = status)
                    .identity((Stay stay) -> stay.id))
            .add(StateMachines.from(PAYMENT_GRAPH)
                    .state(
                        (Stay stay) -> stay.paymentStatus,
                        (Stay stay, PaymentStatus status) -> stay.paymentStatus = status)
                    .identity((Stay stay) -> stay.id))
            .build();
}

A capture through registry.of(STAY_PAYMENTS) moves the stay's payment status to CAPTURED and its own status to CONFIRMED in one commit.

Asynchronous exits

An exit waits under the deadline of the call that runs it: the budget of the machine whose call started the root, which the exit edge's own timeout can only shorten. A machine whose calls can run an asynchronous edge implicitly, as an exit or as an edge an exit leads to, therefore needs an asyncTimeout even when its own graph is synchronous. holdRoom is asynchronous, so Bookings is an asynchronous machine, and so is Payments, since its capture runs DEPOSIT_PAID. Subscriptions runs no asynchronous edge, directly or implicitly. The generated builder therefore takes the shared timeout first and installs it on Bookings and Payments only. asyncTimeout(Payments.class, Duration) overrides the payment machine's budget, and asyncTimeout(Subscriptions.class, Duration) throws IllegalArgumentException. Through billing.payments().async(...), the whole call runs on the payment machine's executor, the exit included, and the binding is checked when the call starts running. Deadline rules has the whole rule, and the billing test AsyncExitTest holds the exit open with a ControlledAsyncAction.

Diagrams, concurrency and tests

GraphvizExporter draws each bound state as a cluster labelled with the state and the child machine, such as DEPOSIT: Payment/PaymentStatus, which holds the child's own diagram. Inspect graphs and export diagrams says how each edge is drawn, and the core tests pin a booking with one payment machine bound in two states in submachine-shared-child.dot.

A call that ends a child its parent held commits the parent's exit, or moved the parent itself, so the commit's check of the original states covers the parent. A call that moves a child to a state that is not terminal leaves the parent out of the commit, so serialize the calls of a parent and its sub-machines as those of one aggregate, as initialize and protect state explains.

A parent and its child must be held by the same @StateGraphs set: a set that holds the parent but not its child is SG806. The child can be a machine of the same compilation, or of a dependency, a jar or a directory of classes whose artifact carries the export index its build published, as multiple modules and published JARs describes; compose machines across modules and JARs binds one through a parent lookup. A child that is a machine of a dependency whose artifact carries no export index, or one that does not list it or describes it otherwise than its classes, or that passes Machine an enum the classpath does not declare, or that has a supertype the classpath does not declare and reaches Machine through none it declares, is SG602, naming that jar or directory whenever the generator can tell it; any other child that is neither is SG608. A standalone machine built with StateMachines.Builder.build() refuses any sub-machine binding, since its registry holds no other machine.

Assert bindings, starts and both refusals with the typed views of the testing guide's sub-machines section. The billing tests run the flows of this section: the starts and exits of a booking, the detached deposit of a cancelled booking, which a check of capture also finds, the NO_ROOM route, a renewal that restarts its payment, the stay and the asynchronous exit.


Next: Compose machines across modules and JARs. Back to the documentation index.