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

GraphMaquina

Maven Central

GraphMaquina: typed graphs, predictable transitionsGraphMaquina for Java 21. A ticket starts OPEN and takes the SUBMIT edge to REVIEW, from which APPROVE reaches DONE. When SUBMIT fails, DECLINE, its declared failure route, takes the ticket from OPEN to FAILED. GraphMaquina Typed graphs. Predictable transitions. Declare the rules. Validate at compile time. Execute through a typed Java API. JAVA 21+ TYPED API IDENTIFIED EDGES A WORKFLOW, MADE EXPLICIT OPEN REVIEW DONE FAILED SUBMIT APPROVE DECLINE, the onFailure route of SUBMIT

Typed, graph-based state machines for Java 21. Declare the transitions your domain allows as identified edges, give every state a reason for refusing the rest, and let the build validate the whole graph before the application runs.

GraphMaquina combines a pre-compilation code generator, a javac annotation processor and an in-process runtime. Your application calls a generated, typed facade. Actions, guards, hooks, properties and watched states are bound through Java symbols rather than string names.

This guide documents the latest GraphMaquina version, the API this repository builds; Maven Central publishes the modules of each release. The examples read the version from a graphmaquinaVersion Gradle property or a graphmaquina.version Maven property, set once per build, so no coordinate repeats it.

The quickstart has complete, runnable files. Most later examples extend it or quote the repository's example module, whose shop and billing domains the guide uses. The documentation index lists every page and maps tasks to the page that covers them.

Contents

What GraphMaquina provides

Capability How it works
A graph of identified transitions You declare edges (from, transition, to). An identifier selects the edge, so parallel edges and self-loops are ordinary declarations.
Compile-time structural validation Checks include reachability, terminal states, intentional cycles, duplicate (from, id) keys, failure routes, watch rules and sub-machine bindings.
Typed operations A machine interface exposes domain operations such as submit(ticket) or pay(order), returning Outcome<E, S, T>.
Explicit bindings Generated Refs classes identify marked methods and properties; the processor checks their roles and signatures.
Synchronous and asynchronous actions Actions and guards may return values or CompletionStage results. The runtime waits under configured deadlines.
Coordinated state changes Cascades share a unit of work; entity state setters run after the root transition succeeds or selects a handled failure route.
Declared watches After a peer commits, a matching owner can be reevaluated and execute the identifier the first matching rule names.
Sub-machines A state can hold another machine. Entering the state starts the child at its initial state, a call to a child whose parent does not hold it there is rejected, and the step that ends the child runs the parent's exit in the same unit of work. See compose machines.
Reasoned refusals Every node carries a policy: a request refused because no edge leaves the current state under its identifier gets the reason that state's policy gives.
Eligibility checks A facade can declare a check of an operation, and a StateMachine checks any identifier: the check runs the operation's admission, its guards included, without its action, and answers whether the operation would be admitted for an entity now, or with the reason it would be refused. See check an operation before you call it.
Inspectable execution Outcomes carry transition records, watch reactions, the sub-machines a call started and the call's flow; technical aborts carry diagnostic details where applicable.
Call logs Each call can log its start, the hops and sub-machine starts it committed, and how it ended, at DEBUG, and each step it took, at TRACE, through System.Logger; off by default. An eligibility check logs its start and its verdict, or its failure, at DEBUG, and its step at TRACE, under lines of its own. See debug a call.
The call's flow Actions put typed values in a flow that every step of the same call reads, guards, cascaded steps and the exits of sub-machines included, along with the entity the call was made for. A failure route drops the writes of the step that failed. Post-commit hooks that take a CommitContext read and write it too, so a value can reach the entity only once the call commits. With recordTrail, the flow also lists the hops and sub-machine starts the call took, each with the instant it took it, and, when the call is rejected or throws, how it ended. The caller receives it frozen, in the outcome or in the call's failure. See the call's flow.
Graph inspection Read the declared edges from the definition or export a deterministic Graphviz state diagram, which draws each sub-machine inside the state it is bound to.

GraphMaquina manages state transitions in objects you supply. It does not provide a database, entity locking, a durable job queue, HTTP endpoints or distributed transactions. See persistence and concurrency for the responsibilities that remain with your application.

The build and runtime have separate jobs:

From Java declarations to a typed runtimeBuild-time generation produces vocabulary and a manifest; javac validates and emits facades; completion publishes exports. Only core is an application dependency. GRAPHMAQUINA / BUILD PIPELINE From declarations to a running machine The build resolves and validates the graph before application code calls it. 01 Declare Entities + state enums Machine interfaces 02 Generate Typed vocabulary Symbols + manifest 03 Compile javac + processor Validate + emit facades 04 Complete Accepted export index Seal owned outputs BUILD TIME RUNTIME Application → typed facade → graphmaquina-core → entity state Generator + processor stay on the build path. Completion publishes META-INF/graphmaquina/exports.json.

At runtime, one call travels through these parts, all in your process:

tickets.submit(ticket)

guards, then the action

commit through the state setter

after a commit

at the start and end of every call

Outcome

Your application

Generated facade
TicketsRuntime

Runtime
graphmaquina-core

Your bindings
TicketActions

Your entity
Ticket

Hooks and watch reactions

Observers

tickets.submit(ticket)

guards, then the action

commit through the state setter

after a commit

at the start and end of every call

Outcome

Your application

Generated facade
TicketsRuntime

Runtime
graphmaquina-core

Your bindings
TicketActions

Your entity
Ticket

Hooks and watch reactions

Observers

Visual guide

Follow the pictures for an overview, then use the linked sections for declarations, commands and complete examples. Each illustration is an SVG: open it to inspect labels at full size.

Question Diagram Read next
What does GraphMaquina do? Typed graphs, predictable transitions What GraphMaquina provides
What runs at build time, and what at runtime? From declarations to a running machine Generation lifecycle
How can my source use annotations that do not exist yet? Source → vocabulary → compilation First generation
Which transitions are permitted? The ticket graph Understand the graph
Why did an operation apply, reject or fail? Edge selection, outcomes and where a check stops Outcomes
Which thread waits for my service? Direct call and async submission Calling styles
How much time is left for an action? Root and action deadline timeline Deadline rules
What happens if the service finishes too late? Timeout and late completion Cancellation
What can I safely use in a callback? Context and thread boundary Context ownership
Does a completed future mean the operation succeeded? Future result branches Result handling
Do both machines commit together? Cascade versus watch Machine coordination
When does an owner react to its peers? Watch reactions Watch other machines
How does a state hold a whole machine? Sub-machine binding Compose machines
When do hooks and reactions run? Commit lifecycle Commit and hooks
What does a call share between its steps, and what does its caller get back? One call's flow The call's flow

Requirements and artifacts

Module Coordinates / plugin ID Add it to
Runtime and public annotations io.github.graphmaquina:graphmaquina-core Application dependencies
Pre-compilation generator io.github.graphmaquina:graphmaquina-codegen Build tooling; the Gradle plugin resolves it, and the Maven plugin and the processor depend on it
Annotation processor io.github.graphmaquina:graphmaquina-processor javac annotation-processor path
Typed testing assertions and probes io.github.graphmaquina:graphmaquina-test Test dependencies
Gradle plugin plugin ID io.github.graphmaquina Gradle plugins block
Maven plugin io.github.graphmaquina:graphmaquina-maven-plugin Maven build plugins
Reference application graphmaquina-example Source and tests in this repository; not an application dependency

Every coordinate takes the same version, set once as the graphmaquinaVersion Gradle property or the graphmaquina.version Maven property; the examples read it from there.

The generator and processor are build-time tools. Do not add them as application runtime dependencies. Application imports begin with io.github.graphmaquina.

Publication and verification status

GraphMaquina publishes to Maven Central under the verified namespace io.github.graphmaquina. A release contains the runtime, generator, processor, testing module, Maven plugin, Gradle plugin and Gradle plugin marker; installation shows the coordinates. Browse the published artifacts or the core artifact on Maven Central. MVNRepository is an independent index; appearing in its search results is not required for Maven or Gradle resolution. Sonatype does not control its update schedule; see the official explanation.

The repository's build checks that the examples of these pages still compile and run:

Check What it verifies
Quickstart ReadmeQuickstartTest copies the Gradle scripts of installation, pointed at artifacts the build stages locally, and the Ticket sources and test of the quickstart into an external Gradle project, compiles them with strict lint, runs App, checks that the output contains All ticket scenarios passed. and checks the TicketsTest report. It does not run the Maven configuration.
Guide fragments GuideOutcomeFragmentsTest compiles the Java blocks of outcomes, of recovery rules, of composition and of the call's flow, plus the async completion callback and the observer example, against the staged core jar.
Quotes of the example module GuideCopiesTest checks that the testing pages quote the shop's tests verbatim, that the call's flow quotes the shop's code, and that composition quotes SameEntitySubmachineTest.
Testing samples TestingGuideFragmentsTest compiles and runs the samples of the recovery, sub-machine and flow testing page against the staged core and test jars.
Maven quickstart The Maven configuration and the quickstart's sources were built with mvn clean verify and App was run, once by hand, with Maven 3.9.12 on JDK 21, against artifacts built from this repository. No automated check covers it.
Async example The runnable async ticket was built and AsyncApp was run, once by hand, through Gradle and through Maven against artifacts built from this repository, and printed the output documented below it. No automated check covers it.
IDE import IntelliJ IDEA 2026.2.3 imported the quickstart's Gradle project once, headless and then in a running IDE queried through its MCP server: it registered the generated vocabulary as a source root and the processor's output as a generated source root, resolved references into both, and renamed a binding method as the IDE workflow describes. Code completion was not exercised. No automated check covers it.

License

GraphMaquina is licensed under Apache License 2.0. See LICENSE and NOTICE.

The code emitted into a consuming project by this project's generator and annotation processor belongs to that project. The repository's license notice states that its license does not extend to that generated output.


Next: Install and configure the build. Back to the documentation index.