Add Java core modules

Author: lucasbellesi

CONCEPT_INDEX.md

@@ -25,12 +25,12 @@ Use this page to browse the same concept across every active language track.
 
 | Concept | C++ | C# | Go | Java | Python | TypeScript |
 | --- | --- | --- | --- | --- | --- | --- |
-| input-validation | [C++](languages/cpp/02-core/input-validation/README.md) | [C#](languages/csharp/02-core/input-validation/README.md) | [Go](languages/go/02-core/input-validation/README.md) | Planned | [Python](languages/python/02-core/input-validation/README.md) | [TypeScript](languages/typescript/02-core/input-validation/README.md) |
-| algorithms-basics | [C++](languages/cpp/02-core/algorithms-basics/README.md) | [C#](languages/csharp/02-core/algorithms-basics/README.md) | [Go](languages/go/02-core/algorithms-basics/README.md) | Planned | [Python](languages/python/02-core/algorithms-basics/README.md) | [TypeScript](languages/typescript/02-core/algorithms-basics/README.md) |
-| file-io-basics | [C++](languages/cpp/02-core/file-io-basics/README.md) | [C#](languages/csharp/02-core/file-io-basics/README.md) | [Go](languages/go/02-core/file-io-basics/README.md) | Planned | [Python](languages/python/02-core/file-io-basics/README.md) | [TypeScript](languages/typescript/02-core/file-io-basics/README.md) |
-| sorting-and-searching | [C++](languages/cpp/02-core/sorting-and-searching/README.md) | [C#](languages/csharp/02-core/sorting-and-searching/README.md) | [Go](languages/go/02-core/sorting-and-searching/README.md) | Planned | [Python](languages/python/02-core/sorting-and-searching/README.md) | [TypeScript](languages/typescript/02-core/sorting-and-searching/README.md) |
-| maps-and-frequency-counting | [C++](languages/cpp/02-core/maps-and-frequency-counting/README.md) | [C#](languages/csharp/02-core/maps-and-frequency-counting/README.md) | [Go](languages/go/02-core/maps-and-frequency-counting/README.md) | Planned | [Python](languages/python/02-core/maps-and-frequency-counting/README.md) | [TypeScript](languages/typescript/02-core/maps-and-frequency-counting/README.md) |
-| error-handling-and-defensive-programming | [C++](languages/cpp/02-core/error-handling-and-defensive-programming/README.md) | [C#](languages/csharp/02-core/error-handling-and-defensive-programming/README.md) | [Go](languages/go/02-core/error-handling-and-defensive-programming/README.md) | Planned | [Python](languages/python/02-core/error-handling-and-defensive-programming/README.md) | [TypeScript](languages/typescript/02-core/error-handling-and-defensive-programming/README.md) |
+| input-validation | [C++](languages/cpp/02-core/input-validation/README.md) | [C#](languages/csharp/02-core/input-validation/README.md) | [Go](languages/go/02-core/input-validation/README.md) | [Java](languages/java/02-core/input-validation/README.md) | [Python](languages/python/02-core/input-validation/README.md) | [TypeScript](languages/typescript/02-core/input-validation/README.md) |
+| algorithms-basics | [C++](languages/cpp/02-core/algorithms-basics/README.md) | [C#](languages/csharp/02-core/algorithms-basics/README.md) | [Go](languages/go/02-core/algorithms-basics/README.md) | [Java](languages/java/02-core/algorithms-basics/README.md) | [Python](languages/python/02-core/algorithms-basics/README.md) | [TypeScript](languages/typescript/02-core/algorithms-basics/README.md) |
+| file-io-basics | [C++](languages/cpp/02-core/file-io-basics/README.md) | [C#](languages/csharp/02-core/file-io-basics/README.md) | [Go](languages/go/02-core/file-io-basics/README.md) | [Java](languages/java/02-core/file-io-basics/README.md) | [Python](languages/python/02-core/file-io-basics/README.md) | [TypeScript](languages/typescript/02-core/file-io-basics/README.md) |
+| sorting-and-searching | [C++](languages/cpp/02-core/sorting-and-searching/README.md) | [C#](languages/csharp/02-core/sorting-and-searching/README.md) | [Go](languages/go/02-core/sorting-and-searching/README.md) | [Java](languages/java/02-core/sorting-and-searching/README.md) | [Python](languages/python/02-core/sorting-and-searching/README.md) | [TypeScript](languages/typescript/02-core/sorting-and-searching/README.md) |
+| maps-and-frequency-counting | [C++](languages/cpp/02-core/maps-and-frequency-counting/README.md) | [C#](languages/csharp/02-core/maps-and-frequency-counting/README.md) | [Go](languages/go/02-core/maps-and-frequency-counting/README.md) | [Java](languages/java/02-core/maps-and-frequency-counting/README.md) | [Python](languages/python/02-core/maps-and-frequency-counting/README.md) | [TypeScript](languages/typescript/02-core/maps-and-frequency-counting/README.md) |
+| error-handling-and-defensive-programming | [C++](languages/cpp/02-core/error-handling-and-defensive-programming/README.md) | [C#](languages/csharp/02-core/error-handling-and-defensive-programming/README.md) | [Go](languages/go/02-core/error-handling-and-defensive-programming/README.md) | [Java](languages/java/02-core/error-handling-and-defensive-programming/README.md) | [Python](languages/python/02-core/error-handling-and-defensive-programming/README.md) | [TypeScript](languages/typescript/02-core/error-handling-and-defensive-programming/README.md) |
 
 ### 03-advanced
 

CONTRIBUTING.md

@@ -9,7 +9,7 @@ Thank you for contributing to this repository.
 - Use clear English for all text, comments, and instructions.
 - Maintain cross-platform compatibility (Windows MSYS2 + Linux).
 - Keep Node-based tooling simple and explicit when touching the TypeScript track.
-- Keep Java foundations on plain `javac`/`java` until the track intentionally adopts build tooling.
+- Keep Java modules on plain `javac`/`java` until the track intentionally adopts build tooling.
 
 ## Workflow
 
@@ -99,7 +99,7 @@ Use [EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md](EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md)
 - Avoid external dependencies and test frameworks for C++ modules.
 - Avoid external dependencies and test frameworks for non-C++ checkpoints.
 - Keep the TypeScript track on plain Node console programs; do not introduce browser, DOM, or framework dependencies.
-- Keep the Java foundations MVP on package-free single-file programs; do not introduce Maven, Gradle, or `src/main/java` yet.
+- Keep the Java MVP on package-free single-file programs; do not introduce Maven, Gradle, or `src/main/java` yet.
 - Keep examples aligned with C++17.
 - Keep documentation in English and keep path names consistent with folder names.
 - Keep parity planning updated in `LANGUAGE_PARITY_MATRIX.md` when adding modules or checkpoints to non-C++ tracks.

LANGUAGE_PARITY_MATRIX.md

@@ -4,7 +4,7 @@ This matrix tracks module and checkpoint parity across C++, C#, Go, Java, Python
 
 - Canonical order is defined by the C++ track.
 - C++, C#, Go, Python, and TypeScript now reach module and checkpoint parity through `04-expert`.
-- Java currently tracks `01-foundations` as a Java 21 MVP.
+- Java currently tracks `01-foundations` and `02-core` as a Java 21 MVP.
 - Status labels:
   - `Done`: module implemented with example, exercises, and README.
   - `Planned`: module not implemented yet, already queued in order.
@@ -28,18 +28,18 @@ Current parity progress in non-C++ tracks:
 
 - C#: `6/6` modules complete
 - Go: `6/6` modules complete
-- Java: `0/6` modules complete
+- Java: `6/6` modules complete
 - Python: `6/6` modules complete
 - TypeScript: `6/6` modules complete
 
 | Order | Module | C++ | C# | Go | Java | Python | TypeScript |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| 1 | input-validation | Done | Done | Done | Planned | Done | Done |
-| 2 | algorithms-basics | Done | Done | Done | Planned | Done | Done |
-| 3 | file-io-basics | Done | Done | Done | Planned | Done | Done |
-| 4 | sorting-and-searching | Done | Done | Done | Planned | Done | Done |
-| 5 | maps-and-frequency-counting | Done | Done | Done | Planned | Done | Done |
-| 6 | error-handling-and-defensive-programming | Done | Done | Done | Planned | Done | Done |
+| 1 | input-validation | Done | Done | Done | Done | Done | Done |
+| 2 | algorithms-basics | Done | Done | Done | Done | Done | Done |
+| 3 | file-io-basics | Done | Done | Done | Done | Done | Done |
+| 4 | sorting-and-searching | Done | Done | Done | Done | Done | Done |
+| 5 | maps-and-frequency-counting | Done | Done | Done | Done | Done | Done |
+| 6 | error-handling-and-defensive-programming | Done | Done | Done | Done | Done | Done |
 
 ## Advanced and Expert
 

README.md

@@ -36,7 +36,8 @@ If you only want to learn one track, follow that track README first because lang
    - [TypeScript Guide](languages/typescript/README.md)
 2. Start at the first roadmap for that track:
    - C++: [00-setup](languages/cpp/00-setup/README.md), then `01-foundations`
-   - C#, Go, Java, Python, TypeScript: `01-foundations`
+   - Java: `01-foundations`, then `02-core`
+   - C#, Go, Python, TypeScript: `01-foundations`
 3. Run one module example.
 4. Solve `exercises/01` and `exercises/02` in that module.
 5. Mark progress in the language checklist.
@@ -55,7 +56,7 @@ If you only want to learn one track, follow that track README first because lang
 | C++ | 00-setup, 01-foundations, 02-core, 03-advanced, 04-expert | Foundations, Core, Advanced, Expert, projects, assessments | Most complete and primary track |
 | C# | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
 | Go | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
-| Java | 01-foundations | 8/8 foundations modules | Java 21 MVP; core, advanced, expert, projects, and assessments planned |
+| Java | 01-foundations, 02-core | 8/8 foundations modules, 6/6 core modules | Java 21 MVP; advanced, expert, projects, and assessments planned |
 | Python | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
 | TypeScript | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
 

languages/java/02-core/README.md

@@ -0,0 +1,39 @@
+# Java 02 Core
+
+This level moves from syntax practice into defensive programs, small algorithms, file handling, and collection-based analysis.
+
+## Learning Metadata
+
+- Difficulty: Intermediate.
+- Estimated Time: 4-6 hours.
+- Prerequisites: Completion of `01-foundations`.
+- Study Strategy: Run each example, trace the edge cases, then solve both exercises before comparing the same module in another language.
+
+## Module Order
+
+1. [input-validation](./input-validation/README.md)
+2. [algorithms-basics](./algorithms-basics/README.md)
+3. [file-io-basics](./file-io-basics/README.md)
+4. [sorting-and-searching](./sorting-and-searching/README.md)
+5. [maps-and-frequency-counting](./maps-and-frequency-counting/README.md)
+6. [error-handling-and-defensive-programming](./error-handling-and-defensive-programming/README.md)
+
+Track progress in [../CHECKLIST.md](../CHECKLIST.md).
+
+## Level Outcomes
+
+- Validate console input without crashing.
+- Implement search, counting, sorting, and aggregation logic.
+- Read and write small text files with `Path` and `Files`.
+- Use maps for frequency analysis and defensive branches for invalid data.
+
+## Done When
+
+- [ ] I ran every `example/Main.java` file.
+- [ ] I completed both exercises in every core module.
+- [ ] I can explain at least one edge case for each exercise.
+- [ ] I can compare Java's standard-library APIs with the same concept in another track.
+
+## Study Tip
+
+Keep the programs package-free for now. The goal is to practice core logic before introducing Maven, Gradle, or multi-file project layout.

languages/java/02-core/algorithms-basics/README.md

@@ -0,0 +1,61 @@
+# Algorithms Basics (Java)
+
+This module practices small search and counting algorithms over arrays.
+
+## Learning Metadata
+
+- Difficulty: Intermediate.
+- Estimated Time: 30-45 minutes.
+- Prerequisites: `01-foundations/arrays-and-vectors`, `01-foundations/control-flow`.
+- Cross-Language Lens: Compare Java loops and helper methods with the same algorithmic patterns in C++, C#, Go, Python, and TypeScript.
+
+## Quick Run
+
+~~~bash
+javac -d build/java languages/java/02-core/algorithms-basics/example/Main.java
+java -cp build/java Main
+~~~
+
+## Topics Covered
+
+- Linear search.
+- Counting matching values.
+- Aggregating minimum, maximum, and even counts.
+- Returning sentinel values such as `-1`.
+
+## Common Pitfalls
+
+- Returning the last match when the task asks for the first.
+- Forgetting to handle empty input.
+- Mixing index positions with values.
+
+## Cross-Language Notes
+
+- Java arrays expose `.length`, not a `size()` method.
+- Helper methods make algorithm intent easier to test.
+- Sentinel values should be documented in output labels and exercise specs.
+
+## Exercise Focus
+
+- exercises/Exercise01.java: find the first index and occurrence count for a target value.
+- exercises/Exercise02.java: summarize minimum, maximum, and even values.
+
+### Exercise Specs
+
+1. exercises/Exercise01.java
+- Input: count, that many integers, then target integer.
+- Output: first index and occurrence count.
+- Edge cases: target missing; target at index 0.
+
+2. exercises/Exercise02.java
+- Input: count followed by that many integers.
+- Output: minimum, maximum, and count of even numbers.
+- Edge cases: single value; negative values; all odd values.
+
+## Checkpoint
+
+- [ ] I can write a linear search.
+- [ ] I can count matches in one pass.
+- [ ] I completed exercises/Exercise01.java.
+- [ ] I completed exercises/Exercise02.java.
+- [ ] I tested a missing-target case.

languages/java/02-core/algorithms-basics/example/Main.java

@@ -0,0 +1,34 @@
+// Module focus: Walking data step by step to compute summaries and decisions.
+// Why it matters: practicing algorithms basics patterns makes exercises and checkpoints easier to reason about.
+
+public class Main {
+    static int firstIndexOf(int[] values, int target) {
+        for (int i = 0; i < values.length; i++) {
+            if (values[i] == target) {
+                // Return immediately because the first match is the result this helper promises.
+                return i;
+            }
+        }
+        return -1;
+    }
+
+    static int countOccurrences(int[] values, int target) {
+        int count = 0;
+        for (int value : values) {
+            // Counting does not stop at the first match; every element still matters.
+            if (value == target) {
+                count++;
+            }
+        }
+        return count;
+    }
+
+    public static void main(String[] args) {
+        int[] values = {4, 7, 4, 2, 4, 9};
+        int target = 4;
+
+        // Report both position and frequency so learners can compare related scans.
+        System.out.println("First index of 4: " + firstIndexOf(values, target));
+        System.out.println("Occurrences of 4: " + countOccurrences(values, target));
+    }
+}

languages/java/02-core/algorithms-basics/exercises/Exercise01.java

@@ -0,0 +1,27 @@
+import java.util.Scanner;
+
+public class Exercise01 {
+    public static void main(String[] args) {
+        Scanner scanner = new Scanner(System.in);
+        int count = scanner.nextInt();
+        int[] values = new int[count];
+        for (int i = 0; i < count; i++) {
+            values[i] = scanner.nextInt();
+        }
+        int target = scanner.nextInt();
+
+        int firstIndex = -1;
+        int occurrences = 0;
+        for (int i = 0; i < values.length; i++) {
+            if (values[i] == target) {
+                occurrences++;
+                if (firstIndex == -1) {
+                    firstIndex = i;
+                }
+            }
+        }
+
+        System.out.println("First index: " + firstIndex);
+        System.out.println("Occurrences: " + occurrences);
+    }
+}

languages/java/02-core/algorithms-basics/exercises/Exercise02.java

@@ -0,0 +1,28 @@
+import java.util.Scanner;
+
+public class Exercise02 {
+    public static void main(String[] args) {
+        Scanner scanner = new Scanner(System.in);
+        int count = scanner.nextInt();
+        if (count <= 0) {
+            System.out.println("Count must be positive.");
+            return;
+        }
+
+        int minimum = Integer.MAX_VALUE;
+        int maximum = Integer.MIN_VALUE;
+        int evenCount = 0;
+        for (int i = 0; i < count; i++) {
+            int value = scanner.nextInt();
+            minimum = Math.min(minimum, value);
+            maximum = Math.max(maximum, value);
+            if (value % 2 == 0) {
+                evenCount++;
+            }
+        }
+
+        System.out.println("Minimum: " + minimum);
+        System.out.println("Maximum: " + maximum);
+        System.out.println("Even numbers: " + evenCount);
+    }
+}

languages/java/02-core/error-handling-and-defensive-programming/README.md

@@ -0,0 +1,61 @@
+# Error Handling and Defensive Programming (Java)
+
+This module practices handling invalid operations and malformed records explicitly.
+
+## Learning Metadata
+
+- Difficulty: Intermediate.
+- Estimated Time: 35-50 minutes.
+- Prerequisites: `02-core/input-validation`, `02-core/file-io-basics`.
+- Cross-Language Lens: Compare Java exceptions and guard clauses with defensive patterns in C++, C#, Go, Python, and TypeScript.
+
+## Quick Run
+
+~~~bash
+javac -d build/java languages/java/02-core/error-handling-and-defensive-programming/example/Main.java
+java -cp build/java Main
+~~~
+
+## Topics Covered
+
+- Guarding invalid operations.
+- Catching parsing failures.
+- Continuing after malformed records.
+- Reporting accepted and skipped data.
+
+## Common Pitfalls
+
+- Catching exceptions too broadly and hiding the real problem.
+- Dividing before checking for zero.
+- Treating malformed rows as valid default values.
+
+## Cross-Language Notes
+
+- Java uses exceptions for many parse and I/O failures.
+- Guard clauses keep the happy path easier to read.
+- Defensive programs should explain what was skipped and why.
+
+## Exercise Focus
+
+- exercises/Exercise01.java: divide two integers defensively.
+- exercises/Exercise02.java: parse name-score rows until EOF and summarize accepted rows.
+
+### Exercise Specs
+
+1. exercises/Exercise01.java
+- Input: two integer tokens.
+- Output: integer division result or a clear error message.
+- Edge cases: non-integer input; division by zero.
+
+2. exercises/Exercise02.java
+- Input: rows shaped as `name score` until EOF.
+- Output: accepted row count, skipped row count, and average score.
+- Edge cases: malformed rows; score outside 0..100.
+
+## Checkpoint
+
+- [ ] I can use guard clauses before risky operations.
+- [ ] I can catch parsing errors without masking valid data.
+- [ ] I completed exercises/Exercise01.java.
+- [ ] I completed exercises/Exercise02.java.
+- [ ] I tested at least one malformed input row.