Files

63 lines
3.6 KiB
Markdown

# elevator
Companion code for the ankurm.com article **Low-Level Design: Elevator System in Java (State Pattern and Scheduling)**.
A tick-based elevator simulation in plain Java: a car built as a State pattern (idle, moving, doors open, maintenance), the LOOK rule that
decides where a car goes next, three dispatchers that choose which car answers a hall button (round robin, nearest car, and one that asks each
car for a forecast of its own future), and a simulation that measures them on seeded traffic. Every figure and console line in the article is
quoted from a file in `output/`, which the JUnit tests write while asserting the same numbers. There is no `docs/` folder: the explanations
live in the article itself.
## Versions
| Component | Version | Verified against |
|---|---|---|
| JDK | Temurin 25.0.5+8 (LTS) | `java -version` |
| JUnit | 6.1.3 | `junit-bom` `maven-metadata.xml` on Maven Central (latest GA) |
| Maven | 3.9.11 | `mvn -version` |
No frameworks and no runtime dependencies: everything in `src/main` is plain Java.
## Quickstart
```bash
cd elevator
export JAVA_HOME=/path/to/jdk-25 PATH="$JAVA_HOME/bin:$PATH"
./scripts/run-all.sh # runs every test and regenerates output/*.txt
```
The first Maven run must be online so the plugins land in the local cache. Every transcript is deterministic: the traffic is generated from
fixed seeds and nothing depends on the wall clock.
## The pieces
| Class | Role |
|---|---|
| `Direction`, `Stop` | UP, DOWN or NONE; a floor a car has promised to visit, tagged with the direction of the button that asked |
| `Car` | floor, heading, stops and riders; delegates every tick to its state; implements the LOOK rule and `eta()` |
| `CarState` | the State interface: `tick(car, lobby)` and `copy()` |
| `IdleState`, `MovingState`, `DoorsOpenState`, `MaintenanceState` | the four behaviours; `DoorsOpenState.open` is where people get off and on |
| `Lobby` | what a car may know about the building; `Lobby.FORECAST` is a do-nothing lobby for cloned cars |
| `Building` | floors, cars, waiting people, a dispatcher; one `tick()` moves the whole world one step |
| `Dispatcher` | chooses the car for a hall button |
| `RoundRobinDispatcher`, `NearestCarDispatcher`, `EtaDispatcher` | the three strategies |
| `Passenger`, `Arrival`, `Traffic`, `Simulation`, `Report` | people, seeded traffic, the run loop and its summary |
| `PolicyComparison`, `StarvationDemo` | FCFS, SSTF and LOOK on a bare list of floors, and the starvation case |
## Transcripts
| File | Written by | What it shows |
|---|---|---|
| `01-single-car-trace.txt` | `TraceTest` | one car, three people, one line per tick; why a DOWN button is skipped while the car goes UP |
| `02-policies.txt`, `02b-starvation.txt` | `PolicyTest` | FCFS vs SSTF vs LOOK distance; SSTF leaving one request waiting 46 ticks |
| `03-dispatchers.txt`, `03b-eta-forecast.txt` | `DispatcherTest` | three dispatchers on 120 people, two traffic shapes; a forecast that matches the real run |
| `04-maintenance.txt`, `04b-all-cars-out.txt` | `MaintenanceTest` | taking a car out of service with a rider aboard; every car out of service |
| `05-capacity.txt` | `CapacityTest` | capacity 2, five people: a full car leaves people behind and the call is re-issued |
| `06-validation.txt`, `06b-stop-outside-shaft.txt` | `ValidationTest` | the exact message for each refused request |
| `07-invariants.txt` | `InvariantsTest` | 900 randomised runs, rules checked after every tick |
| `08-nearest-car-trap.txt`, `08b-same-button.txt` | `PitfallsTest` | the nearest-car trap; five people, one hall call |
## License
MIT — see [LICENSE](../LICENSE).