Files
..

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.