Learner Setup

Lessons 1 through 5 use only the JDK. Lesson 6 adds Spring Boot and uses Maven to resolve framework dependencies. The default scripts target Java 21 because lesson 3 demonstrates virtual threads and lesson 6 uses a modern Spring Boot stack.

Required Software

JDK 21 or newer
Maven 3.6.3 or newer for lesson 6
Bash-compatible shell
Git, optional but recommended

Check your tools:

java -version
javac -version
mvn -version
git --version

The java and javac commands must refer to the same JDK family. If your system has multiple JDKs, configure paths in tutorial.conf or through environment variables.

First Run

From the java_tutorial directory:

scripts/test.sh

Expected behavior:

All six lessons compile.
Exercise runners execute even though they still contain TODO stubs.
Lesson 4 writes build/out/lesson_4/synthetic-input.png and build/out/lesson_4/sobel-edges.png.
Lesson 6 downloads Maven dependencies on the first run and starts a temporary Spring Boot server during its demo.

Configuring Java And Build Paths

Edit tutorial.conf:

JAVA_BIN="/path/to/java"
JAVAC_BIN="/path/to/javac"
MAVEN_BIN="/path/to/mvn"
JAVA_RELEASE="21"
BUILD_DIR="build/classes"
OUTPUT_DIR="build/out"

Or override at the command line:

JAVA_BIN=/opt/jdk-21/bin/java JAVAC_BIN=/opt/jdk-21/bin/javac scripts/test.sh

How Exercises Work

Each lesson has:

src/exercise/java: files learners edit.
stubs/java: reset copies.
answers/java: completed reference answers.

Reset your work:

scripts/reset_exercises.sh lesson_1

Fill answers:

scripts/apply_answers.sh lesson_1

Reset everything:

scripts/reset_exercises.sh all

Recommended Workflow

Run the lesson demo.
Read the lesson README and the exercise file.
Implement one TODO function.
Run scripts/run.sh lesson_N exercise.
Repeat until the output makes sense.
Apply answers only after you have a working attempt or a concrete question.

Troubleshooting

If lesson 3 does not compile, your JDK is probably older than Java 21. Run javac -version and update tutorial.conf.

If lesson 6 cannot resolve dependencies, run mvn -version and confirm Maven can access Maven Central from your network.

If Permission denied appears for scripts, run:

chmod +x scripts/*.sh

If image output is missing in lesson 4, confirm the process can write to OUTPUT_DIR and rerun:

scripts/run.sh lesson_4 demo

If port 8080 is already in use for the Spring Boot app, run:

SERVER_PORT=8081 scripts/serve_spring_hello_8080.sh