Finito Finite state machines for Java

State machines that run, wire & draw themselves.

Your workflow mentor — from start to finish

Finito models a workflow as states and the events that move between them. Define it in XML, a fluent Java API, or JSON; add actions, hooks and persistence by convention; and get a Mermaid & PlantUML diagram for free.

Part of the Chenile group Runs standalone — plain Java, no framework required org.chenile.stm
Build a flow → See auto-diagrams View source
define → STM.proceed(entity, event) → actions · auto-persist · post-save hooks · diagrams
The idea

A workflow is a set of states and the events that move between them

Your entity carries its own state; one call — STM.proceed(entity, event, payload) — advances it, running every action, guard and hook along the way.

🟢

States

Manual states wait for an event. Auto states decide their own next move by evaluating a condition on the data.

⚡

Events & transitions

An <on> maps an eventId to a newStateId and an optional action. That's the whole grammar of movement.

📦

State entities

Your object extends StateEntity and carries its current state. Finito persists it for you and can fire hooks after every save.

Much more than XML

Three ways to define the same flow

XML is convenient and reviewable — but it's only one door. Build a flow with a fluent Java API, or load it from JSON. Same engine, same diagrams, your choice of source.

returns-states.xml
<states>
  <flow id='returns-flow' default='true'>
    <entry-action componentName="returnsEntryAction"/>
    <manual-state id='REQUESTED' initialState='true'>
      <on eventId='approve' newStateId='APPROVED' componentName='ApproveReturn'/>
      <on eventId='reject'  newStateId='REJECTED'/>
    </manual-state>
    <auto-state id='INSPECTION' code='payload.condition'>
      <on eventId='ok'      newStateId='REFUNDED'/>
      <on eventId='damaged' newStateId='REJECTED'/>
    </auto-state>
  </flow>
</states>
ReturnsFlow.java — fluent construction (FluentFlowReader)
new FluentFlowReader(store)
  .newFlow("returns-flow").makeDefault()
    .entryAction(new ReturnsEntryAction())
    .manualState("REQUESTED", true)
      .on("approve").transitionAction(new ApproveReturn()).transitionTo("APPROVED").state()
      .on("reject").transitionTo("REJECTED").state()
      .flow()
    .manualState("APPROVED")
      .on("ship").transitionTo("LABEL_SENT").state()
      .flow()
    .autoState("INSPECTION")
      .component(new IfAction<>())
      .property("condition", "payload.condition")
      .on("ok").transitionTo("REFUNDED").state()
      .on("damaged").transitionTo("REJECTED").state()
      .flow()
    .manualState("REFUNDED");
returns-flow.json — flows serialize to / from JSON
{
  "id": "returns-flow",
  "defaultFlow": true,
  "states": [
    { "id": "REQUESTED", "manualState": true, "initialState": true,
      "transitions": [
        { "eventId": "approve", "newStateId": "APPROVED", "componentName": "ApproveReturn" },
        { "eventId": "reject",  "newStateId": "REJECTED" }
      ]},
    { "id": "INSPECTION", "automaticState": true, "code": "payload.condition",
      "transitions": [
        { "eventId": "ok",      "newStateId": "REFUNDED" },
        { "eventId": "damaged", "newStateId": "REJECTED" }
      ]}
  ]
}
One model underneath
XML, the fluent API and JSON all populate the same in-memory flow model in the STMFlowStore. Pick whichever fits — generate flows programmatically with the fluent API, ship them as JSON from a config service, or keep them as reviewable XML.
A flow, at a glance

The returns workflow — watch it run

However you defined it, this is the machine. Below it animates: an entity walks its states as events fire; the auto state routes itself. Under that, the same flow as a static reference.

An entity walks its states as events fire. Press Play.
start manual state auto state (decides itself) terminal state
manual · initialREQUESTED
approve
manualAPPROVED
ship
manualLABEL_SENT
receive
auto · inspectINSPECTION
ok
terminalREFUNDED
damaged
terminalREJECTED

REQUESTED also goes to REJECTED on reject. The auto state INSPECTION evaluates the item's condition and routes itself — no event from the caller.

Everything hangs off the flow

Actions, hooks and persistence — where they belong

A single transition can run a transition action, land in a new state whose entry action fires, persist the entity automatically, and trigger post-save hooks. You declare it; Finito orchestrates it.

⚡

Event

proceed(entity, "approve")

→
🧩

Transition action

runs your business logic

→
🚪

Entry action

state entered · SLA/timestamps set

→
💾

Auto-persist

entityStore.store() → Spring repo

→
🪝

Post-save hook

notify · integrate · audit

🧩

Transition actions

Attach a component to an <on> to run code when an event fires — validate, call a service, mutate the entity. It implements STMTransitionAction.

🚪

Entry & exit actions

Run logic as a state is entered or left. The built-in GenericEntryAction stamps state-entry time and SLA fields, then persists — so timing and storage are automatic.

🔀

Auto states

An auto-state evaluates an OGNL expression on the entity and picks its own transition — decisions live in the flow, resolved by an STMAutomaticStateComputation.

🪝

Post-save hooks

PostSaveHook.execute(start, end, entity, payload) fires after the entity is stored on a transition — the safe place to publish events, notify or integrate.

💾

Automatic persistence

State is saved through an EntityStore that wraps your Spring repository — entering a state stores the entity with no explicit save call in your code.

🔐

Guards & policies

Attach a security-strategy with meta-acls permissions to events, or an enablement-strategy to switch transitions on and off by configuration.

Convention over configuration

Wired to Spring automatically — by name, not by boilerplate

You rarely wire components by hand. Finito's resolver finds your transition actions, auto-state computations and post-save hooks in the Spring context (or any bean factory) using a naming convention built from a prefix, the event or state, and a type suffix.

how a bean name is resolved
// STMTransitionActionResolver
beanName = prefix + Capitalize(eventId) + suffix

// suffix by component type
TRANSITION_ACTION  ->  "Action"
POST_SAVE_HOOK     ->  "PostSaveHook"
AUTO_STATE         ->  "AutoState"

// for a "returns" workflow, event "approve":
returnsApproveAction        // transition action
returnsAssignedPostSaveHook // hook on the ASSIGNED state
returnsInspectionAutoState  // auto-state computation

How the resolver works

  • It first tries an entity-qualified name (prefix + Entity + Event), then falls back to prefix + Event.
  • A context prefix can override per tenant — e.g. a header x-tenant selects a tenant-specific bean, enabling per-tenant actions and hooks.
  • If nothing matches, an optional default action is used — so you only write the components that differ.
  • Any Spring bean with the right name is picked up automatically — no explicit wiring in the flow.
Look at the returns codebase
In the generated returns service, the resolver is configured with the workflow prefix; dropping a Spring bean named returnsApproveAction (or a tenant-scoped variant) is all it takes to hook business logic onto the approve event. The same convention discovers post-save hooks and auto-state computations.
Automatic diagrams

Your diagram is generated — never hand-drawn, never stale

Finito reads the flow and emits state diagrams in both Mermaid and PlantUML. Main-path, auto and orphaned states are colour-coded automatically, so the picture always matches the running machine.

📄

your flow

XML · fluent · JSON

→
⚙️

Finito generators

StmPumlGenerator · STMMermaidGenerator

→
🌊

Mermaid

stateDiagram-v2 · renders on the web

🌱

PlantUML

.puml · for docs & CI

returns.mmd · generated Mermaid
stateDiagram-v2
  classDef mainPath fill:Bisque,stroke:Peru,stroke-width:4px;
  classDef autoState fill:PaleGreen,stroke:green,stroke-width:2.5px;
  [*] --> REQUESTED
  REQUESTED --> APPROVED : approve
  REQUESTED --> REJECTED : reject
  APPROVED --> LABEL_SENT : ship
  LABEL_SENT --> INSPECTION : receive
  state INSPECTION <<choice>>
  INSPECTION --> REFUNDED : ok
  INSPECTION --> REJECTED : damaged
  class REQUESTED mainPath
  class INSPECTION autoState
returns.puml · generated PlantUML
@startuml
[*] --> REQUESTED
REQUESTED --> APPROVED : approve
REQUESTED --> REJECTED : reject
APPROVED --> LABEL_SENT : ship
LABEL_SENT --> INSPECTION : receive
state INSPECTION <<choice>>
INSPECTION --> REFUNDED : ok
INSPECTION --> REJECTED : damaged
@enduml

Live Mermaid render of the code above ↓

stateDiagram-v2
  [*] --> REQUESTED
  REQUESTED --> APPROVED : approve
  REQUESTED --> REJECTED : reject
  APPROVED --> LABEL_SENT : ship
  LABEL_SENT --> INSPECTION : receive
  state INSPECTION <<choice>>
  INSPECTION --> REFUNDED : ok
  INSPECTION --> REJECTED : damaged
Trajectories

Run a different flow behaviour — without branching

A trajectory is an ephemeral, per-request variant selected by the header x-chenile-trajectory-id. Because Finito resolves its transition actions and auto-states by convention, a trajectory can point an event at a different action or auto-state computation — no if statements, nothing to untangle later.

request— no trajectory header —
Pick a trajectory — or press Play — to see the resolver pick a different bean.
Same idea, framework-wide
In the full Chenile framework a trajectory also swaps the service implementation (@ConditionalOnTrajectory) and returns different configuration values — read the Trajectories chapter on chenile.org.
Advanced workflow features

More than states and transitions

Real business workflows need checklists, feature toggles, permissions, introspection and their own vocabulary. Finito builds all of these into the same declarative flow.

✅

Activities & completion checks

Tag transitions as mandatory or optional activities (meta-activity="MANDATORY"). An automatic activity-checker state (e.g. AreClosedActivitiesComplete) blocks progress until every mandatory activity for a status is done — so a workflow can't advance with work outstanding.

🎚️

Enablement

Attach an enablement-strategy (e.g. a config-based one) to switch transitions on and off by configuration — feature flags for your workflow, per module, tenant or deployment, without touching the XML.

🔐

Security on transitions

Add a security-strategy and attach meta-acls permissions to individual events. The permission is checked before the action runs — authorization lives in the flow, next to the transition it guards.

🔎

Runtime introspection

Generated workflow services expose an admin info API under /{service}/info/… — render the live state diagram, list the allowed actions for an entity, return the workflow as JSON, and fetch generated test cases.

🧬

Extend the DSL

Define your own vocabulary with add-state-tag / add-transition-tag. A custom <status> or <on-action> tag expands into the underlying states and transitions — so flows read in your domain language.

⏱️

SLA & timing

Entry actions stamp state-entry time and compute SLA fields (late / getting-late) from the flow metadata, so dashboards and escalations have the timing data they need without extra code.

a custom DSL — states.xml (excerpt)
<!-- define the vocabulary once… -->
<add-state-tag tag="status" manualState="true"/>
<add-transition-tag tag="on-action" eventIdTag="id" newStateIdTag="move-to"/>
<add-transition-tag tag="mandatory-activity" meta-activity="MANDATORY" eventIdTag="id"/>

<!-- …then write the flow in your own words -->
<status id='OPENED' initialState='true'>
  <on-action id='assign' move-to='ASSIGNED'/>
  <mandatory-activity id='attachDocuments'/>
</status>

These features are generated and wired by the wfcustom blueprint. In the full Chenile framework they compose with security, multi-tenancy and messaging.

The blueprint · jgen

From one flow to a running workflow service

Finito ships an inbuilt blueprint — bp-wfcustom — that jgen expands into a complete Chenile service: an -api and a -service module wired to your state machine, with persistence, tests and diagrams.

📄

your flow

+ a few answers

→
🧬

jgen · bp-wfcustom

the inbuilt blueprint

→
📘

returns-api

StateEntity + StateEntityService<T>

⚙️

returns-service

actions, hooks, config, BDD tests

🖼️

diagrams

Mermaid + PlantUML

Standardised contract
Your entity extends AbstractStateEntity; the generated API reuses the shared StateEntityService<T> — so every workflow exposes the same verbs: process, processById, create, retrieve, getAllowedActionsAndMetadata. Toggle JPA, security, activities, enablement and the cloud switch at generation time.
Under the hood · workflow services

One HTTP call, one transition — typed, convention-wired, persisted

A generated workflow service exposes three verbs. Every event goes through the same generic engine; your code is found by name, gets a strongly typed payload, and the response tells the caller what it may do next.

the workflow REST contract
// create — starts in the initial state
POST  /returns                      { "openedBy": "USER1" }
// retrieve
GET   /returns/{id}
// fire an event — the payload type depends on the event
PATCH /returns/{id}/approve         { "comment": "looks good" }

// every call answers with
{ "payload": {
    "mutatedEntity": { …, "currentState": { "stateId": "APPROVED" } },
    "allowedActionsAndMetadata": [
      { "allowedAction": "refund", "acls": "returns.refund" },
      { "allowedAction": "inspect", "activity": "MANDATORY" } ] } }

What happens on PATCH …/approve

  1. StmBodyTypeSelector picks the payload type — explicit bodyType metadata, or the second parameter of the action's transitionTo(…).
  2. The STM fires the transition; BaseTransitionAction runs a metadata-named command or orchestration if there is one…
  3. …otherwise the resolver finds returnsApproveAction and runs your typed AbstractSTMTransitionAction.
  4. Secondary actions registered for approve (SecondSTMTransitionAction) run next, in order.
  5. GenericEntryAction stamps SLA timing, stores the entity, and calls the state's post-save hook.
  6. The response lists the allowed actions for the new state — already filtered by state and security.
🏷️

Metadata reaches the client

Every meta-* attribute on a transition comes back on its allowed action with the prefix stripped — meta-acls → acls, meta-label → label. Build buttons from it; never hard-code events.

🔎

Introspection endpoints

/{svc}/info/state-diagram, allowed-actions?state=, json, test-cases, test-visualization and test-state-diagrams expose the flow itself to consoles and tools.

🤖

Agents and grids, too

With workflow-mcp, AI agents see each event's payload variant (ProcessIdPolymorph). Workflow-backed Chenile queries return the same allowedActions per row.

Go deeper
The full convention table, every stmcmds class and the security wiring are on chenile.org: workflow service internals.
Built on Finito

Long-running processes are a Finito flow, too

Chenile Process Management orchestrates tree-shaped batch work — split a job, run the pieces, aggregate the results, chain the next job — and the orchestrator itself is a Finito state machine. Processes are rows in your database; workers raise events back into the flow.

process-states.xml — the flow
isThisLeafNode ── leaf ──────▶ EXECUTING ── doneSuccessfully ──▶ PROCESSED
       │                          └─ doneWithErrors ──▶ PROCESSED_WITH_ERRORS
       └─ non-leaf ─▶ SPLIT_PENDING ── splitDone ─▶ SUB_PROCESSES_PENDING
SUB_PROCESSES_PENDING ── child done ─▶ areAllSubProcessesDone?
   numSubProcesses == numCompletedSubProcesses && splitCompleted
          ─▶ AGGREGATION_PENDING ── aggregationDone ─▶ areThereErrors?
                                        ─▶ PROCESSED | PROCESSED_WITH_ERRORS

What Finito gives the orchestrator

  • Decision states (isThisLeafNode, areAllSubProcessesDone, areThereErrors) keep the coordination rules in the flow, not in code.
  • Entry actions launch the right worker — splitter, executor or aggregator — in-VM, over a queue, or from a durable JDBC work queue.
  • An optional transactional outbox commits each transition's consequences with the state change itself.
  • Triggers (Quartz crontabs), completion chaining, a management API and a React dashboard come with it — new in Chenile 2.1.31.
Read more on chenile.org
Process management · durable outbox · administration & dashboard · vs. Temporal
stm-cli

A command line for your state machines

stm-cli works straight off your flow — render its diagram, and even scaffold test cases that walk every transition.

terminal
# render a Mermaid state diagram
stm-cli --mermaid returns-states.xml

# generate test cases that walk every transition
stm-cli --generate-test-cases returns-states.xml

# render a state diagram for each generated test path
stm-cli --render-tests-as-state returns-states.xml
-m, --mermaid

Emit a Mermaid-compatible state diagram for the flow.

-t, --generate-test-cases

Generate test cases that exercise the machine's transitions.

-r, --render-tests-as-state

Draw a state diagram for every generated test-case path.

Where it fits

Part of Chenile — happy on its own

Finito is the state-machine core of the Chenile framework, but the engine has no framework strings attached.

🧩 Standalone engine

Drop org.chenile.stm into any Java app. Build a flow with XmlFlowReader, the FluentFlowReader API, or from JSON, then drive entities with STM.proceed(...).

  • Plain Java — no Spring, no container required
  • Pluggable strategies (scripting, security, store) with no-op defaults
  • Generate Mermaid / PlantUML from any flow with the CLI
  • Perfect for embedding a workflow inside an existing service

🟠 Within the Chenile group

Use the full workflow blueprint and get a first-class Chenile service: convention-wired actions and hooks, Spring persistence, security, activities, BDD tests and REST endpoints.

  • Generated -api + -service via jgen bp-wfcustom
  • Convention-based resolution from the Spring context
  • Shares Chenile's interceptors, registry and messaging
  • Versioned with the Chenile release train

Model your first state machine

Define a flow — in XML, Java or JSON — drive it with one call, let Finito wire and persist it, and draw the diagram for you.

Get the code Build a flow