Java-StateCharts

This repository contains a Java implementation of the UML Statechart Framework together with a number of example applications. The project is organised as a multi module Maven build and demonstrates how statecharts can be used to model different behaviours in Java programs.

Repository layout

statechart-lib/  - Core statechart runtime library
simulation/      - Small discrete event simulator used by some examples
application/     - Example statechart based applications

The statechart-lib module provides classes such as Statechart, State, Transition and others that mirror the original framework. The simulation module contains a simple event based simulator used for scheduling timed events. All demonstration programs live under the application module.

Prerequisites

• Java 11 or newer
• Maven 3
• The examples under application depend on Log4j for logging which is resolved automatically by Maven.

To build the entire project simply run:

mvn package

After a successful build the compiled classes reside under each module's target/classes directory. Example programs can then be executed using java and the combined classpath of the three modules, e.g.

java -cp application/target/classes:statechart-lib/target/classes:simulation/target/classes <MainClass>

Replace <MainClass> with the class of the example you want to run.

Simulation modes

The simulation module contains helper classes for running a statechart either in real time or with a simulated clock. The SimFactory class exposes three factory methods:

• getWallclockSim() – executes events according to the system wall clock.
• getDiscreteSim(long initTime) – uses a DiscreteTimeProvider where time only advances when you manually call advanceTime. Useful for deterministic tests.
• getAcceleratedSim(long initTime, double factor) – runs in real time but with the clock sped up by the given factor.

All example applications create a wall clock simulator, but any of these modes can be substituted to change how time progresses during execution.

Example applications

AcademicExample

dk.sdu.mmmi.academic_example.AcademicExample implements the statechart found in the original framework documentation. It prints messages as the machine transitions between states. A typical snippet of the output looks like:

B active
D active
E active
E -> F
F active

HierarchicalFizzBuzzExample

dk.sdu.mmmi.fizzbuzz_example.HierarchicalFizzBuzzExample is an implementation of the statecharts.dev fizzbuzz example. It uses hierarchical states and prints the generated fizz/buzz sequence. Running the example prints lines similar to:

2025-07-25T11:58:38.256917643           In state: digit_fizz_buzz
Dispatching event
...
[1, 2, Fizz, 4, Buzz, Fizz, 7, 8, Fizz, Buzz, 11, Fizz, 13, 14, FizzBuzz, ...]
Passed verification: true

ConcurrentFizzBuzzExample

dk.sdu.mmmi.fizzbuzz_example.ConcurrentFizzBuzzExample demonstrates the use of concurrent regions that synchronise to produce the fizzbuzz output. The resulting list is identical to the hierarchical example and ends with the message Passed verification: true.

Traffic light examples

Several programs model traffic light controllers of increasing complexity:

• dk.sdu.mmmi.traffic_lights_example.LightBox – a single light box cycling through red, amber, green and yellow states.
• dk.sdu.mmmi.traffic_lights_example.LightBoxNorthSouth – two light boxes running concurrently for north and south directions.
• dk.sdu.mmmi.traffic_lights_example.LightBoxNorthSouthEastWest_OneInEachDirection – four concurrent light boxes, one in each direction.
• dk.sdu.mmmi.traffic_lights_example.LightBoxNorthSouthEastWest_MultipleInEachDirection – an extended example with multiple light boxes in each direction.

These applications log trace messages such as In state: light_box_red whenever a state is entered.

OCPP K15 Smart Charging

dk.sdu.mmmi.jocpp.ocpp2_0_1.SM_K15 is a statechart describing part of the OCPP 2.0.1 charging protocol. It uses the simulator from the simulation module to schedule events and logs state transitions in the same style as the traffic light examples.

Running the examples

After compiling with Maven you can run any example using a command similar to the following:

java -cp application/target/classes:statechart-lib/target/classes:simulation/target/classes dk.sdu.mmmi.fizzbuzz_example.HierarchicalFizzBuzzExample

Substitute the class name with the desired example. When executed you should see output comparable to the snippets shown above.