Rung 3 — The MiniCollections Library

Target month: Shipped by end of M5 = end of November 2026 (started in late M4) Calendar deadline: November 30, 2026 Phase alignment: Phase 02 → Phase 03 bridge — DSA meets OOP & generics Signal level: Implementation-from-scratch → proves you understand the machinery under java.util, not just how to call it

What It Is

A public GitHub library that re-implements the core of java.util.Collections from scratch, with the same behavior as the JDK but written by you, tested against the JDK’s contract, and documented like a small production library.

Scope is deliberately narrow. Ship these six, well:

#

Class

JDK counterpart

Must support

1

MiniArrayList<E>

java.util.ArrayList

resizing array, all List<E> methods, Iterator with fail-fast, generics

2

MiniLinkedList<E>

java.util.LinkedList

doubly-linked, List<E> + Deque<E> methods, iterator

3

MiniHashMap<K,V>

java.util.HashMap

separate chaining, resizing, load factor 0.75, all Map<K,V> methods, keySet/entrySet/values views

4

MiniLinkedHashMap<K,V>

java.util.LinkedHashMap

insertion-order preserving, LRU-mode via removeEldestEntry hook

5

MiniPriorityQueue<E>

java.util.PriorityQueue

binary min-heap over array, Queue<E> methods, comparator support

6

MiniArrayDeque<E>

java.util.ArrayDeque

circular buffer, both stack and queue behaviors, Deque<E>

Each class implements the standard java.util interface (List<E>, Map<K,V>, Queue<E>, Deque<E>) so it can be a drop-in replacement in your own code (not JDK internals).

The library ships as a real Maven artifact with a group id you own, so it’s pip install-able for JVM: mvn install on a fresh clone and the JAR is available locally.

Where To Publish

  • Repo: github.com/RaghulR2003/minicollections — public, pinned

  • Maven Central: Optional stretch goal — publishing to Maven Central via Sonatype OSSRH is a strong senior-signal, but not required for this rung. If you do it, put the badge in the README.

  • Javadoc: Hosted via GitHub Pages at raghulr2003.github.io/minicollections/

  • Announced: One LinkedIn + one Hashnode/dev.to post on completion. The post title is “I rewrote java.util — here’s what I found under the hood.” This is your first “looks like a senior engineer wrote this” post.

Acceptance Criteria

  • All 6 classes implemented, each in its own package, each implementing the correct java.util interface

  • Each class has a contract test suite that runs your class and the JDK class side-by-side and asserts identical behavior on 200+ operations (Guava’s Testlib or a homegrown property-test harness — both acceptable)

  • Each class has an isolated JUnit 5 test suite with at least 20 tests covering edge cases (empty, single-element, resize triggers, iterator fail-fast, null handling)

  • Iterator implementations detect concurrent modification and throw ConcurrentModificationException correctly

  • MiniHashMap handles collisions via separate chaining, resizes at load factor 0.75, and passes a stress test of 100K puts with random keys

  • MiniPriorityQueue passes a heap-invariant checker after every operation in a randomized 10K-operation test

  • Javadoc is generated and hosted on GitHub Pages, linked from the README

  • Top-level README has a benchmarks section: your implementation vs JDK on 5 operations (add, get, remove, iterate, resize) with a JMH-generated table

  • CI runs the full test suite + JMH smoke tests on push; badge is green

  • CHANGELOG.md exists and documents the evolution

Signal It Sends

  • You know the machinery. Anyone who has debugged a real production Java service has, at some point, asked “why is this HashMap slow?” You’ve now built one. You will never look at HashMap the same way again — and study partners can tell.

  • You test against a reference implementation. Contract testing against the JDK is a senior-engineer move. It shows you understand that “my class works” is a much weaker claim than “my class behaves identically to the reference on 200 operations.”

  • You benchmark. Even a rough JMH table signals that you care about how fast, not just whether it runs. This preloads the JVM performance work in Rung 6.

  • You write library-quality code. README, Javadoc, CHANGELOG, semantic versioning. This is a preview of the professionalism Rung 7 and 8 will demand.

Common Failure Modes

  • Reimplementing the whole java.util package. Scope creep. Six classes is enough. Don’t add MiniTreeMap, MiniConcurrentHashMap, or MiniIdentityHashMap — you’ll burn November and starve Rung 4.

  • Skipping the contract tests. “My tests pass, I’m done.” No — the contract test is the whole point. Without it, this is just a personal exercise. With it, it’s a portfolio piece.

  • Getting HashMap almost right. Collisions, resizing, and null keys are all easy to get subtly wrong. Budget 8 hours minimum for MiniHashMap and its contract tests. It is the hardest of the six.

  • Not benchmarking with JMH. Wall-clock System.nanoTime() benchmarks are noise. Use JMH from the start. The benchmark table in the README is what makes recruiters click.

  • No Javadoc. “Nobody reads Javadoc.” A senior engineer scanning your repo does. The absence of Javadoc reads as “I’ve never worked on a real library.”

Time Estimate

  • MiniArrayList + tests: ~6 hours

  • MiniLinkedList + tests: ~6 hours

  • MiniHashMap + tests + collision stress test: ~10 hours

  • MiniLinkedHashMap + tests: ~4 hours

  • MiniPriorityQueue + heap-invariant tests: ~6 hours

  • MiniArrayDeque + tests: ~5 hours

  • Contract test harness (JDK-vs-yours): ~5 hours

  • JMH benchmarks: ~4 hours

  • Javadoc + GitHub Pages + README + CHANGELOG: ~4 hours

  • Total: ~50 hours over 4-5 weeks

Prerequisites

  • Rung 2 in flight or shipped (you understand list/map/heap operations from problem-solving)

  • Comfortable with generics (Phase 04 has started or you’ve read 03_oop_design_patterns_modern_java if it exists)

  • JMH read-through: jmh docs — 20 minutes

  • One re-read of the java.util.HashMap JDK source (yes, actually open the JDK source)

Stretch Goals (Optional)

  1. Publish to Maven Central. The process (Sonatype OSSRH ticket, GPG signing, staging repo) is fiddly but transferable. If you do it once, you know it forever. Adds a massive senior-signal to the repo.

  2. Add MiniConcurrentHashMap with a striped-lock design. This is a preview of Rung 5 and shows you understand thread safety at the collections layer.

  3. Fuzz the contract tests using jqwik property-based testing. Instead of hand-writing 200 test operations, generate 10K randomized sequences and assert JDK-equivalence. This is the highest-signal stretch goal in the whole ladder for its cost.

Return to README.md · Next: 04_rung4_modern_java_refactor.md