Java Guild course · Lesson 0005

Lesson 0005 · the second intermediate requirement

Persistence Without Data Loss

A delimiter that appears in the data, a parser with no validation, and a load that destroys the library before it fails.

The save/load code works — for well-behaved input. The Intermediate requirement asks for persistence, and the starter has persistence, so it is tempting to tick it and move on. Three bugs say otherwise, and all three are the kind that reach production.

Step 1 · Write the failing tests

Create src/test/java/com/solirius/intermediate/library/LibraryPersistenceTest.java. Five tests, one per defect plus two controls:

package com.solirius.intermediate.library;

import com.solirius.intermediate.library.exceptions.LibraryStorageException;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;

@DisplayName("Saving and reloading the library")
class LibraryPersistenceTest {

    @TempDir
    private Path directory;

    @Test
    @DisplayName("preserves a title that contains the field separator")
    void preservesATitleContainingTheSeparator() throws Exception {
        Path file = directory.resolve("state.txt");
        Library saved = new Library();
        saved.addBook(new Book("Coming Home; A Novel", "Rosamunde Pilcher"));
        saved.saveLibraryState(file.toString());

        Library reloaded = new Library();
        reloaded.loadLibraryState(file.toString());

        Book book = reloaded.viewAvailableBooks().get(0);
        assertEquals("Coming Home; A Novel", book.getTitle());
        assertEquals("Rosamunde Pilcher", book.getAuthor());
    }

    @Test
    @DisplayName("preserves a title that contains the escape character")
    void preservesATitleContainingTheEscapeCharacter() throws Exception {
        Path file = directory.resolve("state.txt");
        Library saved = new Library();
        saved.addBook(new Book("AC\\DC: The Story", "Murray Engleheart"));
        saved.saveLibraryState(file.toString());

        Library reloaded = new Library();
        reloaded.loadLibraryState(file.toString());

        assertEquals("AC\\DC: The Story",
                reloaded.viewAvailableBooks().get(0).getTitle());
    }

    @Test
    @DisplayName("keeps a book borrowed across a save and reload")
    void keepsABookBorrowedAcrossASaveAndReload() throws Exception {
        Path file = directory.resolve("state.txt");
        Library saved = new Library();
        saved.addBook(new Book("Dune", "Frank Herbert"));
        saved.borrowBook("Dune");
        saved.saveLibraryState(file.toString());

        Library reloaded = new Library();
        reloaded.loadLibraryState(file.toString());

        assertTrue(reloaded.viewAvailableBooks().isEmpty());
        assertTrue(reloaded.searchBook("Dune").orElseThrow().isBorrowed());
    }

    @Test
    @DisplayName("rejects a corrupt file instead of crashing on an array index")
    void rejectsACorruptFile() throws Exception {
        Path file = directory.resolve("state.txt");
        Files.write(file, List.of("Dune;Frank Herbert"));

        LibraryStorageException thrown = assertThrows(LibraryStorageException.class,
                () -> new Library().loadLibraryState(file.toString()));

        assertEquals("Corrupt library state at line 1: "
                + "expected 3 fields but found 2", thrown.getMessage());
    }

    @Test
    @DisplayName("leaves the library untouched when the file cannot be read")
    void leavesTheLibraryUntouchedWhenTheFileCannotBeRead() {
        Library library = new Library();
        library.addBook(new Book("Dune", "Frank Herbert"));

        assertThrows(LibraryStorageException.class,
                () -> library.loadLibraryState(
                        directory.resolve("absent.txt").toString()));

        assertEquals(1, library.viewAvailableBooks().size(),
                "a failed load must not destroy the books already held");
    }
}

LibraryPersistenceTest.java:[23,31] unreported exception
  LibraryStorageException; must be caught or declared to be thrown

Step 2 · Run it and read the red

cd ~/Desktop/java-guild-candidate-test-intermediate-main
mvn clean test

preservesATitleContainingTheSeparator
  expected: <Coming Home; A Novel> but was: <Coming Home>

rejectsACorruptFile
  Unexpected exception type thrown, expected: <...LibraryStorageException>
  but was: <java.lang.ArrayIndexOutOfBoundsException>

leavesTheLibraryUntouchedWhenTheFileCannotBeRead
  a failed load must not destroy the books already held
  expected: <1> but was: <0>

Three failures, three distinct defects. The fix is one coherent rewrite of the persistence half of Library, so the steps below build it in order rather than defect by defect.

Step 3 · Add LibraryStorageException

Create src/main/java/com/solirius/intermediate/library/exceptions/LibraryStorageException.java:

package com.solirius.intermediate.library.exceptions;

/**
 * Exception thrown when the saved library state cannot be read or written.
 */
public class LibraryStorageException extends LibraryException {
    /**
     * Constructs a new LibraryStorageException with the specified message.
     *
     * @param message the detail message
     */
    public LibraryStorageException(final String message) {
        super(message);
    }

    /**
     * Constructs a new LibraryStorageException with a message and a cause.
     *
     * @param message the detail message
     * @param cause   the underlying failure
     */
    public LibraryStorageException(final String message, final Throwable cause) {
        super(message);
        initCause(cause);
    }
}

Step 4 · Add the format constants

    /** Field separator used by the flat-file format. */
    private static final String SEPARATOR = ";";
    /** Escape character used to protect separators inside a field. */
    private static final String ESCAPE = "\\";
    /** Number of fields on every well-formed line. */
    private static final int FIELD_COUNT = 3;

Two constants, used by the save, the load and the validation. A disagreement between any two of them is a silent round-trip bug, so they are named once.

Step 5 · Make the separator impossible to collide with

The problem in one sentence: you are using ; as a separator, and ; can appear in the data. There are two families of fix.

The obvious one, and why it is more work than it looks

Escape the separator on the way out — ; becomes \; — and unescape on the way in. The write side is four lines and looks harmless:

private static String escape(final String field) {
    return field.replace(ESCAPE, ESCAPE + ESCAPE)
            .replace(SEPARATOR, ESCAPE + SEPARATOR);
}

The read side is where the cost lands. You cannot use String.split(";") any more — it has no idea that \; means “a literal semicolon” — so you hand-roll a character-by-character state machine: 21 further lines, a boolean escaped flag, and a final fields.add() after the loop that is easy to forget.

The better one: make the separator unrepresentable

Instead of teaching the parser about escapes, encode each field so it cannot contain the separator in the first place. The JDK already does this:

    /**
     * Encodes a field so that it cannot contain the separator.
     * <p>
     * Percent-encoding is delegated to the JDK rather than hand-rolled: it
     * makes every character legal in every field, including the separator
     * itself, and it is symmetric with {@link #decode(String)} by
     * construction.
     * </p>
     *
     * @param field the raw field value
     * @return the field, safe to place between separators
     */
    private static String encode(final String field) {
        return URLEncoder.encode(field, StandardCharsets.UTF_8);
    }

    /**
     * Reverses {@link #encode(String)}.
     *
     * @param field the encoded field value
     * @return the original text
     */
    private static String decode(final String field) {
        return URLDecoder.decode(field, StandardCharsets.UTF_8);
    }

That is the entire mechanism. URLEncoder percent-encodes anything that is not alphanumeric — including ; — so a plain split(SEPARATOR, -1) is now correct, and parseLine just decodes each field:

    /**
     * Parses one line of the saved format into a book.
     *
     * @param line       the raw line
     * @param lineNumber the 1-based line number, used in error messages
     * @return the book the line describes
     * @throws LibraryStorageException if the line is not well formed
     */
    private Book parseLine(final String line, final int lineNumber)
            throws LibraryStorageException {
        String[] fields = line.split(SEPARATOR, -1);
        if (fields.length != FIELD_COUNT) {
            throw new LibraryStorageException("Corrupt library state at line "
                    + lineNumber + ": expected " + FIELD_COUNT
                    + " fields but found " + fields.length);
        }
        Book book = new Book(decode(fields[0]), decode(fields[1]));
        if (Boolean.parseBoolean(fields[2])) {
            book.borrowBook();
        }
        return book;
    }

escaped:   Coming Home\; A Novel;Rosamunde Pilcher;false
encoded:   Coming+Home%3B+A+Novel;Rosamunde+Pilcher;false

Step 6 · Rewrite saveLibraryState

    /**
     * Saves the state of the library to a file.
     *
     * @param filePath the path to save the file to
     * @throws LibraryStorageException if the state cannot be written
     */
    public void saveLibraryState(final String filePath)
            throws LibraryStorageException {
        try (BufferedWriter writer =
                     new BufferedWriter(new FileWriter(filePath))) {
            for (Book book : books) {
                writer.write(encode(book.getTitle()) + SEPARATOR
                        + encode(book.getAuthor()) + SEPARATOR
                        + book.isBorrowed());
                writer.newLine();
            }
        } catch (IOException e) {
            throw new LibraryStorageException(
                    "Could not save library state to " + filePath, e);
        }
    }

Two changes: every field goes through escape(), and the IOException is caught and re-thrown as a LibraryStorageException that names the file.

Step 7 · Rewrite loadLibraryState and add parseLine

    /**
     * Loads the state of the library from a file.
     * <p>
     * The current contents are replaced only once the whole file has been
     * read successfully, so a failed load never destroys the books already
     * held in memory.
     * </p>
     *
     * @param filePath the path to load the file from
     * @throws LibraryStorageException if the state cannot be read or is corrupt
     */
    public void loadLibraryState(final String filePath)
            throws LibraryStorageException {
        List<Book> loaded = new ArrayList<>();
        try (BufferedReader reader = new BufferedReader(
                new FileReader(filePath))) {
            String line;
            int lineNumber = 0;
            while ((line = reader.readLine()) != null) {
                lineNumber++;
                loaded.add(parseLine(line, lineNumber));
            }
        } catch (IOException e) {
            throw new LibraryStorageException(
                    "Could not read library state from " + filePath, e);
        }
        books.clear();
        books.addAll(loaded);
    }

    /**
     * Parses one line of the saved format into a book.
     *
     * @param line       the raw line
     * @param lineNumber the 1-based line number, used in error messages
     * @return the book the line describes
     * @throws LibraryStorageException if the line is not well formed
     */
    private Book parseLine(final String line, final int lineNumber)
            throws LibraryStorageException {
        List<String> fields = splitEscaped(line);
        if (fields.size() != FIELD_COUNT) {
            throw new LibraryStorageException("Corrupt library state at line "
                    + lineNumber + ": expected " + FIELD_COUNT
                    + " fields but found " + fields.size());
        }
        Book book = new Book(fields.get(0), fields.get(1));
        if (Boolean.parseBoolean(fields.get(2))) {
            book.borrowBook();
        }
        return book;
    }

library.addBook(new Book("Dune", "Frank Herbert"));
library.loadLibraryState("/nonexistent/nope.txt");   // throws
library.viewAvailableBooks().size();                 → 0

books.clear();
books.addAll(loaded);      // only reached on success

Corrupt library state at line 1: expected 3 fields but found 2

Step 8 · Update Main

Two catch blocks — the load at startup and the save on exit — still say IOException:

// startup
try {
    library.loadLibraryState(filePath);
    System.out.println("Library state loaded successfully.");
} catch (IOException e) {
} catch (LibraryException e) {
    System.out.println("Could not load library state. Starting fresh.");
}

// on exit
try {
    library.saveLibraryState(filePath);
    System.out.println("Library state saved successfully.");
} catch (IOException e) {
} catch (LibraryException e) {
    System.out.println(e.getMessage());
}

import java.io.IOException; can now come out of Main entirely. It stays in Library, which genuinely does I/O.

Step 8b · Understand every line you just wrote

You now have four new pieces in Library. This section walks each one, then traces a single book all the way out to disk and back. If you can narrate this, you can defend the whole change.

1 · The two codec methods

private static String encode(final String field) {
    return URLEncoder.encode(field, StandardCharsets.UTF_8);
}

private static String decode(final String field) {
    return URLDecoder.decode(field, StandardCharsets.UTF_8);
}

Percent-encoding replaces any character that is not a plain letter, digit, or one of a few safe symbols with a % followed by its byte value in hexadecimal. It is the same scheme URLs use, which is why the class lives in java.net.

2 · saveLibraryState — three things happen per book

writer.write(encode(book.getTitle()) + SEPARATOR
        + encode(book.getAuthor()) + SEPARATOR
        + book.isBorrowed());
writer.newLine();

Each field is encoded, joined with ;, and given its own line. The boolean is not encoded — true and false contain no special characters, so there is nothing to protect.

} catch (IOException e) {
    throw new LibraryStorageException(
            "Could not save library state to " + filePath, e);
}

3 · parseLine — validate, then build

String[] fields = line.split(SEPARATOR, -1);
if (fields.length != FIELD_COUNT) {
    throw new LibraryStorageException("Corrupt library state at line "
            + lineNumber + ": expected " + FIELD_COUNT
            + " fields but found " + fields.length);
}
Book book = new Book(decode(fields[0]), decode(fields[1]));
if (Boolean.parseBoolean(fields[2])) {
    book.borrowBook();
}
return book;

"Dune;;".split(";")      → [Dune]           length 1
"Dune;;".split(";", -1)  → [Dune, "", ""]   length 3

4 · loadLibraryState — the order of the last three lines

List<Book> loaded = new ArrayList<>();      // 1. a NEW list, not the real one
try (BufferedReader reader = ...) {
    String line;
    int lineNumber = 0;
    while ((line = reader.readLine()) != null) {
        lineNumber++;                        // 2. 1-based, for the message
        loaded.add(parseLine(line, lineNumber));   // 3. may throw - nothing lost yet
    }
} catch (IOException e) {
    throw new LibraryStorageException(...);  // 4. still nothing lost
}
books.clear();                               // 5. only reached if we got here
books.addAll(loaded);

Read lines 1, 5 and 6 together. Everything that can fail happens before books is touched. Compare the original:

public void loadLibraryState(final String filePath) throws IOException {
    books.clear();                          // destroyed first...
    try (BufferedReader reader = ...) {  // ...then discovered the file is missing

Trace one book, end to end

Title Coming Home; A Novel, author Rosamunde Pilcher, not borrowed.

The one semicolon that is data became %3B and never reached the splitter. The two semicolons that are structure were written by saveLibraryState itself and survive untouched. That separation — data cannot impersonate structure — is the whole idea.

The+Great+Gatsby;Fitzgerald; F. Scott;false     fields=4 -> LOAD FAILS
Good+Omens;Neil Gaiman; Terry Pratchett;false  fields=4 -> LOAD FAILS

Step 9 · See the escaping with your own eyes

mvn -q clean compile
LMS() { java -cp target/classes com.solirius.intermediate.library.Main; }

rm -f libraryState.txt
printf '1\nComing Home; A Novel\nRosamunde Pilcher\n6\n' | LMS > /dev/null
cat libraryState.txt

Coming Home\; A Novel;Rosamunde Pilcher;false

There is the fix, visible on disk: the semicolon inside the title is now preceded by a backslash, and the two separators are not. Reload it:

printf '2\n6\n' | LMS | grep -A2 'Available books:'
rm -f libraryState.txt

Available books:
Coming Home; A Novel by Rosamunde Pilcher (Available)

Rosamunde Pilcher is back.

Step 10 · Green, then approve, then commit

mvn clean test

Tests run: 5 ... in Saving and reloading the library
[ERROR] GoldenMasterTest.behavesAsApproved » Failed Approval
[ERROR] Tests run: 18, Failures: 0, Errors: 1, Skipped: 0

Everything green except the golden master, which is correct — you changed what the user sees. Check the diff is only that:

D=src/test/java/com/solirius/intermediate/library
diff -u $D/GoldenMasterTest.behavesAsApproved.approved.txt \
        $D/GoldenMasterTest.behavesAsApproved.received.txt

The entire diff is one hunk:

-Coming Home by  A Novel (Available)
+Coming Home; A Novel by Rosamunde Pilcher (Available)

mv -f $D/GoldenMasterTest.behavesAsApproved.received.txt \
      $D/GoldenMasterTest.behavesAsApproved.approved.txt
mvn clean test

[INFO] Tests run: 18, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

git add src/main/java/com/solirius/intermediate/library/Library.java
git add src/main/java/com/solirius/intermediate/library/Main.java
git add src/main/java/com/solirius/intermediate/library/exceptions/LibraryStorageException.java
git add src/test/java/com/solirius/intermediate/library/LibraryPersistenceTest.java
git add $D/GoldenMasterTest.behavesAsApproved.approved.txt

git commit -F - <<'EOF'
fix: stop the saved format losing and corrupting data

Three defects in save/load, each covered by a test added here:

- Titles containing the ';' separator were split across fields, so
  "Coming Home; A Novel" by Rosamunde Pilcher reloaded as "Coming Home"
  by " A Novel". Worse, every field shifted one place left, so the
  author was parsed as the borrowed flag and a book on loan came back
  marked available. Fields are now escaped, so any character is legal.
- A truncated line raised ArrayIndexOutOfBoundsException from parts[2].
  The field count is validated and reported with its line number.
- loadLibraryState cleared the collection before opening the file, so a
  missing or corrupt file destroyed the in-memory library. The
  replacement list is built first and swapped in only once the whole
  file has parsed, giving the strong exception guarantee.

Storage failures now raise LibraryStorageException rather than
IOException, so the console handles them alongside domain failures.
EOF

git log --oneline

Then the refactor — separately, and only if you have time

Make it work, then make it right. With the tests green you can address the design problem: Library is both a collection of books and a file format. Two reasons to change, one class.

public class Library implements LibraryRepository {

    @Override
    public void save(Library library) throws LibraryStorageException {
    }

    @Override
    public Library load() throws LibraryStorageException {
        return null;
    }

If you have already written the repository — do exactly this

Edit 1 · Add getBooks() to Library

Fixes: cannot find symbol: method getBooks()

Add this method at the end of Library, just before the closing brace:

    /**
     * Gets the books this library holds, in the order they were added.
     *
     * @return an unmodifiable view of the books
     */
    public List<Book> getBooks() {
        return Collections.unmodifiableList(books);
    }

and add one import:

import java.util.Collections;

Edit 2 · Delete the persistence code from Library

Fixes: Library.java: cannot find symbol (from encode and parseLine, which you moved to the repository)

Delete all of this from Library — it now lives in FileLibraryRepository:

• saveLibraryState(...) and loadLibraryState(...)
• parseLine(...), encode(...), decode(...)
• the SEPARATOR, FIELD_COUNT and ESCAPE constants
• every java.io, java.net and java.nio import
• the LibraryStorageException import — Library no longer throws it

Two commands confirm you got it all. Both must print nothing:

grep -nE 'saveLibraryState|loadLibraryState|parseLine|encode\(|decode\(|SEPARATOR|FIELD_COUNT|ESCAPE' \
     src/main/java/com/solirius/intermediate/library/Library.java

grep -nE 'import java\.(io|net|nio)' \
     src/main/java/com/solirius/intermediate/library/Library.java

Library.java should drop to roughly 108 lines of pure domain.

Edit 3 · Rename the test file and replace its contents

Fixes: cannot find symbol: method saveLibraryState / loadLibraryState

cd ~/Desktop/java-guild-candidate-test-intermediate-main
git mv src/test/java/com/solirius/intermediate/library/LibraryPersistenceTest.java \
       src/test/java/com/solirius/intermediate/library/FileLibraryRepositoryTest.java

Then replace the whole file with this. Your four tests are all here — three translated mechanically, and the fourth replaced for the reason explained further down:

package com.solirius.intermediate.library;

import com.solirius.intermediate.library.exceptions.LibraryStorageException;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

import static org.junit.jupiter.api.Assertions.*;

@DisplayName("The file-backed library repository")
class FileLibraryRepositoryTest {
    @TempDir
    private Path directory;

    private LibraryRepository repositoryFor(final String fileName) {
        return new FileLibraryRepository(directory.resolve(fileName).toString());
    }

    @Test
    @DisplayName("preserves a title that contains the field separator")
    void preservesATitleContainingTheSeparator() throws Exception {
        LibraryRepository repository = repositoryFor("state.txt");
        Library saved = new Library();
        saved.addBook(new Book("Coming Home; A Novel", "Rosamunde Pilcher"));
        repository.save(saved);

        Book book = repository.load().viewAvailableBooks().get(0);
        assertEquals("Coming Home; A Novel", book.getTitle());
        assertEquals("Rosamunde Pilcher", book.getAuthor());
    }

    @Test
    @DisplayName("preserves a title that contains the escape character")
    void preservesATitleContainingTheEscapeCharacter() throws Exception {
        LibraryRepository repository = repositoryFor("state.txt");
        Library saved = new Library();
        saved.addBook(new Book("AC\\DC: The Story", "Murray Engleheart"));
        repository.save(saved);

        assertEquals("AC\\DC: The Story",
                repository.load().viewAvailableBooks().get(0).getTitle());
    }


    @Test
    @DisplayName("rejects a corrupt file instead of crashing on an array index")
    void rejectsACorruptFile() throws Exception {
        Path file = directory.resolve("state.txt");
        Files.write(file, List.of("Dune;Frank Herbert"));   // only 2 fields

        LibraryStorageException thrown = assertThrows(LibraryStorageException.class,
                () -> repositoryFor("state.txt").load());

        assertEquals("Corrupt library state at line 1: "
                + "expected 3 fields but found 2", thrown.getMessage());
    }

    @Test
    @DisplayName("reports a missing file rather than returning an empty library")
    void reportsAMissingFileRatherThanReturningAnEmptyLibrary() {
        assertThrows(LibraryStorageException.class,
                () -> repositoryFor("absent.txt").load(),
                "a missing file must be reported, not silently treated as empty");
    }
}

Edit 3b · The six changes inside the test file, one at a time

If you have already renamed the class but the body still calls saveLibraryState, here are the exact edits. There are six, and nothing else in the file changes — every assertion stays as it is.

- @DisplayName("Library data persistence")
+ @DisplayName("The file-backed library repository")

  @TempDir
  private Path directory;

+
+ private LibraryRepository repositoryFor(final String fileName) {
+     return new FileLibraryRepository(directory.resolve(fileName).toString());
+ }

- Path file = directory.resolve("state.txt");
+ LibraryRepository repository = repositoryFor("state.txt");

  Library saved = new Library();
  saved.addBook(new Book("Coming Home; A Novel", "Rosamunde Pilcher"));
- saved.saveLibraryState(file.toString());
+ repository.save(saved);

- Library reloaded = new Library();
- reloaded.loadLibraryState(file.toString());
-
- Book book = reloaded.viewAvailableBooks().get(0);
+ Book book = repository.load().viewAvailableBooks().get(0);

  assertEquals("Coming Home; A Novel", book.getTitle());     // unchanged
  assertEquals("Rosamunde Pilcher", book.getAuthor());       // unchanged

- Path file = directory.resolve("state.txt");
+ LibraryRepository repository = repositoryFor("state.txt");
  Library saved = new Library();
  saved.addBook(new Book("AC\DC: The Story", "Murray Engleheart"));
- saved.saveLibraryState(file.toString());
-
- Library reloaded = new Library();
- reloaded.loadLibraryState(file.toString());
+ repository.save(saved);

  assertEquals("AC\DC: The Story",
-         reloaded.viewAvailableBooks().get(0).getTitle());
+         repository.load().viewAvailableBooks().get(0).getTitle());

  LibraryStorageException thrown = assertThrows(LibraryStorageException.class,
-         () -> new Library().loadLibraryState(file.toString()));
+         () -> repositoryFor("state.txt").load());

- @DisplayName("leaves the library untouched when the file cannot be read")
- void leavesTheLibraryUntouchedWhenTheFileCannotBeRead() {
-     Library library = new Library();
-     library.addBook(new Book("Dune", "Frank Herbert"));
-
-     assertThrows(LibraryStorageException.class,
-             () -> library.loadLibraryState(
-                     directory.resolve("absent.txt").toString()));
-
-     assertEquals(1, library.viewAvailableBooks().size(),
-             "a failed load must not destroy the books already held");
- }
+ @DisplayName("reports a missing file rather than returning an empty library")
+ void reportsAMissingFileRatherThanReturningAnEmptyLibrary() {
+     assertThrows(LibraryStorageException.class,
+             () -> repositoryFor("absent.txt").load(),
+             "a missing file must be reported, not silently treated as empty");
+ }

What the imports should look like afterwards

All of your existing imports are still needed — Files, Path and List are all still used by rejectsACorruptFile. Nothing to add and nothing to remove.

Then run it

mvn clean test

[INFO] Tests run: 17, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.FileReader;
import java.io.FileWriter;
import java.io.IOException;

mvn checkstyle:check -Dcheckstyle.failOnViolation=false -Dcheckstyle.consoleOutput=true

The shape it should be: three roles, three types

Library does not implement the interface. A separate class does, and Library becomes the thing it is handed.

Step A · Take persistence out of Library

Delete saveLibraryState, loadLibraryState, parseLine, encode, decode, the SEPARATOR and FIELD_COUNT constants, and every java.io / java.net import. Library drops to about a hundred lines of pure domain.

It needs one new method, so a repository can read what to save:

/**
 * Gets the books this library holds, in the order they were added.
 *
 * @return an unmodifiable view of the books
 */
public List<Book> getBooks() {
    return Collections.unmodifiableList(books);
}

Step B · The interface

package com.solirius.intermediate.library;

import com.solirius.intermediate.library.exceptions.LibraryStorageException;

/**
 * Stores and retrieves the state of a library.
 * <p>
 * The domain depends on this abstraction rather than on a file, so an
 * alternative store - a portable database, for instance - can be added as a
 * new implementation without changing {@link Library}.
 * </p>
 */
public interface LibraryRepository {

    /**
     * Saves the given library, replacing anything previously stored.
     *
     * @param library the library to store
     * @throws LibraryStorageException if the state cannot be written
     */
    void save(Library library) throws LibraryStorageException;

    /**
     * Loads the stored library.
     *
     * @return the stored library
     * @throws LibraryStorageException if the state cannot be read or is corrupt
     */
    Library load() throws LibraryStorageException;
}

Note there is no file path in either signature. That is deliberate: a path is a detail of this implementation. A database version would need a connection string instead, and the interface should not have to change.

Step C · The implementation

The path goes in the constructor, so each repository instance knows where its own state lives:

public class FileLibraryRepository implements LibraryRepository {

    /** Field separator used by the flat-file format. */
    private static final String SEPARATOR = ";";
    /** Number of fields on every well-formed line. */
    private static final int FIELD_COUNT = 3;

    /** Where the state is kept. */
    private final String filePath;

    /**
     * Creates a repository backed by the given file.
     *
     * @param theFilePath the file to read from and write to
     */
    public FileLibraryRepository(final String theFilePath) {
        this.filePath = theFilePath;
    }

save is your old saveLibraryState, with two changes: no path parameter (it is a field now), and the books come from the argument:

    @Override
    public void save(final Library library) throws LibraryStorageException {
        try (BufferedWriter writer =
                     new BufferedWriter(new FileWriter(filePath))) {
            for (Book book : library.getBooks()) {
                writer.write(encode(book.getTitle()) + SEPARATOR
                        + encode(book.getAuthor()) + SEPARATOR
                        + book.isBorrowed());
                writer.newLine();
            }
        } catch (IOException e) {
            throw new LibraryStorageException(
                    "Could not save library state to " + filePath, e);
        }
    }

load is your old loadLibraryState, with one addition at the end — it must build and return a library rather than mutate one:

    @Override
    public Library load() throws LibraryStorageException {
        List<Book> loaded = new ArrayList<>();
        try (BufferedReader reader = new BufferedReader(
                new FileReader(filePath))) {
            String line;
            int lineNumber = 0;
            while ((line = reader.readLine()) != null) {
                lineNumber++;
                loaded.add(parseLine(line, lineNumber));
            }
        } catch (IOException e) {
            throw new LibraryStorageException(
                    "Could not read library state from " + filePath, e);
        }
        Library library = new Library();
        for (Book book : loaded) {
            library.addBook(book);
        }
        return library;
    }

Step D · Wire it in Main

// before
Library library = new Library();
String filePath = "libraryState.txt";
try {
    library.loadLibraryState(filePath);
    System.out.println("Library state loaded successfully.");
} catch (LibraryStorageException e) {
    System.out.println("Could not load library state. Starting fresh.");
}

// after
String filePath = "libraryState.txt";
LibraryRepository repository = new FileLibraryRepository(filePath);

Library library;
try {
    library = repository.load();
    System.out.println("Library state loaded successfully.");
} catch (LibraryStorageException e) {
    library = new Library();          // no stored state yet - start empty
    System.out.println("Could not load library state. Starting fresh.");
}

and on exit:

library.saveLibraryState(filePath);
repository.save(library);

Step E · Move the tests, change no assertions

Rename LibraryPersistenceTest to FileLibraryRepositoryTest and swap how the subject is built. The assertions stay byte for byte identical:

// before
Library saved = new Library();
saved.addBook(new Book("Coming Home; A Novel", "Rosamunde Pilcher"));
saved.saveLibraryState(file.toString());

Library reloaded = new Library();
reloaded.loadLibraryState(file.toString());
Book book = reloaded.viewAvailableBooks().get(0);

// after
LibraryRepository repository =
        new FileLibraryRepository(directory.resolve("state.txt").toString());
Library saved = new Library();
saved.addBook(new Book("Coming Home; A Novel", "Rosamunde Pilcher"));
repository.save(saved);

Book book = repository.load().viewAvailableBooks().get(0);

// unchanged
assertEquals("Coming Home; A Novel", book.getTitle());
assertEquals("Rosamunde Pilcher", book.getAuthor());

Checkpoint · what is left, from wherever you are

The refactor has four moving parts and they must all land before anything compiles. It is normal for the build to be red in the middle of it. Use the compiler as your to-do list:

/**
 * Gets the books this library holds, in the order they were added.
 *
 * @return an unmodifiable view of the books
 */
public List<Book> getBooks() {
    return Collections.unmodifiableList(books);
}

grep -nE 'saveLibraryState|loadLibraryState|parseLine|encode\(|decode\(|SEPARATOR|FIELD_COUNT' \
     src/main/java/com/solirius/intermediate/library/Library.java

grep -nE 'import java\.(io|net|nio)' \
     src/main/java/com/solirius/intermediate/library/Library.java

Migrating your four persistence tests

Three are mechanical. The fourth is not, and it is the interesting one.

library.loadLibraryState(path);                          // mutates 'library'
assertEquals(1, library.viewAvailableBooks().size());    // did it survive?

Library load() throws LibraryStorageException;

What to replace it with

Deleting a test without replacing it should always make you uneasy, so ask: what is the new risk in this area? It is no longer “destroys existing data”. It is that load() might silently return an empty library when the file is unreadable, which would look like success and quietly wipe the user’s catalogue on the next save.

@Test
@DisplayName("reports a missing file rather than returning an empty library")
void reportsAMissingFileRatherThanReturningAnEmptyLibrary() {
    assertThrows(LibraryStorageException.class,
            () -> repositoryFor("absent.txt").load(),
            "a missing file must be reported, not silently treated as empty");
}

The finished test file

package com.solirius.intermediate.library;

import com.solirius.intermediate.library.exceptions.LibraryStorageException;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

import static org.junit.jupiter.api.Assertions.*;

@DisplayName("The file-backed library repository")
class FileLibraryRepositoryTest {
    @TempDir
    private Path directory;

    private LibraryRepository repositoryFor(final String fileName) {
        return new FileLibraryRepository(directory.resolve(fileName).toString());
    }

    @Test
    @DisplayName("preserves a title that contains the field separator")
    void preservesATitleContainingTheSeparator() throws Exception {
        LibraryRepository repository = repositoryFor("state.txt");
        Library saved = new Library();
        saved.addBook(new Book("Coming Home; A Novel", "Rosamunde Pilcher"));
        repository.save(saved);

        Book book = repository.load().viewAvailableBooks().get(0);
        assertEquals("Coming Home; A Novel", book.getTitle());
        assertEquals("Rosamunde Pilcher", book.getAuthor());
    }

    @Test
    @DisplayName("preserves a title that contains the escape character")
    void preservesATitleContainingTheEscapeCharacter() throws Exception {
        LibraryRepository repository = repositoryFor("state.txt");
        Library saved = new Library();
        saved.addBook(new Book("AC\\DC: The Story", "Murray Engleheart"));
        repository.save(saved);

        assertEquals("AC\\DC: The Story",
                repository.load().viewAvailableBooks().get(0).getTitle());
    }


    @Test
    @DisplayName("rejects a corrupt file instead of crashing on an array index")
    void rejectsACorruptFile() throws Exception {
        Path file = directory.resolve("state.txt");
        Files.write(file, List.of("Dune;Frank Herbert"));   // only 2 fields

        LibraryStorageException thrown = assertThrows(LibraryStorageException.class,
                () -> repositoryFor("state.txt").load());

        assertEquals("Corrupt library state at line 1: "
                + "expected 3 fields but found 2", thrown.getMessage());
    }

    @Test
    @DisplayName("reports a missing file rather than returning an empty library")
    void reportsAMissingFileRatherThanReturningAnEmptyLibrary() {
        assertThrows(LibraryStorageException.class,
                () -> repositoryFor("absent.txt").load(),
                "a missing file must be reported, not silently treated as empty");
    }
}

Note the repositoryFor helper: one line, and it keeps every test from repeating the directory.resolve(...).toString() plumbing. Note also that the tests are typed against LibraryRepository, not FileLibraryRepository — so the same suite could be pointed at a future SQLite implementation with one line changed.

[INFO] Tests run: 17, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Commit it separately — and write the message carefully

This is the commit where a reviewer decides whether you understand what a refactor is. Get it green first, then use this message.

cd ~/Desktop/java-guild-candidate-test-intermediate-main
mvn clean test          # 17 green, golden master among them

git add src/main/java/com/solirius/intermediate/library/LibraryRepository.java
git add src/main/java/com/solirius/intermediate/library/FileLibraryRepository.java
git add src/main/java/com/solirius/intermediate/library/Library.java
git add src/main/java/com/solirius/intermediate/library/Main.java
git add src/test/java/com/solirius/intermediate/library/

git commit -F - <<'EOF'
refactor: move persistence out of Library into a repository

Library was two things at once: the rules about borrowing books, and the
format those books are stored in. That gave it two unrelated reasons to
change - a new lending rule, or a new file layout - and meant the domain
class carried java.io and java.net imports it had no business knowing
about.

Persistence now sits behind a LibraryRepository interface, implemented by
FileLibraryRepository, which owns the separator, the percent-encoding and
the line parsing. Library keeps only the book rules and exposes
getBooks(), an unmodifiable view the repository reads from. Main builds
the repository and is the only place that names the concrete type.

This matters beyond tidiness: the Advanced tier of the brief asks for a
portable file-based database, and the pom already declares sqlite-jdbc.
With this seam, that becomes a new class implementing the same interface
and a one-line change in Main. Without it, it is a rewrite of Library.

One test was removed rather than translated. It asserted that a failed
load left the in-memory books untouched, but load() now returns a new
Library instead of mutating one, so it has no access to the caller's
state and that failure mode cannot occur. It is replaced by a test for
the risk the new design does carry: that an unreadable file is reported
rather than quietly coming back as an empty library.

No behaviour change. The tests moved to FileLibraryRepositoryTest but no
assertion was altered, and the golden master passes against its existing
approved file.
EOF

git log --oneline

Why that message is shaped the way it is

Five paragraphs, each doing a job the diff cannot do for you.

Drill

Read this

Carry on

• Reference card: Defect inventory
• Next: Lesson 0006 — Making Main Testable

If you want to attempt the Advanced SQLite repository, tell me — it is a good use of an evening only once everything else is finished and committed.