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

Quickstart: a complete ticket machine

Configure the build first, with Gradle or Maven, as the installation page shows. Then create the following seven files under src/main/java/com/example/tickets/. Both build configurations compile them, and they require no Lombok, framework or external service. You can write all seven files before the first build; the generation walkthrough explains why the references to generated annotations are valid in this workflow.

A ticket is submitted for review, and submission registers it with the review board. A board that will not take the ticket is a declared domain failure, so the ticket lands in FAILED. Once in review it can be approved by a person, auto-approved by a rule, retouched in place, or rejected back to OPEN.

The ticket graph: identified edges, parallel edges and a self-loopFour states and six identified edges. SUBMIT leaves OPEN for REVIEW behind the hasTitle guard, and its onFailure route DECLINE leaves the same origin for FAILED. From REVIEW, APPROVE and AUTO_APPROVE are two separate edges to DONE, each with its own action; RETOUCH is a self-loop that applies and stays in REVIEW; REJECT returns to OPEN. A request whose identifier has no edge from the current state is refused by that node's policy. GRAPHMAQUINA / QUICKSTART Four states. Six edges. Each one has a name. An operation selects an edge by its identifier, never by where that edge lands. REJECT reject() OPEN Initial state REVIEW Four edges leave here DONE Terminal · no exit FAILED Terminal · no exit SUBMIT submit() guard hasTitle action register APPROVE approve() AUTO_APPROVE autoApprove() RETOUCH retouch() DECLINE — the onFailure route of SUBMIT, resolved from OPEN APPROVE and AUTO_APPROVE are two edges between the same pair of states; each runs its own action and neither can stand in for the other. RETOUCH is an ordinary edge that ends where it started: it applies. An identifier with no edge from the current state is refused by that node's policy.

Contents

TicketState.java

package com.example.tickets;

public enum TicketState {
    OPEN, REVIEW, DONE, FAILED
}

TicketTransition.java

package com.example.tickets;

public enum TicketTransition {
    SUBMIT, APPROVE, AUTO_APPROVE, RETOUCH, REJECT, DECLINE
}

Two enums, never one. TicketState names where a ticket can be; TicketTransition names the edges it can take. You write both: GraphMaquina derives no identifier from an action name, a method name or a destination.

Ticket.java

package com.example.tickets;

import io.github.graphmaquina.annotation.GraphProperty;
import java.util.Objects;

public final class Ticket {
    @GraphProperty
    private final String id;

    @GraphProperty
    private TicketState state = TicketState.OPEN;

    private final String title;
    private final boolean accepted;

    public Ticket(String id, String title, boolean accepted) {
        this.id = Objects.requireNonNull(id);
        this.title = Objects.requireNonNull(title);
        this.accepted = accepted;
    }

    public String getId() { return id; }
    public TicketState getState() { return state; }
    public String getTitle() { return title; }
    public boolean isAccepted() { return accepted; }

    public void setState(TicketState state) {
        this.state = Objects.requireNonNull(state);
    }
}

The state starts initialized. initial = OPEN describes the graph; it does not initialize new entities. The runtime calls the state setter during commit. Action code must not call it.

TicketActions.java

package com.example.tickets;

import io.github.graphmaquina.annotation.GraphAction;
import io.github.graphmaquina.annotation.GraphGuard;
import io.github.graphmaquina.annotation.GraphHook;
import io.github.graphmaquina.api.ActionOutcome;
import io.github.graphmaquina.api.CommitContext;
import io.github.graphmaquina.api.GuardContext;
import io.github.graphmaquina.api.GuardResult;
import io.github.graphmaquina.api.TransitionContext;
import java.util.ArrayList;
import java.util.List;

public final class TicketActions {
    private final List<String> decisions = new ArrayList<>();

    /** Which action actually ran, in order. Two edges to DONE never stand in for each other. */
    public List<String> decisions() {
        return List.copyOf(decisions);
    }

    @GraphGuard
    public GuardResult hasTitle(GuardContext<Ticket, TicketState, TicketTransition> ctx) {
        return ctx.entity().getTitle().isBlank()
                ? GuardResult.reject("a ticket needs a title")
                : GuardResult.pass();
    }

    @GraphAction
    public ActionOutcome register(TransitionContext<Ticket, TicketState, TicketTransition> ctx) {
        return ctx.entity().isAccepted()
                ? ActionOutcome.ok()
                : ActionOutcome.failed("the review board declined the ticket");
    }

    @GraphAction
    public ActionOutcome approve(TransitionContext<Ticket, TicketState, TicketTransition> ctx) {
        decisions.add("approve " + ctx.entity().getId());
        return ActionOutcome.ok();
    }

    @GraphAction
    public ActionOutcome autoApprove(TransitionContext<Ticket, TicketState, TicketTransition> ctx) {
        decisions.add("autoApprove " + ctx.entity().getId());
        return ActionOutcome.ok();
    }

    @GraphAction
    public ActionOutcome retouch(TransitionContext<Ticket, TicketState, TicketTransition> ctx) {
        decisions.add("retouch " + ctx.entity().getId());
        return ActionOutcome.ok();
    }

    @GraphHook
    public void committed(Ticket ticket, CommitContext<TicketState, TicketTransition> commit) {
        System.out.println("Committed " + ticket.getId() + ": " + commit.from()
                + " -" + commit.transition() + "-> " + commit.to());
    }
}

Tickets.java

package com.example.tickets;

import io.github.graphmaquina.annotation.GenerateGraphApi;
import io.github.graphmaquina.api.Machine;
import io.github.graphmaquina.api.Outcome;

@GenerateGraphApi
@TicketsGraph.Definition(
    initial = TicketState.OPEN,
    terminals = {TicketState.DONE, TicketState.FAILED},
    allowsCycle = {TicketState.OPEN, TicketState.REVIEW},
    state = TicketRefs.State.class,
    id = TicketRefs.Id.class,
    afterCommit = TicketActionsRefs.Committed.class)
@TicketsGraph.StatePolicy(state = TicketState.OPEN, otherwise = "submit the ticket first")
@TicketsGraph.StatePolicy(
    state = TicketState.REVIEW,
    otherwise = "approve, reject or retouch the ticket")
@TicketsGraph.Reject(
    from = TicketState.OPEN,
    transition = TicketTransition.APPROVE,
    reason = "approval requires review")
// DECLINE has no method: it is the failure route that SUBMIT names in onFailure
@TicketsGraph.Transition(
    id = TicketTransition.DECLINE,
    from = TicketState.OPEN,
    to = TicketState.FAILED)
public interface Tickets extends Machine<Ticket, TicketState, TicketTransition> {

    // SUBMIT moves OPEN to REVIEW; if Register fails, DECLINE takes the ticket to FAILED
    @TicketsGraph.Transition(
        id = TicketTransition.SUBMIT,
        from = TicketState.OPEN,
        to = TicketState.REVIEW,
        action = TicketActionsRefs.Register.class,
        guards = TicketActionsRefs.HasTitle.class,
        onFailure = TicketTransition.DECLINE)
    Outcome<Ticket, TicketState, TicketTransition> submit(Ticket ticket);

    // APPROVE and AUTO_APPROVE are parallel edges: same states, each with its own action
    @TicketsGraph.Transition(
        id = TicketTransition.APPROVE,
        from = TicketState.REVIEW,
        to = TicketState.DONE,
        action = TicketActionsRefs.Approve.class)
    Outcome<Ticket, TicketState, TicketTransition> approve(Ticket ticket);

    @TicketsGraph.Transition(
        id = TicketTransition.AUTO_APPROVE,
        from = TicketState.REVIEW,
        to = TicketState.DONE,
        action = TicketActionsRefs.AutoApprove.class)
    Outcome<Ticket, TicketState, TicketTransition> autoApprove(Ticket ticket);

    @TicketsGraph.Transition(
        id = TicketTransition.RETOUCH,
        from = TicketState.REVIEW,
        to = TicketState.REVIEW,
        action = TicketActionsRefs.Retouch.class)
    Outcome<Ticket, TicketState, TicketTransition> retouch(Ticket ticket);

    @TicketsGraph.Transition(
        id = TicketTransition.REJECT,
        from = TicketState.REVIEW,
        to = TicketState.OPEN)
    Outcome<Ticket, TicketState, TicketTransition> reject(Ticket ticket);
}

APPROVE and AUTO_APPROVE are two edges between the same pair of states, each with its own action. They are parallel edges, not duplicates: approve(ticket) can never run autoApprove's action. RETOUCH is a self-loop, an ordinary edge that happens to end where it started, and REJECT closes the OPEN → REVIEW → OPEN loop. allowsCycle marks both cycles as intentional: each passes through REVIEW, so REVIEW alone would be enough, and OPEN may be listed too because it lies on one. DECLINE has no method of its own: it is the route SUBMIT names in onFailure, and it is resolved from SUBMIT's origin.

TicketsGraph, TicketRefs and TicketActionsRefs do not exist in handwritten source. The generator writes them before javac compiles this interface, using @GenerateGraphApi, Machine<Ticket, TicketState, TicketTransition> and the marked members. See the first-generation walkthrough for the minimal-interface and complete-source workflows. Do not create placeholder versions of these classes.

TicketMachines.java

package com.example.tickets;

import io.github.graphmaquina.annotation.StateGraphs;
import io.github.graphmaquina.api.Machines;

@StateGraphs
public interface TicketMachines extends Machines {
    Tickets tickets();
}

The processor generates TicketsRuntime and TicketMachinesRuntime. The set owns the runtime machines and closes their default executors together.

App.java

package com.example.tickets;

import io.github.graphmaquina.api.Outcome;
import io.github.graphmaquina.api.OutcomeCode;
import io.github.graphmaquina.api.OutcomeStatus;
import java.util.List;
import java.util.Optional;

public final class App {
    private App() { }

    public static void main(String[] args) {
        TicketActions actions = new TicketActions();
        try (TicketMachines machines = TicketMachinesRuntime.builder(actions).build()) {
            Tickets tickets = machines.tickets();

            Ticket accepted = new Ticket("T-1", "Document the workflow", true);
            require(
                tickets.submit(accepted).status() == OutcomeStatus.APPLIED,
                "submit should apply");
            require(
                tickets.approve(accepted).status() == OutcomeStatus.APPLIED,
                "approve should apply");
            require(accepted.getState() == TicketState.DONE, "an approved ticket should be DONE");

            Ticket untitled = new Ticket("T-2", "", true);
            require(
                tickets.submit(untitled).code() == OutcomeCode.GUARD_REJECTED,
                "blank title should reject");
            require(
                untitled.getState() == TicketState.OPEN,
                "a rejected ticket should remain OPEN");

            // the board refuses T-3: register fails and DECLINE commits FAILED
            Ticket refused = new Ticket("T-3", "Await the board", false);
            Outcome<Ticket, TicketState, TicketTransition> declined = tickets.submit(refused);
            require(
                declined.code() == OutcomeCode.FAILURE_ROUTED
                    && declined.explanation().equals(
                        Optional.of("the review board declined the ticket")),
                "a decline should be handled");
            require(
                refused.getState() == TicketState.FAILED,
                "the failure route should commit FAILED");

            // OPEN has no APPROVE edge, so the Reject reason answers
            Ticket fresh = new Ticket("T-4", "Not submitted yet", true);
            Outcome<Ticket, TicketState, TicketTransition> refusal = tickets.approve(fresh);
            require(
                refusal.code() == OutcomeCode.NO_TRANSITION
                    && refusal.explanation().equals(Optional.of("approval requires review")),
                "APPROVE leaves no edge from OPEN");

            Ticket revised = new Ticket("T-5", "Revise the wording", true);
            tickets.submit(revised);
            require(
                tickets.retouch(revised).status() == OutcomeStatus.APPLIED,
                "a self-loop should apply");
            require(revised.getState() == TicketState.REVIEW, "a self-loop ends where it started");
            require(
                tickets.reject(revised).status() == OutcomeStatus.APPLIED,
                "reject should apply");
            require(revised.getState() == TicketState.OPEN, "reject returns the ticket to OPEN");

            Ticket automatic = new Ticket("T-6", "Trivial typo fix", true);
            tickets.submit(automatic);
            require(
                tickets.autoApprove(automatic).status() == OutcomeStatus.APPLIED,
                "autoApprove should apply");
            require(
                actions.decisions().equals(
                    List.of("approve T-1", "retouch T-5", "autoApprove T-6")),
                "each operation runs its own action: " + actions.decisions());
            System.out.println("All ticket scenarios passed.");
        }
    }

    private static void require(boolean condition, String message) {
        if (!condition) {
            throw new IllegalStateException(message);
        }
    }
}

Expected application output:

Committed T-1: OPEN -SUBMIT-> REVIEW
Committed T-1: REVIEW -APPROVE-> DONE
Committed T-3: OPEN -DECLINE-> FAILED
Committed T-5: OPEN -SUBMIT-> REVIEW
Committed T-5: REVIEW -RETOUCH-> REVIEW
Committed T-5: REVIEW -REJECT-> OPEN
Committed T-6: OPEN -SUBMIT-> REVIEW
Committed T-6: REVIEW -AUTO_APPROVE-> DONE
All ticket scenarios passed.

One afterCommit on Definition is the default hook of every edge, so each committed hop prints itself, including the self-loop and the failure route. Nothing prints for T-2, whose guard rejected, or for T-4, whose request had no edge: neither committed anything. The program checks an applied edge, a guard rejection, a handled failure, a request with no edge, a self-loop, a cycle and two parallel edges. It does not rely on Java assertions being enabled.

What one call does

Every operation resolves one edge and runs it. For tickets.submit(ticket) the edge keyed by (OPEN, SUBMIT) leads to REVIEW, and its guard and action decide which of three outcomes the caller gets:

committed hookTicketregister actionhasTitle guardtickets facadeAppcommitted hookTicketregister actionhasTitle guardtickets facadeAppSUBMIT is discarded and DECLINE is resolved from OPENalt[the board accepts the ticket, as for T-1][the board declines it, as for T-3]alt[the title is blank, as for T-2][the title is present]submit(ticket)getState() is OPENhasTitle(ctx)GuardResult.reject("a ticket needs a title")Rejected, code GUARD_REJECTED, the ticket stays OPENGuardResult.pass()register(ctx)ActionOutcome.ok()setState(REVIEW)committed(ticket, OPEN -SUBMIT-> REVIEW)Applied, code APPLIEDActionOutcome.failed("the review board declined the ticket")setState(FAILED)committed(ticket, OPEN -DECLINE-> FAILED)Failed, code FAILURE_ROUTED, movedTo FAILED
committed hookTicketregister actionhasTitle guardtickets facadeAppcommitted hookTicketregister actionhasTitle guardtickets facadeAppSUBMIT is discarded and DECLINE is resolved from OPENalt[the board accepts the ticket, as for T-1][the board declines it, as for T-3]alt[the title is blank, as for T-2][the title is present]submit(ticket)getState() is OPENhasTitle(ctx)GuardResult.reject("a ticket needs a title")Rejected, code GUARD_REJECTED, the ticket stays OPENGuardResult.pass()register(ctx)ActionOutcome.ok()setState(REVIEW)committed(ticket, OPEN -SUBMIT-> REVIEW)Applied, code APPLIEDActionOutcome.failed("the review board declined the ticket")setState(FAILED)committed(ticket, OPEN -DECLINE-> FAILED)Failed, code FAILURE_ROUTED, movedTo FAILED

A request with no edge from the current state, such as approve on the OPEN ticket T-4, runs no guard and no action: the state's policy answers with NO_TRANSITION and its reason. Handle transition outcomes covers every variant.

Test your machines

Test through generated facades using real entities and deterministic action dependencies. The quickstart's App is an executable smoke test that covers an applied edge, a guard rejection, a handled failure, a request with no edge, a self-loop, a cycle and two parallel edges, and OrderFlowTest shows JUnit tests for payment, retries, cascades, watches, journals, and the flow and the trail of a call.

The test below reads its outcome with graphmaquina-test, the module that holds the typed assertions. Every release publishes it with the runtime, at the same version, and settings.gradle.kts already resolves it. For a Gradle application using JUnit, add to build.gradle.kts:

dependencies {
    testImplementation(platform("org.junit:junit-bom:5.13.4"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
    testImplementation("io.github.graphmaquina:graphmaquina-test:$graphmaquinaVersion")
}

tasks.test {
    useJUnitPlatform()
}

Create src/test/java/com/example/tickets/TicketsTest.java:

package com.example.tickets;

import static io.github.graphmaquina.test.GraphAssertions.assertThat;

import org.junit.jupiter.api.Test;

class TicketsTest {
    @Test
    void aDomainFailureCommitsItsDeclaredFailureState() {
        try (TicketMachines machines = TicketMachinesRuntime.builder(new TicketActions()).build()) {
            Ticket ticket = new Ticket("T-7", "Declined at intake", false);
            assertThat(machines.tickets().submit(ticket)).isFailed()
                    .hasTarget(TicketState.REVIEW)
                    .hasFailureTransition(TicketTransition.DECLINE)
                    .movedTo(TicketState.FAILED)
                    .hasEntityState(Ticket::getState, TicketState.FAILED);
        }
    }
}

isFailed() narrows the outcome and fails with the kind it actually got. hasTarget is where SUBMIT was heading, hasFailureTransition is the identifier of the edge that recovered, movedTo is where that edge landed, and hasEntityState reads the entity itself. Run ./gradlew test in your application. The repository's ReadmeQuickstartTest extracts these literal Gradle blocks and Ticket Java files, generates and compiles the main sources, runs App and checks that its output contains All ticket scenarios passed., and verifies this named JUnit test and its result counts in an external Gradle consumer using locally staged artifacts. This verifies the Gradle workflow; it does not execute this JUnit sample through Maven. This test consumes generated main code; it does not declare test graphs and needs no testAnnotationProcessor. In Maven, add JUnit and a compatible test runner through your application's usual test configuration, together with the test-scoped graphmaquina-test dependency shown in the testing guide. Preserve the graph generation lifecycle for any test graphs.

The testing guide covers every assertion, probe, recorder and snapshot graphmaquina-test offers.


Next: Code generation and IDE setup. Back to the documentation index.