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.

Version 2.0.6 on Maven Central. Apache License 2.0.

The quickstart's ticket machine: OPEN, REVIEW, DONE and FAILED, with the current state filled REJECT SUBMIT APPROVE AUTO_APPROVE RETOUCH DECLINE, the failure route of SUBMIT OPEN REVIEW DONE FAILED
  1. a new ticketOPENcall an operation to see what the machine answers

For a ticket that has a title and that the review board accepts:

In stateYou callThe machine answers
OPENsubmit(ticket)Applied OPEN -SUBMIT-> REVIEW
OPENapprove(ticket)Rejected NO_TRANSITION approval requires review
OPENautoApprove(ticket)Rejected NO_TRANSITION submit the ticket first
OPENretouch(ticket)Rejected NO_TRANSITION submit the ticket first
OPENreject(ticket)Rejected NO_TRANSITION submit the ticket first
REVIEWsubmit(ticket)Rejected NO_TRANSITION approve, reject or retouch the ticket
REVIEWapprove(ticket)Applied REVIEW -APPROVE-> DONE
REVIEWautoApprove(ticket)Applied REVIEW -AUTO_APPROVE-> DONE
REVIEWretouch(ticket)Applied REVIEW -RETOUCH-> REVIEW
REVIEWreject(ticket)Applied REVIEW -REJECT-> OPEN
DONEsubmit(ticket)Rejected NO_TRANSITION terminal state DONE accepts no transitions
DONEapprove(ticket)Rejected NO_TRANSITION terminal state DONE accepts no transitions
DONEautoApprove(ticket)Rejected NO_TRANSITION terminal state DONE accepts no transitions
DONEretouch(ticket)Rejected NO_TRANSITION terminal state DONE accepts no transitions
DONEreject(ticket)Rejected NO_TRANSITION terminal state DONE accepts no transitions
FAILEDsubmit(ticket)Rejected NO_TRANSITION terminal state FAILED accepts no transitions
FAILEDapprove(ticket)Rejected NO_TRANSITION terminal state FAILED accepts no transitions
FAILEDautoApprove(ticket)Rejected NO_TRANSITION terminal state FAILED accepts no transitions
FAILEDretouch(ticket)Rejected NO_TRANSITION terminal state FAILED accepts no transitions
FAILEDreject(ticket)Rejected NO_TRANSITION terminal state FAILED accepts no transitions

Replays the outcomes GraphMaquina 2.0.6 returned for the quickstart's ticket machine.

Install

Each coordinate resolves from Maven Central. The installation page has the full settings and build files.

Plugin
io.github.graphmaquina version 2.0.6
implementation
io.github.graphmaquina:graphmaquina-core:2.0.6
annotationProcessor
io.github.graphmaquina:graphmaquina-processor:2.0.6
Dependency
io.github.graphmaquina:graphmaquina-core:2.0.6
Annotation processor path
io.github.graphmaquina:graphmaquina-processor:2.0.6
Plugin
io.github.graphmaquina:graphmaquina-maven-plugin:2.0.6

What you write

@TicketsGraph.StatePolicy(state = TicketState.OPEN, otherwise = "submit the ticket first")
// REVIEW's policy is omitted here
@TicketsGraph.Reject(
    from = TicketState.OPEN,
    transition = TicketTransition.APPROVE,
    reason = "approval requires review")
// the DECLINE route is omitted here
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, autoApprove, retouch and reject are omitted here
}
  1. A reason for refusingOPEN answers the calls it does not accept with the reason you wrote.
  2. An identified edgeSUBMIT is a name you chose, not a pair of states.
  3. A failure routeWhen the action fails, the ticket takes DECLINE to FAILED.