Java Data Structures

A collection of 18 plain-Java console programs from CSC248 — Data Structures (UiTM, semester 3, ~2021) coursework: hand-rolled linked list / stack / queue ADTs (plus an AdtsDemo driver added in 2026), five progressive sorting-and-searching programs, and four progressively refined shortest-job-first CPU-scheduling prototypes. Preserved as written for the course, apart from the deliberate 2026 fixes noted below.

New developer? Start with .docs/tldr.md — every doc summarised on one page. The full guide lives in .docs/.

Program catalog

Program	Folder	What it does
LinkedList (+ Node)	adts/	Generic singly linked list ADT: insert front/back/after, remove front/back, keyed delete, traversal accessors, EmptyListException. No main — it is the base class of the two ADTs below. search/deleteNode compare payloads with .equals() (fixed in 2026; used to be ==/!=, see below).
Stack	adts/	Stack ADT (push/pop/peek) implemented by extending LinkedList.
Queue	adts/	Queue ADT (enqueue/dequeue/getFront/getEnd) implemented by extending LinkedList.
AdtsDemo	adts/	Driver added in 2026: exercises LinkedList/Stack/Queue end to end (insert, traverse, search, keyed delete, push/pop/peek, enqueue/dequeue, empty-pop/-dequeue). No stdin.
ProgramApp	sorting-searching/	Menu-style program: read 10 integers, bubble sort, then binary search for a value.
SortingAndSearchingV1	sorting-searching/	Bubble + insertion sort and binary search over int arrays, ascending.
SortingAndSearchingV2	sorting-searching/	Same over String arrays (case-insensitive), ascending.
SortingAndSearchingV3	sorting-searching/	Same over an array of Student objects (numbers and names sorted independently), ascending.
SortingAndSearchingV4	sorting-searching/	Int + String arrays, descending, with two binary-search variants.
SortingAndSearchingV5	sorting-searching/	Student objects, descending.
Student	sorting-searching/	Data class (name, number) used by V3/V5. No main.
Proto5	scheduling-prototypes/	First CPU-scheduling prototype: ArrayList<Job> clock-tick trace, FCFS order, no sorting.
Proto6	scheduling-prototypes/	Adds waiting-time tracking and insertion-sorting the ready queue by CPU time (SJF).
Proto7	scheduling-prototypes/	Adds per-job execute/wait bookkeeping and average executing/waiting times.
Proto8	scheduling-prototypes/	Final prototype: Proto7 with cleaned-up output (average turn-around time label, debug prints removed).
Job	scheduling-prototypes/	Data class (name, cpu time, arrival time, wait) used by Proto5–8. No main.
ForEachExample1	misc/	Tiny for-each loop demo.

Cross-reference: the finished scheduler these prototypes led to — a linked-list-based SJF simulator (mainApp with a Job-typed sorting LinkedList) — formerly lived in a standalone repo that has since been retired. These prototypes are its documented ancestors, and the lineage is preserved here: Job.java and Node.java are earlier variants of that scheduler's same-named classes (no burstTime field; generic Object payload), kept because Proto5–8 and the ADTs compile against them.

Prerequisites

Tool	Version	Installed by
PowerShell + winget	Windows 10/11 stock	— (the only true prerequisites)
Temurin JDK	11+ (21 installed if missing)	setup.ps1
Git	any recent	setup.ps1
Node.js LTS	for the Claude CLI	setup.ps1
uv + Python	latest	setup.ps1
just	any recent	setup.ps1
Claude Code CLI	latest	setup.ps1 (optional, for AI-assisted dev)

Quick start

# 1. One-time machine setup (idempotent — safe to re-run)
pwsh ./setup.ps1

# 2. Close and reopen PowerShell so PATH updates land
just list          # catalog of runnable programs
just build-all     # compile all four folders into out\
just run Proto8    # build + run one program against sample-inputs\Proto8.txt

just run <name> compiles one program and runs it with sample-inputs\<name>.txt piped as stdin (programs without a sample file run directly). Every stdin-reading program has a committed sample input — the second-Scanner defect that once made ProgramApp and SortingAndSearchingV1/V2/V4 interactive-only was fixed in 2026 (their search methods now reuse main's Scanner). These are run-to-completion CLIs — there is no server to stop.

Commands

Run just with no arguments to list every recipe. The ones you'll use daily:

Command	What it does
just list	List every runnable program (class with main), one per line
just build <name>	Compile one program (plus same-folder dependencies) into out\
just build-all	Compile every folder; fail on first error; PASS/FAIL summary
just run <name>	Build + run one program with sample-inputs\<name>.txt as stdin
just run-interactive <name>	Build + run one program with your own typed input
just test	Golden-output suite: build + run all 12 runnable programs, diff stdout vs tests\expected\
just clean	Remove compiled classes (out\)
just claudex	Launch Claude Code (Sonnet, all permissions)

Sample output

just run Proto8 — the final SJF scheduler prototype on its committed sample input (sample-inputs\Proto8.txt: job A cpu 4 arriving at 1, B cpu 1 at 2, C cpu 2 at 3; SJF picks B before C once A finishes). Prompts appear answerless because the sample file is piped as stdin; recipe echo trimmed:

Job A)
Enter cpu time = Enter arrival time =
Want to add more? - (yes/no)

Job B)
Enter cpu time = Enter arrival time =
Want to add more? - (yes/no)

Job C)
Enter cpu time = Enter arrival time =
Want to add more? - (yes/no)


Time : 1
Job A is executing ...

Time : 2
Job A is executing ...
Job B has arrived...

Time : 3
Job A is executing ...
Job B is in hold for 2 ms
Job C has arrived...

Time : 4
Job A is executing ...
Job B is in hold for 3 ms
Job C is in hold for 2 ms

Time : 5
Job B is executing ...
Job C is in hold for 3 ms

Time : 6
Job C is executing ...

Time : 7
Job C is executing ...

Time : 8
End


Average turn-around time : 4.333333333333333ms
Average waiting time : 2.0ms

Testing

just test runs the golden-output harness (tests\run-tests.ps1): for every golden in tests\expected\, it compiles the program (same-folder dependencies via -sourcepath, like just build), runs it with its committed sample-inputs\<name>.txt as stdin — or no stdin for ForEachExample1 and AdtsDemo — and diffs stdout against the golden (CRLF-normalized). A non-zero exit code fails the test even when stdout matches. One [PASS]/[FAIL] line per program, summary at the end, exit 1 on any failure.

The programs are compiled and run concurrently (ForEach-Object -Parallel, which is why this one recipe runs under pwsh), taking the suite from about 21s to about 5s. To make that safe the harness compiles each program into its own out\<Name>\ rather than the shared out\ the build recipes use — otherwise Proto5–Proto8 would race to write the same out\Job.class. Results are printed sorted by name, so the output is identical to a serial run; use just test-serial when a failure needs a clean log.

Coverage: all 12 runnable programs. The four former exclusions — ProgramApp and SortingAndSearchingV1/V2/V4 — joined the suite after their second-Scanner defect was fixed in 2026: their search methods used to build a second Scanner(System.in) that hit EOF under redirected stdin; they now reuse main's Scanner, so each has a committed sample input and golden. adts/ was the one remaining gap — it had no driver class at all — until AdtsDemo was added in 2026, along with a .equals() fix for the search/deleteNode reference-identity bug it exposed (see below). No program is excluded for nondeterminism — nothing here uses timestamps or randomness.

The adts/ identity-comparison bug (fixed 2026)

LinkedList.search/deleteNode used to compare payloads with ==/!= (reference identity) instead of .equals() (value equality). That silently failed for any String not interned to the same object, or any Integer outside the -128..127 autobox cache — e.g. deleteNode(new String("date")) reported "No data removed" for a "date" that really was in the list. AdtsDemo reproduces this with runtime-built Strings and Integers > 127 at the head, middle, and tail of the list; both methods now use java.util.Objects.equals(...) and correctly find/remove the matching node.

Troubleshooting

just run Proto5 (or any Proto) dies with IndexOutOfBoundsException

The prototypes assume the first job arrives at time 1 and that arrivals keep the CPU busy. An input whose ready queue is empty when a job completes crashes at queue.get(0). Keep custom inputs gap-free (see .docs/05-reference/).

A program crashes with NumberFormatException on the very first prompt

You piped input with PowerShell (Get-Content file | java ...) — the 5.1 pipe injects a UTF-8 BOM into the first line. Use just run <name>, which redirects via cmd /c instead.

NoSuchElementException: No line found at a search prompt under redirected input

Historical: ProgramApp and SortingAndSearchingV1/V2/V4 used to construct a second Scanner(System.in) inside their search methods; with redirected stdin the first Scanner buffered the whole stream, so the second one hit EOF. Fixed in 2026 — the search methods now reuse main's Scanner, and all four run fine under just run/just test. Seeing this error today means a sample-input file has fewer lines than the program reads.

javac prints a [serial] warning for EmptyListException

Known baseline (one warning, adts\LinkedList.java): the nested exception class has no serialVersionUID. Accepted as-is — preserved coursework. Anything beyond that one warning is new.

A program just sits there doing nothing

It is waiting for stdin. Either its sample-inputs\<name>.txt is missing (check just run's notice) or you ran run-interactive — type the values in the prompt order.

More in .docs/06-troubleshooting/common-issues.md.

Project layout

java-data-structures/
  adts/                    # generic linked list ADT family: LinkedList, Node, Stack, Queue + AdtsDemo (driver)
  sorting-searching/       # ProgramApp + SortingAndSearchingV1–V5 + Student (data class)
  scheduling-prototypes/   # Proto5–Proto8 SJF scheduler prototypes + Job (data class)
  misc/                    # ForEachExample1 (tiny for-each demo)
  sample-inputs/           # <ProgramName>.txt canned stdin, one per stdin-reading program
  tests/                   # golden-output harness: run-tests.ps1 + expected/ (12 goldens)
  out/                     # compiled classes (git-ignored)
  .docs/                   # numbered documentation set
  .claude/                 # skills, hooks, settings
  justfile, setup.ps1