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.

Write the failing tests first

@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());
}

The red bar

[ERROR] Tests run: 13, Failures: 3, Errors: 0, Skipped: 0

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

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

leavesTheLibraryUntouchedWhenTheFileCannotBeRead:57
  expected: <1> but was: <0>

Three failures, three distinct defects. Take them in order.

Defect one · a delimiter that occurs in the data

writer.write(book.getTitle() + ";" + book.getAuthor() + ";" + book.isBorrowed());

Book titles contain semicolons. Coming Home; A Novel is a real book. So is Roget’s Thesaurus; or, Classified Collection of Words. When one is saved, the file contains four fields on a line the reader splits into three, and the reader takes the first three:

file:       Coming Home; A Novel;Rosamunde Pilcher;false
split(";"): ["Coming Home", " A Novel", "Rosamunde Pilcher", "false"]
parsed as:  title="Coming Home"  author=" A Novel"  isBorrowed=false
displayed:  Coming Home by  A Novel (Available)

Rosamunde Pilcher is gone. No exception, no warning, no log line. The user sees a book with a mangled title and an author that is half a title, and nothing anywhere records that data was destroyed.

Fixing it: three options, ranked

/** Protects separator and escape characters inside a field. */
private static String escape(final String field) {
    return field.replace(ESCAPE, ESCAPE + ESCAPE)     // backslash first!
                .replace(SEPARATOR, ESCAPE + SEPARATOR);
}

Defect two · a parser that trusts its input

String[] parts = line.split(";");
String title = parts[0];
String author = parts[1];
boolean isBorrowed = Boolean.parseBoolean(parts[2]);

Truncate the file — a disk fills, a process is killed mid-write, someone edits it by hand — and you get:

java.lang.ArrayIndexOutOfBoundsException: Index 2 out of bounds for length 2

Which tells the user nothing at all. Validate the field count, and say what is wrong and where:

if (fields.size() != FIELD_COUNT) {
    throw new LibraryStorageException("Corrupt library state at line "
            + lineNumber + ": expected " + FIELD_COUNT
            + " fields but found " + fields.size());
}

Note the line number. An exception that names the line is an exception someone can act on.

Defect three · destroy first, fail second

This is the subtlest of the three and the best one to have spotted.

public void loadLibraryState(final String filePath) throws IOException {
    books.clear();                              // happens first
    try (BufferedReader reader = new BufferedReader(new FileReader(filePath))) {
        ...                                     // this is what can fail
    }
}

The library is emptied before the file is opened. If the file is missing, unreadable, or corrupt halfway through, the books already in memory are gone and the exception arrives too late to matter. Verified:

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

The fix is to build the replacement completely, and only then swap it in:

List<Book> loaded = new ArrayList<>();
try (BufferedReader reader = ...) {
    while ((line = reader.readLine()) != null) {
        loaded.add(parseLine(line, ++lineNumber));   // may throw; nothing lost yet
    }
} catch (IOException e) {
    throw new LibraryStorageException("Could not read library state from " + filePath, e);
}
books.clear();
books.addAll(loaded);                                  // only reached on success

Green, and then the refactor

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

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

public interface LibraryRepository {
    void save(Library library) throws LibraryStorageException;
    Library load()             throws LibraryStorageException;
}

public class FileLibraryRepository implements LibraryRepository { ... }

Drill

Commit it

Stop the saved format losing and corrupting data

Three defects in save/load, each found by a test added in this commit:

- Titles containing the ';' separator were split across fields, so
  "Coming Home; A Novel" by Rosamunde Pilcher reloaded as "Coming Home"
  by " A Novel". Fields are now escaped, so any character is legal.
- A truncated line raised ArrayIndexOutOfBoundsException. The field
  count is now validated and reported with its line number.
- loadLibraryState cleared the collection before opening the file, so
  a failed load destroyed the in-memory library. The replacement is
  built first and swapped in only once the whole file has parsed.

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.