# 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).