Project: build a console app end to end

When this course began, an empty file was a mystery and printing one line felt like a win. Since then you have learned objects and interfaces, records, lists and maps, exceptions, files and streams, one idea at a time. This lesson adds no new keyword. It does the thing all of those lessons were building toward: it takes them together and builds one small program, end to end, that remembers its data between runs.

This is where it comes together#

Up to now each lesson taught one idea at a time. A loop here, a constructor there. Real programs are not like that. A real program is many small ideas working at once: a record holds some data, a list holds many records, a map remembers who has what, a method changes it, an exception reports what went wrong, and a file keeps it all when the program stops. Engineering is the skill of fitting those pieces together so the whole thing does something useful and does not fall over.

Key idea

Learning the pieces and building with the pieces are two different skills. You have the first. This lesson is a full practice run at the second.

We will build a small library manager: a program that keeps a catalogue of books, lets people borrow and return them, shows what is still on the shelf, and saves the catalogue to a file so it is still there next time. Small enough to finish, real enough to feel like software. We design it first, build the core and run it at every step, and add the keyboard menu last.

Step one: design the classes#

Before any Java, ask the two questions from why objects exist: what things are in this program, and for each thing, what does it have and what can it do? Read the description and underline the nouns.

“A library keeps a catalogue of books. People can borrow a book and return it. The catalogue is saved to a file.” The nouns give you the shape. A Book is one entry in the catalogue. A Library holds all the books and knows who has which. The file is not a class at all: it is somewhere the library writes to and reads from.

Step two: the Book, as a record#

A book's title and author never change, which is exactly what a record is for. One line gives you the constructor, the accessors title() and author(), a readable toString, and an equals that compares the contents. Run it and step through.

It prints Dune by Herbert, then Book[title=Dune, author=Herbert], then true and false. The memory view shows two separate Book objects, so ==, which asks “is this the same object?”, says no. equalsasks “do they hold the same title and author?”, and a record answers that for you. That matters more than it looks, because lists and maps use equals when they search.

Step three: the Library, with a List and a Map#

Now the class that does the work. It holds a List<Book> for the catalogue and a Map<String, String> for the loans, from a title to the name of the person who has it. Each method does one job:

1. 1add: put a book in the list. The list grows by itself, so there is no size to worry about.
2. 2find: walk the list and return the book whose title matches, ignoring upper and lower case. If there is none, return an empty Optional rather than null.
3. 3borrow: find the book; if it is not already in loans, put it there with the borrower's name.
4. 4giveBack: find the book and remove its loan.
5. 5onShelf: the titles of every book that is not in loans, built with a stream.

Here it is, running. Step through and watch the list fill up, then watch an entry appear in the map when Emma is borrowed and disappear again when she comes back.

Trace what happened. Three add calls put three books in the list. borrow("Emma", "Asha") finds Emma and records the loan, so the map holds {Emma=Asha} and the next shelf listing leaves her out. borrow("Mistborn", "Ravi") finds nothing, and the empty Optional leads to a polite message instead of a crash. giveBack("Emma") removes the loan, and the last listing shows all three books again.

A map keeps one value per key, which is exactly what a loan needs: one book, one borrower. Check that you know what happens when the same key is used twice.

The second put("Dune", ...)replaces Ravi with Asha without a word of warning. Ravi's loan is simply lost. That is why borrow checks containsKey before it calls put: the map will not stop you, so the method has to.

Step four: failures as exceptions#

The Library above has a quiet flaw: when something goes wrong, it prints a message itself. That ties the logic to the console. A window could not show that message, a test could not check it, and the code that called borrow has no idea it failed. The fix, from exceptions, is to report the failure and let the caller decide what to tell the user.

A failure that belongs to your program deserves an exception of its own, so give the library one. LibraryException extends Exception, which makes it a checked exception: any method that can throw it must say so with throws LibraryException, and any caller must either catch it or pass it on. The compiler will not let anyone forget that borrowing can fail.

It prints Asha borrowed Emma, then Sorry, Ravi: Emma is out with Asha, then Sorry, Ravi: there is no book called Mistborn. Look at borrow now: it prints nothing. orElseThrow either hands back the book inside the Optional or throws the exception the lambda builds. A second throw covers a book that is already out. Every message is decided in main, in the one catch block. The fields are now private too, so nothing outside the class can change the loans behind its back, as in encapsulation.

Key idea

The class that finds a problem should report it, not decide how to show it. Throw where you find the problem; catch where you can do something about it.

1import java.util.*;
2 
3public class Main {
4    public static void main(String[] args) {
5        Library library = new Library();
6        library.add(new Book("Dune", "Herbert"));
7        library.add(new Book("Emma", "Austen"));
8        try {
9            library.borrow("Emma", "Asha");
10        } catch (LibraryException e) {
11            System.out.println("Sorry: " + e.getMessage());
12        }
13 
14        String[] returns = {"Emma", "Emma", "Mistborn"};
15        for (String title : returns) {
16            try {
17                library.giveBack(title);
18                System.out.println(title + " is back on the shelf");
19            } catch (LibraryException e) {
20                System.out.println("Sorry: " + e.getMessage());
21            }
22        }
23    }
24}
25 
26record Book(String title, String author) {}
27 
28class LibraryException extends Exception {
29    LibraryException(String message) {
30        super(message);
31    }
32}
33 
34class Library {
35    private final List<Book> books = new ArrayList<>();
36    private final Map<String, String> loans = new HashMap<>();
37 
38    void add(Book book) {
39        books.add(book);
40    }
41 
42    Optional<Book> find(String title) {
43        for (Book b : books) {
44            if (b.title().equalsIgnoreCase(title)) {
45                return Optional.of(b);
46            }
47        }
48        return Optional.empty();
49    }
50 
51    void borrow(String title, String who) throws LibraryException {
52        Book book = find(title)
53                .orElseThrow(() -> new LibraryException("there is no book called " + title));
54        String holder = loans.get(book.title());
55        if (holder != null) {
56            throw new LibraryException(book.title() + " is out with " + holder);
57        }
58        loans.put(book.title(), who);
59    }
60 
61    void giveBack(String title) throws LibraryException {
62        // TODO: throw a LibraryException if there is no book with this title,
63        // or if the book is not out. Otherwise remove its loan.
64    }
65}

Step five: remembering between runs#

So far the library forgets everything the moment the program ends. To remember, it writes the catalogue to a file and reads it back next time, with the Files methods from files with java.nio. The format is as plain as it gets: one line per book, the title and the author separated by a semicolon.

It prints Saved: [Dune;Herbert, Emma;Austen] and Loaded 2 books: [Dune, Emma], and the Files panel shows library.txt with its two lines. save turns each book into one line and writes them all at once. load does the reverse: it reads every line, splits it at the semicolon, and builds a Bookfrom the two parts. The second library never saw the first one's objects. It got everything from the file, which is exactly what will happen when the real program starts up tomorrow.

Step six: the keyboard menu#

The logic is done, and every piece of it has run. The last piece lets a person drive it from the keyboard. Here is the finished program. It starts by loading library.txt, which already holds three books, and the keyboard box below it holds what a user types: look at the shelf, borrow Emma, try two loans that fail, add a book, try a bad return, mistype the menu, then quit. Run it, then change the input and run it again.

Dune;Herbert
Emma;Austen
Solaris;Lem

Look at how thin the menu is. Each case reads what it needs and calls one method on library. The switch with arrows, from if-else and switch, needs no break. One try wraps the whole switch, so a failed borrow or return prints its message and the loop simply shows the menu again. And when the user picks 0, the loop ends and the catalogue is saved, Middlemarch included: the Files panel shows four lines now.

Key idea

Keep your logic apart from your input and output. Logic you can test on its own is logic you can trust. The menu is just a steering wheel; the engine is the classes underneath.

What comes next#

This project closes the core of the course, and it is a fair picture of what you can build with the language alone. The phases after it add the things real software leans on.

• Phase 7, concurrency. Doing several things at once, from your first threads to thread pools and virtual threads. A library server answering many users at the same time would need it.
• Phase 8, tools of the trade. Git to keep every version of this project, and Maven and Gradle to build it with libraries and tests the way teams do.
• Phase 9, data and the web. A real database instead of a text file, starting with SQL and JDBC, and then a web service that other programs can talk to, which ends in a second, bigger project.
• Desktop apps with JavaFX. An elective track that puts windows and buttons in front of programs like this one, starting with what a window really is.

The course so far, on one map#

Here is the route through the first six phases, so you can see how each idea sat on the one before it. Every link goes back to where it was taught.

Phase 1: first steps

From an empty file to collections of values. setup and the JVM, variables and types, operators and casting, if-else and switch, loops, arrays, ArrayList, two-dimensional arrays and reading errors.

Phase 2: objects

Where Library and the habit of designing classes came from. why objects, classes and objects, methods, constructors, encapsulation, this and references, inheritance, overriding and super, polymorphism, OOP practice, strings, string practice and testing with JUnit.

Phase 3: abstraction and design

Where Book became a record. abstract classes, interfaces, choosing between them, static and final, inner classes, enums and lambdas, records, sealed types and patterns and design principles.

Phase 4: collections and algorithms

Where the catalogue and the loans came from. wrapper classes, generics, the collections family, HashMap and HashSet, object equality, comparing and sorting, stacks and queues, linked lists, recursion, Big O, searching and sorting and building your own.

Phase 5: errors, files and the standard library

Where LibraryException, library.txt and the menu came from. packages and imports, Scanner and the console, reading files, writing files, exception handling, files with java.nio, dates and times, money with BigDecimal and regular expressions.

Phase 6: functional and modern Java

Where onShelf and find got their shape. streams, collectors, Optional, modern syntax and annotations and tooling.