Appendix B Companion: Code, Explanations and Solutions

bash scripts/check-setup.sh
bash scripts/check.sh

CHAPTER_M2=/path/to/repository CHAPTER_OFFLINE=1 bash scripts/check.sh

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>edu.se506</groupId>
  <artifactId>toolchain-check</artifactId>
  <version>0.1.0</version>
  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>5.13.4</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.mockito</groupId>
      <artifactId>mockito-core</artifactId>
      <version>5.20.0</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.14.1</version>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.4</version>
        <configuration><failIfNoTests>true</failIfNoTests></configuration>
      </plugin>
    </plugins>
  </build>
</project>

package edu.se506.setup;

/** Reports which Java runtime is executing and which release the code was compiled for. */
public final class ToolchainReport {
    /** The language and API level the build targets (see maven.compiler.release in pom.xml). */
    public static final int RELEASE_TARGET = 17;

    private ToolchainReport() {
    }

    public static int javaFeatureVersion() {
        return Runtime.version().feature();
    }

    /** Code compiled for a release runs on that Java version and on every later one. */
    public static boolean canRunOn(int runtimeFeature) {
        return runtimeFeature >= RELEASE_TARGET;
    }

    public static String summary() {
        return "Running on Java " + javaFeatureVersion()
                + "; compiled for release target " + RELEASE_TARGET;
    }

    public static void main(String[] args) {
        System.out.println(summary());
    }
}

package edu.se506.setup;

import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;

class ToolchainReportTest {

    @Test
    void theRunningJavaCanRunCodeCompiledForTheTarget() {
        assertTrue(ToolchainReport.canRunOn(ToolchainReport.javaFeatureVersion()));
    }

    @Test
    void theSummaryNamesTheReleaseTarget() {
        assertTrue(ToolchainReport.summary().endsWith("compiled for release target 17"));
    }

    @ParameterizedTest
    @ValueSource(ints = {17, 21, 24})
    void javaVersionsAtOrAboveTheTargetCanRunTheCode(int runtimeFeature) {
        assertTrue(ToolchainReport.canRunOn(runtimeFeature));
    }

    @Test
    void aJavaVersionBelowTheTargetCannotRunTheCode() {
        assertFalse(ToolchainReport.canRunOn(16));
    }
}

package edu.se506.setup;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;

import org.junit.jupiter.api.Test;

/** Checks that Mockito is configured. It tests the framework setup, not any domain behaviour. */
class GreeterMockTest {

    interface Greeter {
        String greet(String name);
    }

    @Test
    void aMockOfAnInterfaceAnswersWhatItIsTold() {
        Greeter greeter = mock(Greeter.class);
        when(greeter.greet("Ada")).thenReturn("Hello, Ada");

        assertEquals("Hello, Ada", greeter.greet("Ada"));
        verify(greeter).greet("Ada");
    }
}

mock-maker-proxy

#!/usr/bin/env bash
# Reports whether the tools the book needs are on the PATH and recent enough.
# It changes nothing and downloads nothing. A line that starts with OK, MISSING or TOO-OLD
# is easy to search for; the exit status is 1 if any required tool is not usable.
# CHAPTER_MVN optionally names the Maven command (default: mvn).
set -u

MVN="${CHAPTER_MVN:-mvn}"
status=0

report() {
  printf '%-8s %s\n' "$1" "$2"
}

# Report the first line of the output of a tool's version command.
need() {
  local label="$1"
  shift
  if command -v "$1" >/dev/null 2>&1 || [ -f "$1" ]; then
    report "OK" "${label}: $("$@" 2>&1 | head -1)"
  else
    report "MISSING" "${label}: '$1' is not on the PATH"
    status=1
  fi
}

need "bash" bash --version
need "git" git --version
need "java" java -version
need "maven" "$MVN" --version

if command -v javac >/dev/null 2>&1; then
  feature="$(javac -version 2>&1 | sed -n 's/^javac \([0-9][0-9]*\).*/\1/p')"
  if [ "${feature:-0}" -ge 17 ]; then
    report "OK" "javac: compiler version ${feature} can compile with --release 17"
  else
    report "TOO-OLD" "javac: version '$(javac -version 2>&1)' cannot compile with --release 17; install a JDK of version 17 or later"
    status=1
  fi
else
  report "MISSING" "javac: a JDK (not only a JRE) is needed"
  status=1
fi

if [ "$status" -eq 0 ]; then
  echo "SETUP OK"
else
  echo "SETUP INCOMPLETE"
fi
exit "$status"

#!/usr/bin/env bash
# The one command that decides whether the starter is healthy: compile, run every test, package.
# CHAPTER_MVN names the Maven command (default: mvn). CHAPTER_M2 optionally names a local Maven
# repository, and CHAPTER_OFFLINE=1 stops Maven from contacting any remote repository.
set -euo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")/.."

MVN="${CHAPTER_MVN:-mvn}"
ARGS=(--batch-mode)
if [ -n "${CHAPTER_M2:-}" ]; then
  ARGS+=("-Dmaven.repo.local=${CHAPTER_M2}")
fi
if [ "${CHAPTER_OFFLINE:-0}" = "1" ]; then
  ARGS+=(--offline)
fi

"$MVN" "${ARGS[@]}" verify
java -cp target/classes edu.se506.setup.ToolchainReport
echo "BUILD AND TESTS PASSED"

name: Verify

on:
  push:
  pull_request:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: '17'
          cache: maven
      - name: Build and test
        run: bash scripts/check.sh

# Toolchain check

A small project that shows the book's toolchain works: a Java 17 release target, Maven 3.9.11
with JUnit Jupiter 5.13.4 and Mockito 5.20.0, and the Bash scripts. It is not part of the lending project.

## Check the tools

```bash
bash scripts/check-setup.sh
```

Every line should start with `OK`, and the last line should be `SETUP OK`.

## Build and test

```bash
bash scripts/check.sh
```

Expect `BUILD SUCCESS`, seven test invocations (five test methods; one is parameterised with
three values), the line `Running on Java N; compiled for release target 17` and, last,
`BUILD AND TESTS PASSED`. A failing test must stop the script with a non-zero exit status.

Optional variables: `CHAPTER_MVN` names the Maven command, `CHAPTER_M2` names a local Maven
repository folder and `CHAPTER_OFFLINE=1` stops Maven from contacting any remote repository.

OK       bash: GNU bash, version 5.3.9(1)-release (x86_64-pc-cygwin)
OK       git: git version 2.54.0.windows.1
OK       java: java version "24.0.2" 2025-07-15
OK       maven: Apache Maven 3.9.11 (3e54c93a704957b63ee3494413a2b544fd3d825b)
OK       javac: compiler version 24 can compile with --release 17
SETUP OK

[INFO] Compiling 1 source file with javac [debug release 17] to target\classes
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 ... in edu.se506.setup.GreeterMockTest
[INFO] Tests run: 6, Failures: 0, Errors: 0, Skipped: 0 ... in edu.se506.setup.ToolchainReportTest
[INFO] Tests run: 7, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS
Running on Java 24; compiled for release target 17
BUILD AND TESTS PASSED

#!/usr/bin/env bash
# A complete Git walk in a throwaway folder: commit, branch, inspect, undo, merge and share.
# Usage: bash git-walkthrough.sh /path/to/starter /path/to/empty-work-folder
# It uses only local folders. The "remote" is a bare repository on this machine, so no account
# and no network are involved. The author identity is set for this repository only.
set -euo pipefail

STARTER="$1"
WORK="$2"
mkdir -p "$WORK"
cp -r "$STARTER/." "$WORK/project"
rm -rf "$WORK/project/target"
cd "$WORK/project"

step() { printf '\n--- %s\n' "$1"; }

step "1 create the repository and the first commit"
git init -b main
git config user.name "Example Student"
git config user.email "[email protected]"
git add README.md pom.xml src scripts .gitignore .gitattributes .github
git status --short
git commit -m "Add the toolchain starter"

step "2 a branch for one small change"
git switch -c feature/clearer-summary
FILE=src/main/java/edu/se506/setup/ToolchainReport.java
sed 's/Running on Java /Running on Java version /' "$FILE" > "$FILE.tmp"
mv "$FILE.tmp" "$FILE"
git status --short
git diff

step "3 stage it, compare staged and unstaged, commit"
git add "$FILE"
git diff --staged --stat
git diff --stat
git commit -m "Say 'version' in the runtime summary"

step "4 discard an edit, and unstage a file"
echo "/scratch/" >> .gitignore
git status --short
git restore .gitignore
git status --short
echo "notes" > NOTES.txt
git add NOTES.txt
git status --short
git restore --staged NOTES.txt
git status --short
rm NOTES.txt

step "5 reverse a commit by adding a new one"
git revert --no-edit HEAD
git log --oneline

step "6 merge back and look at the history"
git switch main
git merge feature/clearer-summary
git log --oneline --graph --decorate

step "7 share through a bare repository acting as the remote"
git init --bare -b main "$WORK/remote.git"
git remote add origin "$WORK/remote.git"
git push -u origin main
git push -u origin feature/clearer-summary
git branch -vv
git ls-remote --heads origin | cut -f2

step "8 a second clone sees the same history"
git clone "$WORK/remote.git" "$WORK/second-clone"
git -C "$WORK/second-clone" log --oneline | head -3

bash git-walkthrough.sh /path/to/toolchain-check /path/to/new-empty-work-folder

--- 2 a branch for one small change
Switched to a new branch 'feature/clearer-summary'
 M src/main/java/edu/se506/setup/ToolchainReport.java
...
--- 4 discard an edit, and unstage a file
 M .gitignore
A  NOTES.txt
?? NOTES.txt
--- 5 reverse a commit by adding a new one
[feature/clearer-summary <hash>] Revert "Say 'version' in the runtime summary"
--- 6 merge back and look at the history
Fast-forward
* <hash> (HEAD -> main, feature/clearer-summary) Revert "Say 'version' in the runtime summary"
* <hash> Say 'version' in the runtime summary
* <hash> Add the toolchain starter
--- 7 share through a bare repository acting as the remote
 * [new branch]      main -> main
 * [new branch]      feature/clearer-summary -> feature/clearer-summary