2  Part I — Start with what you already know

Steps 1 to 10 stay inside one JVM. The system is built three times: as direct calls, as three capabilities that refuse to know each other, and as those same capabilities glued together by mediators. Nothing is distributed yet, and that is the point: the only thing that changes is who knows whom.

2.1 Step 1 — Rock bottom: just call it

ProceduralRot13.java is the whole system in one compact source file: a loop that reads a line, and one statement that prints the rotated text.

void main() {
    while (true) {
        var text = IO.readln();

        if (text == null)
            return;

        IO.println(rot13(text));
    }
}

IO.readln() stands on its own line, but rot13(text) is not a step of its own: it is called inside the argument of IO.println. Neither rot13 nor IO.println knows anything about the other. The one that knows both is main(), which names them and fixes their order.

What main() knows about rot13: that it exists, how to invoke it (a bare name, both live in the same implicitly generated class), what argument it takes, what it returns, that it is available right now, and that execution continues after it returns. It does not know how rot13 is implemented — that is the one thing it can ignore.

The availability guarantee is worth naming, because it disappears later: main() and rot13 are two methods of one already-loaded class, called on the same thread, in the same process. Nothing has to be started first, no message travels anywhere, no listener has to be subscribed.

Observed: typing a line prints it rotated; Ctrl+D ends the program silently, because IO.readln() returns null and main() returns.

Figure 2.1: The procedural version. The wiring is written into the code: main() names all three parts and fixes their order.

2.2 Step 2 — Three egoistic capabilities

An egoistic component says: I know what I can do, what data I accept and what data I produce — and I would rather not know the business process around me. Concretely, ConsoleIn must not contain rot13(...), and ROT13 must not contain consoleOut(...).

Removing those calls immediately creates a problem, which the tutorial states as a question: if nobody knows anybody, who makes this into a system? Note what the question does not say: the knowledge is not gone, it has to go somewhere else. Two connections are missing, not one — ConsoleIn ↔︎ ROT13 and ROT13 ↔︎ ConsoleOut.

2.3 Step 3 — Give every capability a mailbox

The smallest mechanism for the missing connections: a message and a named queue.

record Message(String type, String value) {}

Map<String, BlockingQueue<Message>> mailboxes = new ConcurrentHashMap<>();

BlockingQueue<Message> mailbox(String name) {
    return mailboxes.computeIfAbsent(name, _ -> new LinkedBlockingQueue<>());
}

The tutorial insists on calling these mailboxes, not topics, and gives the reason: if two readers call take() on the same mailbox, they compete — each message goes to exactly one of them and is not copied to both. A topic, in Publish/Subscribe, would hand every subscriber its own copy. One reader per message is enough for now, and the limitation is kept on purpose: it is what makes it clear later what Publish/Subscribe actually adds.

2.4 Steps 4–6 — The three capabilities become egoistic

Each capability now touches only its own mailbox names:

Capability reads writes
ConsoleIn the keyboard consoleIn.outbox
ROT13 rot13.inbox rot13.outbox
ConsoleOut consoleOut.inbox the console

No capability contains the name of another. The tutorial’s own summary of the result: “three nicely isolated capabilities. And they do absolutely nothing together.” Nothing moves a message from consoleIn.outbox to rot13.inbox, or from rot13.outbox to consoleOut.inbox.

2.5 Step 7 — Enter the mediator

The smallest possible glue: a loop that takes from one mailbox and puts into another, knowing nothing about what travels through it.

void mediate(String from, String to) {
    while (true)
        mailbox(to).put(mailbox(from).take());
}

main() starts five virtual threads: the three capabilities, plus two mediators whose routes are given as arguments — consoleIn.outbox → rot13.inbox and rot13.outbox → consoleOut.inbox.

Observed: Hello World in, Uryyb Jbeyq out, exactly as in step 1. But Ctrl+D no longer ends the program. ConsoleIn’s thread returns (it does not loop), and the other four threads sit blocked in take() on empty mailboxes, using no CPU. What actually keeps the process alive is the last line of main(), Thread.currentThread().join(): the main thread waits for itself, which can never finish. Virtual threads are daemon threads, so those four waiting threads would not have kept the JVM running on their own.

Figure 2.2: The mediated version inside one JVM. In the web version, Play walks one message through all eight hops.

2.6 Step 8 — Ask again: who knows whom?

Does ConsoleIn know ROT13? No. Does ROT13 know ConsoleIn or ConsoleOut? No. Has the topology disappeared? No — it sits in the two mediate(...) calls inside main().

This is the tutorial’s first major result:

Decoupling often does not make knowledge disappear. It moves knowledge to where it belongs.

The capability “ROT13 transforms text” belongs to ROT13. The topology ConsoleIn → ROT13 → ConsoleOut belongs to system composition. What changed since step 1 is not that the wiring left main() — it is still there — but that it is no longer written inside a capability. It is now data: two pairs of mailbox names. Rewiring touches those two lines and no capability at all.

2.7 Step 9 — Why virtual threads?

Five loops now wait indefinitely: the keyboard, rot13.inbox, consoleOut.inbox and the two mediators’ sources. Virtual threads are simply the cheap Java way to let five waits happen at once inside one JVM.

They are an implementation convenience, not an architecture. The architecture — who knows whom, and where the wiring lives — is in the mailbox names, not in the threads. The tutorial’s own evidence for the separation: the same architecture will run as separate processes in step 11, with no threads shared between the parts.

2.8 Step 10 — Keep the services egoistic

The obvious shortcut: the first mediator only copies messages unchanged, so why not delete it and let ROT13 take() from consoleIn.outbox directly?

Because ROT13 would then contain the name consoleIn.outbox, which means it would know that ConsoleIn exists and where it publishes. The topology would move into ROT13, and ROT13 would stop being an egoistic capability. The test that makes this concrete: suppose the input comes from a new FileIn capability publishing to fileIn.outbox.

with the mediator with the shortcut
what changes one argument of the mediator runRot13 itself
who is touched no capability ROT13, whose job did not change

The tutorial is honest about the price: this design “may look indirect — even a little odd”, and it promises a different way to keep services egoistic without a mediator in every message’s path.

2.9 What part I moved

stage where the topology lives who could rewire it
step 1 inside the capability code (IO.println(rot13(text))) whoever edits that code
steps 7–8 in main(), as pairs of mailbox names whoever edits main()

Functionality: unchanged. Lines of code: more. Parts that know each other: none. That is the trade the rest of the tutorial keeps testing.