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

GraphMaquina documentation

GraphMaquina builds typed, graph-based state machines for Java 21. You declare the transitions your domain allows as identified edges, the build generates a typed vocabulary and validates the whole graph before the application runs, and an in-process runtime executes each call against the entities you supply.

These pages document the latest GraphMaquina version, the API this repository builds. Read them in the order below the first time; each page links the next one in that order.

Contents

Start here

Page What it covers
Overview What GraphMaquina provides, the visual guide, requirements and artifacts
Install and configure the build Gradle and Maven configuration, Lombok, test source sets, multi-module builds
Quickstart A complete, runnable ticket machine and its first JUnit test
Code generation and IDE setup What the generator writes before javac runs, the first build and the IDE workflow

Model your domain

Page What it covers
Graphs, annotations and bindings Edges, identity, self-loops, guards, policies, structural rules, operations, markers, generated names, signatures
Actions, guards and failure routes Action and guard contexts, operation input, domain failures, failsOn, recovery rules by failure kind
Handle transition outcomes The four outcome variants, status and code, records, journals, reactions and failed calls
Programmatic DSL Building a graph and a machine without annotations

Asynchronous work

Page What it covers
Asynchronous work and timeouts Asynchronous actions and guards, machine.async, a runnable async example, reading the future
Deadlines, cancellation and executors Root and edge deadlines, timeouts and late completion, contexts in callbacks, executors, async tests

Several machines

Page What it covers
Machine sets, cascades and watches Generated machine sets, peer views, cascades in one unit of work, watches after a peer commits
Compose machines Sub-machines: binding a machine to a state, parent lookups, starts, exits, interruptions, reuse

After the commit

Page What it covers
Commit, hooks, observers and persistence The commit sequence, after-commit hooks, observers, state initialization, identity, database boundaries

Observe and debug

Page What it covers
Debug a call with logs The runtime's System.Logger output at DEBUG and TRACE
The call's flow Typed values every step of a call shares, values applied only on commit, and the call's trail
Inspect graphs and export diagrams Reading a definition, Graphviz export, topology queries
Diagnostics and troubleshooting Every SG diagnostic code, runtime exceptions and common build problems

Test your machines

Page What it covers
Testing GraphMaquina machines graphmaquina-test: entry points, identity checks, goldens, snapshots, what a check does not prove
Testing samples: graphs, outcomes, probes and async Verified samples for graph, outcome, failure, recorder, probe, input and controlled async assertions
Testing samples: recovery, sub-machines and the call's flow Verified samples for recovery rules, sub-machines and the flow and trail of a call

Build tooling reference

Page What it covers
Building with the typed graph API The four build steps, where artifacts come from, the Gradle adapter
The Maven adapter The six goals, the compiler execution they read, outputs, what the adapter requires and refuses
Build troubleshooting and limits Build failures, repeated builds and renames, generator limits

Find a feature

I want to… Read
Allow two different operations between the same pair of states Identity, not destination
Explain why a state refuses an operation Policies
Pass a value from the caller to guards and actions Operations and internal edges
Turn an expected failure into a state Domain failures
Send different failures to different states Recovery rules
Map an outcome to an HTTP response Map an outcome to a response
Call a remote service from an action Asynchronous work and deadline rules
Move several entities in one unit of work Cascade a transition
React when other machines change Watch other machines
Run a whole machine inside one state Compose machines
Run code only after a transition committed After-commit hooks
Count or audit every call Observers
Share values between the steps of one call The call's flow
See what a call did, step by step Logs and the call's trail
Draw the graph Inspect graphs and export diagrams
Build a graph at runtime, without annotations Programmatic DSL
Pin a graph's structure in a test Goldens and structural snapshots
Decide in a test when an async callback answers Controlled asynchronous invocations
Understand an SG error code Diagnostics

Illustrations

Page What it covers
Documentation illustrations The SVG illustrations the pages embed, and what each one shows