Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017ic4b6W3VPEBweaeA5DE4n
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
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.