jfsm/README.in at develop · io7m-com/jfsm · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

## Repository Relocation

Development of this project has moved to an
[open-source but not open-contribution](https://sqlite.org/copyright.html#notopencontrib)
model.

Source code and commits will remain publicly available perpetually, but issues
and/or pull requests will be rejected and/or ignored. Additionally, this project
will now only be available via a read-only mirror at:

  https://codeberg.org/io7m-com/jfsm


## jfsm

The `jfsm` package provides implementations of finite state machines.

## Features

* Mutable enum-based finite state machines.
* Written in pure Java 17.
* High coverage test suite.
* [OSGi-ready](https://www.osgi.org/).
* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System).
* ISC license.

## Usage

Declare a type that will be used to represent the states of the FSM.
An `enum` type or a `sealed` hierarchy is a good choice.

```
enum TrafficLight
{
  RED,
  YELLOW,
  GREEN
}
```

Declare the allowed state transitions and build an FSM:

```
final FSMEnumMutableBuilderType<TrafficLight> b =
  FSMEnumMutable.builder(TrafficLight.RED);
b.addTransition(TrafficLight.RED, TrafficLight.YELLOW);
b.addTransition(TrafficLight.YELLOW, TrafficLight.GREEN);
b.addTransition(TrafficLight.GREEN, TrafficLight.YELLOW);
b.addTransition(TrafficLight.YELLOW, TrafficLight.RED);
var fsm = b.build();
```

Execute transitions:

```
assert TrafficLight.RED == m.current();

m.transition(TrafficLight.YELLOW;
assert TrafficLight.YELLOW == m.current();

m.transition(TrafficLight.GREEN;
assert TrafficLight.GREEN == m.current();

m.transition(TrafficLight.YELLOW;
assert TrafficLight.YELLOW == m.current();

m.transition(TrafficLight.RED;
assert TrafficLight.RED == m.current();

m.transition(TrafficLight.YELLOW;
assert TrafficLight.YELLOW == m.current();

m.transition(TrafficLight.GREEN;
assert TrafficLight.GREEN == m.current();

m.transition(TrafficLight.YELLOW;
assert TrafficLight.YELLOW == m.current();

m.transition(TrafficLight.RED;
assert TrafficLight.RED == m.current();

m.transition(TrafficLight.YELLOW;
assert TrafficLight.YELLOW == m.current();

m.transition(TrafficLight.GREEN;
assert TrafficLight.GREEN == m.current();
```

The FSM will throw an `FSMTransitionException` if an attempt is made to
perform a transition that is not permitted.