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
- Model your domain
- Asynchronous work
- Several machines
- After the commit
- Observe and debug
- Test your machines
- Build tooling reference
- Find a feature
- Illustrations
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 |
| Check an operation before you call it | Whether an operation would be admitted now, and why not, through a facade or the DSL, without running it |
| Programmatic DSL | Building a graph and a machine without annotations |
| Automatic transitions | Edges the machine takes on its own after a commit, their order, advance, continuing failure routes, the limit and what the caller sees |
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 |
| Compose machines across modules and JARs | Watches and sub-machines over a machine of another module or jar: what the producer publishes, lookups, sets, checks |
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 and common build problems |
| Runtime exceptions | Every exception the library throws, its phase, its accessors and what to investigate |
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, automatic transitions and the call's flow | Verified samples for recovery rules, sub-machines and the flow and trail of a call, and the assertions on automatic transitions |
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 |
| Show whether an operation is available, and why not | Check an operation before you call it |
| 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 |
| Advance an entity on its own | Automatic transitions |
| 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 |
| Watch or bind a machine from another module | Compose machines across modules and JARs |
| Run code only after a transition committed | After-commit hooks |
| Count or audit every call; an eligibility check is no 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 |