Assignment 2 — Interlocking Implementation

This repository contains a single-threaded implementation of the Interlocking interface together with a minimal command-line demo and a suite of JUnit 4 tests. The goal is to model a small rail corridor using the rules laid out in the assignment brief: legal entry/exit points, passenger vs freight subnets, crossing priority, merge fairness, and deadlock detection.

---

Project Layout

.
├── Interlocking.java            # Provided interface
├── InterlockingImpl.java        # Implementation submitted for marking
├── Main.java                    # Simple CLI demo (default package)
├── *.java                       # Default-package unit tests (JUnit 4)
└── docs/
    ├── design-notes.md          # Narrative design and topology summary
    └── progress/                # Daily progress logs

All source files live in the default package to match the marking harness. No build tool is required; everything compiles with javac on JDK 11.

---

Building

1. Ensure you have a Java 11 JDK on your PATH.

2. Compile the implementation, demo, and tests:

   javac -source 11 -target 11 -cp junit.jar:hamcrest.jar -d out @sources.txt

   The sources.txt file is generated by the compile scripts and lists every Java source (implementation plus tests).

---

Running the Demo

The demo exercises the crossing priority rules and prints a small trace to stdout:

java -cp out Main

You can optionally pass demo (the default) or any other token; unsupported arguments produce a short usage hint.

---

Test Suite

Unit tests are written against JUnit 4.13.2 with Hamcrest 1.3. To execute the entire suite:

java -cp "out:junit.jar:hamcrest.jar" \
     org.junit.runner.JUnitCore \
     BasicFlow_Test \
     MovePhase1_Test \
     PriorityAndCrossing_Test \
     CrossingConflict_Test \
     FairMerge_Test \
     NoEnabledMoves_Test \
     DeadlockHandling_Test \
     OccupancyLocks_Test \
     RoutingRules_Test \
     Main_Test

The test names align with the assignment rubric (routing, crossing priority, merge fairness, deadlock detection, etc.). Main_Test is a smoke test that ensures the CLI driver compiles and runs without throwing.

---

Implementation Highlights

• Routing: Legal paths are precomputed by BFS within each subnet (passenger vs freight) based on the simplified adjacency (single-direction itineraries listed in design-notes.md).
• Crossing priority: Only one crossing move is granted per tick; passenger trains win against freight when both request the diamond simultaneously.
• Fair merges: Sections 6 (passenger northbound funnel) and 7 (freight bi-directional funnel) use round-robin queues to avoid starvation.
• Exit handling: Trains vacate only when their destination is an official exit (2,3,4,8,9,11); otherwise they remain in place. Exit-ready trains still hold the block until the rest of the tick’s arbitration completes.
• Outcome diagnostics: getLastOutcome() reports PROGRESS, BLOCKED, or DEADLOCK, with policy-only stalls classified as BLOCKED.

For a deeper explanation, see docs/design-notes.md.

Notes

• All code stays in the default package to interoperate with the marking scripts.
• No external dependencies beyond JUnit/Hamcrest are required.
• The docs/progress/ folder documents daily changes; see the latest entry for the current submission state.