[
{
"objectID": "index.html",
"href": "index.html",
"title": "Process Control",
"section": "",
"text": "About these notes\nThese notes follow one small program through a long series of rebuilds, from direct method calls to an event-driven architecture over MQTT. Every rebuild leaves the program doing exactly what it did before, and changes who knows about whom.\nThe program under construction never changes: you type a line, it comes back rotated by 13 letters.\nWhat changes is everything around it. The same system is rebuilt again and again, and each rebuild asks three questions, in this order:\nOne summary is added here each time a step is finished, so the book grows at the pace of the work. Each summary says what the step did, what was observed when it ran, and what moved architecturally — usually a piece of knowledge that changed hands.\nBased on material by Reto Konig, University of Fribourg.",
"crumbs": [
"[About these notes]{.en}[À propos de ces notes]{.fr}[Über diese Notizen]{.de}"
]
},
{
"objectID": "index.html#sec-diagrams",
"href": "index.html#sec-diagrams",
"title": "Process Control",
"section": "How to read the diagrams",
"text": "How to read the diagrams\nEvery diagram exists once as a drawing and three times as a language. In the web version, a diagram that carries a message flow has a small play bar under it: Play walks one message through the whole chain, One hop advances a single step, and Reset puts it back. Boxes light up as the message reaches them, so you can see which component is waiting and which one is working.\nIn the PDF, and in a browser with JavaScript switched off, the same picture is there — just still. Nothing in the notes depends on the animation.",
"crumbs": [
"[About these notes]{.en}[À propos de ces notes]{.fr}[Über diese Notizen]{.de}"
]
},
{
"objectID": "00-orientation.html",
"href": "00-orientation.html",
"title": "1 Step 0 — What this is about",
"section": "",
"text": "1.1 The three questions\nStep 0 contains no code. It states the subject: not ROT13, but the architecture around it. The functionality stays almost unchanged for 81 steps, which is what makes the changes around it visible.\nTwo rules are set here and hold all the way through:\nThat is why the build-up does not start with MQTT, and not with dynamic subscriptions either. A system with deliberately awkward mediators is built first, put into operation, and only then asked whether those mediators have earned their place.\nThe second rule is about vocabulary: Intent, Status/State and Event are named only after they have been used. They appear around step 42, not before.\nThe planned route, from step 0:\nThe wording of the three questions matters, and it is easy to replace it with something weaker:\n“Knowing” is not “communicating”: two components can exchange messages all day without either one naming the other. “Deciding the wiring” is not “connecting”: the part that forwards messages need not be the part that chose the route. Both distinctions become concrete later — the first already in step 1, the second in part III.",
"crumbs": [
"1 [Step 0 — What this is about]{.en}[Étape 0 — De quoi il s'agit]{.fr}[Schritt 0 — Worum es geht]{.de}"
]
},
{
"objectID": "00-orientation.html#sec-three-questions",
"href": "00-orientation.html#sec-three-questions",
"title": "1 Step 0 — What this is about",
"section": "",
"text": "As asked here\nA weaker version\n\n\n\n\nWho knows whom?\nwho communicates with whom\n\n\nWho owns what?\nwhich data each part holds\n\n\nWho decides how the system is wired?\nwhich part connects everything",
"crumbs": [
"1 [Step 0 — What this is about]{.en}[Étape 0 — De quoi il s'agit]{.fr}[Schritt 0 — Worum es geht]{.de}"
]
},
{
"objectID": "01-part-i-calls.html",
"href": "01-part-i-calls.html",
"title": "2 Part I — Start with what you already know",
"section": "",
"text": "2.1 Step 1 — Rock bottom: just call it\nSteps 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.\nProceduralRot13.java is the whole system in one compact source file: a loop that reads a line, and one statement that prints the rotated text.\nIO.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.\nWhat 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.\nThe 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.\nObserved: typing a line prints it rotated; Ctrl+D ends the program silently, because IO.readln() returns null and main() returns.",
"crumbs": [
"2 [Part I — Start with what you already know]{.en}[Partie I — Commencer par ce que l'on connaît déjà]{.fr}[Teil I — Mit dem beginnen, was man schon kennt]{.de}"
]
},
{
"objectID": "01-part-i-calls.html#sec-step-1",
"href": "01-part-i-calls.html#sec-step-1",
"title": "2 Part I — Start with what you already know",
"section": "",
"text": "void main() {\n while (true) {\n var text = IO.readln();\n\n if (text == null)\n return;\n\n IO.println(rot13(text));\n }\n}\n\n\n\n\n\n\n\n\n\n\nFigure 2.1: The procedural version. The wiring is written into the code: main() names all three parts and fixes their order.",
"crumbs": [
"2 [Part I — Start with what you already know]{.en}[Partie I — Commencer par ce que l'on connaît déjà]{.fr}[Teil I — Mit dem beginnen, was man schon kennt]{.de}"
]
},
{
"objectID": "01-part-i-calls.html#sec-step-2",
"href": "01-part-i-calls.html#sec-step-2",
"title": "2 Part I — Start with what you already know",
"section": "2.2 Step 2 — Three egoistic capabilities",
"text": "2.2 Step 2 — Three egoistic capabilities\nAn 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(...).\nRemoving those calls immediately creates a problem, best put 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.",
"crumbs": [
"2 [Part I — Start with what you already know]{.en}[Partie I — Commencer par ce que l'on connaît déjà]{.fr}[Teil I — Mit dem beginnen, was man schon kennt]{.de}"
]
},
{
"objectID": "01-part-i-calls.html#sec-step-3",
"href": "01-part-i-calls.html#sec-step-3",
"title": "2 Part I — Start with what you already know",
"section": "2.3 Step 3 — Give every capability a mailbox",
"text": "2.3 Step 3 — Give every capability a mailbox\nThe smallest mechanism for the missing connections: a message and a named queue.\nrecord Message(String type, String value) {}\n\nMap<String, BlockingQueue<Message>> mailboxes = new ConcurrentHashMap<>();\n\nBlockingQueue<Message> mailbox(String name) {\n return mailboxes.computeIfAbsent(name, _ -> new LinkedBlockingQueue<>());\n}\nThese are mailboxes, not topics, and the distinction is worth insisting on: 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.",
"crumbs": [
"2 [Part I — Start with what you already know]{.en}[Partie I — Commencer par ce que l'on connaît déjà]{.fr}[Teil I — Mit dem beginnen, was man schon kennt]{.de}"
]
},
{
"objectID": "01-part-i-calls.html#sec-steps-4-6",
"href": "01-part-i-calls.html#sec-steps-4-6",
"title": "2 Part I — Start with what you already know",
"section": "2.4 Steps 4–6 — The three capabilities become egoistic",
"text": "2.4 Steps 4–6 — The three capabilities become egoistic\nEach capability now touches only its own mailbox names:\n\n\n\nCapability\nreads\nwrites\n\n\n\n\nConsoleIn\nthe keyboard\nconsoleIn.outbox\n\n\nROT13\nrot13.inbox\nrot13.outbox\n\n\nConsoleOut\nconsoleOut.inbox\nthe console\n\n\n\nNo capability contains the name of another, and that is exactly the result: three nicely isolated capabilities that do absolutely nothing together. Nothing moves a message from consoleIn.outbox to rot13.inbox, or from rot13.outbox to consoleOut.inbox.",
"crumbs": [
"2 [Part I — Start with what you already know]{.en}[Partie I — Commencer par ce que l'on connaît déjà]{.fr}[Teil I — Mit dem beginnen, was man schon kennt]{.de}"
]
},
{
"objectID": "01-part-i-calls.html#sec-step-7",
"href": "01-part-i-calls.html#sec-step-7",
"title": "2 Part I — Start with what you already know",
"section": "2.5 Step 7 — Enter the mediator",
"text": "2.5 Step 7 — Enter the mediator\nThe smallest possible glue: a loop that takes from one mailbox and puts into another, knowing nothing about what travels through it.\nvoid mediate(String from, String to) {\n while (true)\n mailbox(to).put(mailbox(from).take());\n}\nmain() 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.\nObserved: 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.\n\n\n\n\n\n\nFigure 2.2: The mediated version inside one JVM. In the web version, Play walks one message through all eight hops.",
"crumbs": [
"2 [Part I — Start with what you already know]{.en}[Partie I — Commencer par ce que l'on connaît déjà]{.fr}[Teil I — Mit dem beginnen, was man schon kennt]{.de}"
]
},
{
"objectID": "01-part-i-calls.html#sec-step-8",
"href": "01-part-i-calls.html#sec-step-8",
"title": "2 Part I — Start with what you already know",
"section": "2.6 Step 8 — Ask again: who knows whom?",
"text": "2.6 Step 8 — Ask again: who knows whom?\nDoes 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().\nThis is the first major result:\n\nDecoupling often does not make knowledge disappear. It moves knowledge to where it belongs.\n\nThe 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.",
"crumbs": [
"2 [Part I — Start with what you already know]{.en}[Partie I — Commencer par ce que l'on connaît déjà]{.fr}[Teil I — Mit dem beginnen, was man schon kennt]{.de}"
]
},
{
"objectID": "01-part-i-calls.html#sec-step-9",
"href": "01-part-i-calls.html#sec-step-9",
"title": "2 Part I — Start with what you already know",
"section": "2.7 Step 9 — Why virtual threads?",
"text": "2.7 Step 9 — Why virtual threads?\nFive 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.\nThey 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 evidence for the separation: the same architecture will run as separate processes in step 11, with no threads shared between the parts.",
"crumbs": [
"2 [Part I — Start with what you already know]{.en}[Partie I — Commencer par ce que l'on connaît déjà]{.fr}[Teil I — Mit dem beginnen, was man schon kennt]{.de}"
]
},
{
"objectID": "01-part-i-calls.html#sec-step-10",
"href": "01-part-i-calls.html#sec-step-10",
"title": "2 Part I — Start with what you already know",
"section": "2.8 Step 10 — Keep the services egoistic",
"text": "2.8 Step 10 — Keep the services egoistic\nThe obvious shortcut: the first mediator only copies messages unchanged, so why not delete it and let ROT13 take() from consoleIn.outbox directly?\nBecause 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.\n\n\n\n\nwith the mediator\nwith the shortcut\n\n\n\n\nwhat changes\none argument of the mediator\nrunRot13 itself\n\n\nwho is touched\nno capability\nROT13, whose job did not change\n\n\n\nThe price is worth stating plainly: this design may look indirect — even a little odd. There is another way to keep services egoistic without a mediator in every message’s path, and it comes later.",
"crumbs": [
"2 [Part I — Start with what you already know]{.en}[Partie I — Commencer par ce que l'on connaît déjà]{.fr}[Teil I — Mit dem beginnen, was man schon kennt]{.de}"
]
},
{
"objectID": "01-part-i-calls.html#sec-part-i-result",
"href": "01-part-i-calls.html#sec-part-i-result",
"title": "2 Part I — Start with what you already know",
"section": "2.9 What part I moved",
"text": "2.9 What part I moved\n\n\n\n\n\n\n\n\nstage\nwhere the topology lives\nwho could rewire it\n\n\n\n\nstep 1\ninside the capability code (IO.println(rot13(text)))\nwhoever edits that code\n\n\nsteps 7–8\nin main(), as pairs of mailbox names\nwhoever edits main()\n\n\n\nFunctionality: unchanged. Lines of code: more. Parts that know each other: none. That is the trade everything that follows keeps testing.",
"crumbs": [
"2 [Part I — Start with what you already know]{.en}[Partie I — Commencer par ce que l'on connaît déjà]{.fr}[Teil I — Mit dem beginnen, was man schon kennt]{.de}"
]
},
{
"objectID": "02-part-ii-processes.html",
"href": "02-part-ii-processes.html",
"title": "3 Part II — Cross the process boundary",
"section": "",
"text": "3.1 Step 11 — Separate the components\nSteps 11 to 18 take the architecture of part I and split it across five operating-system processes on one computer. The capabilities keep their mailbox names; only the transport underneath changes, from Java objects to files in directories. The first genuinely distributed problem shows up here, and it has nothing to do with ROT13.\nThree processes cannot share a BlockingQueue: every java command starts its own JVM with its own memory, so the mailboxes map would exist three times and each copy would see only its own messages. An external transport is needed.\nTCP would do, MQTT would do. The most primitive option is picked deliberately, the filesystem, for a one-line reason: because you can see it. Messages become files you can list with ls and read with cat while the system runs. Primitive here does not mean inferior; part VIII comes back to what the filesystem is genuinely good and bad at.",
"crumbs": [
"3 [Part II — Cross the process boundary]{.en}[Partie II — Franchir la frontière de processus]{.fr}[Teil II — Die Prozessgrenze überschreiten]{.de}"
]
},
{
"objectID": "02-part-ii-processes.html#sec-steps-12-13",
"href": "02-part-ii-processes.html#sec-steps-12-13",
"title": "3 Part II — Cross the process boundary",
"section": "3.2 Steps 12–13 — A directory becomes a mailbox",
"text": "3.2 Steps 12–13 — A directory becomes a mailbox\nThe mapping is one line long:\ndirectory = mailbox file = message\npublish = create file receive = watch directory\nmessageBoard/\n├── consoleIn/outbox/\n├── rot13/inbox/\n├── rot13/outbox/\n└── consoleOut/inbox/\nThe Message record gains an optional timestamp, and the file format stays two lines plus an optional third:\nTEXT\nHello World\nTIMESTAMP: 2026-09-22T10:42:12.123Z\nA message written by hand may leave the timestamp out. The TIMESTAMP: marker keeps a payload line that happens to look like a date from being mistaken for metadata; in this tiny format, a final line starting with TIMESTAMP: is reserved.\nJackson could be introduced here and deliberately is not. The point of a ridiculously simple format is that almost nothing hides the architecture — the whole message is readable in any text editor, which is what keeps the attention on who talks to whom.",
"crumbs": [
"3 [Part II — Cross the process boundary]{.en}[Partie II — Franchir la frontière de processus]{.fr}[Teil II — Die Prozessgrenze überschreiten]{.de}"
]
},
{
"objectID": "02-part-ii-processes.html#sec-step-14",
"href": "02-part-ii-processes.html#sec-step-14",
"title": "3 Part II — Cross the process boundary",
"section": "3.3 Step 14 — The first distributed-systems problem: publication",
"text": "3.3 Step 14 — The first distributed-systems problem: publication\nA reader watching a directory can discover a file before the writer has finished writing it. Hence a publication protocol:\n\ncreate a private temporary file;\nwrite the complete message;\nclose it;\natomically rename it to its final .msg name;\nconsumers react only to final files.\n\nFiles.writeString(temporary, content);\nFiles.move(temporary, published, StandardCopyOption.ATOMIC_MOVE);\nBoth halves are needed. The rename is atomic — a reader sees either no .msg file or the complete one — but it protects nothing if readers also pick up .tmp files. .tmp and .msg stay in the same directory so the move cannot cross filesystems, where atomicity would be lost.\n\nWriting and publishing are not the same operation.",
"crumbs": [
"3 [Part II — Cross the process boundary]{.en}[Partie II — Franchir la frontière de processus]{.fr}[Teil II — Die Prozessgrenze überschreiten]{.de}"
]
},
{
"objectID": "02-part-ii-processes.html#sec-step-15",
"href": "02-part-ii-processes.html#sec-step-15",
"title": "3 Part II — Cross the process boundary",
"section": "3.4 Step 15 — Observe a mailbox with WatchService",
"text": "3.4 Step 15 — Observe a mailbox with WatchService\nJava’s own filesystem observer supplies the consumer half: register a directory for ENTRY_CREATE, block in watcher.take(), and ignore every filename that does not end in .msg.\nThat also gives a low-tech injection tool. With ActuatorService running as the consumer:\nprintf 'TEXT\\nHello from a file' > messageBoard/consoleOut/inbox/manual.tmp\nmv messageBoard/consoleOut/inbox/manual.tmp messageBoard/consoleOut/inbox/manual.msg\nObserved: nothing happens when the .tmp file appears; the line is printed the moment the rename creates the .msg name. Both accepted formats work, with and without the trailing timestamp.\nThe architectural point reads producer → filesystem → consumer: the consumer could not tell a human typing mv from a real service. It knows its own inbox, not who writes into it. Egoism survived the process boundary.",
"crumbs": [
"3 [Part II — Cross the process boundary]{.en}[Partie II — Franchir la frontière de processus]{.fr}[Teil II — Die Prozessgrenze überschreiten]{.de}"
]
},
{
"objectID": "02-part-ii-processes.html#sec-steps-16-17",
"href": "02-part-ii-processes.html#sec-steps-16-17",
"title": "3 Part II — Cross the process boundary",
"section": "3.5 Steps 16–17 — Services and mediator become processes",
"text": "3.5 Steps 16–17 — Services and mediator become processes\nThe three capabilities become three programs, and the mediator a fourth kind of program:\n\n\n\n\n\n\n\n\n\nprogram\nplays\nreads\nwrites\n\n\n\n\nSensorService.java\nConsoleIn\nthe keyboard\nconsoleIn/outbox\n\n\nProcessorService.java\nROT13\nrot13/inbox\nrot13/outbox\n\n\nActuatorService.java\nConsoleOut\nconsoleOut/inbox\nthe console\n\n\nMediator.java <from> <to>\nthe glue\n<from>\n<to>\n\n\n\nThe mediator is generic: its route is not compiled in, it arrives as two startup arguments. But there is an asymmetry worth keeping in mind: the three capabilities receive their work as messages in a mailbox, while the mediator receives its route as startup configuration, and it has no name and no control mailbox of its own that anyone could write to.\nThe practical consequence: arguments are read once, so changing the route of a running mediator means stopping it and starting it again. A configuration file would be no different — it is still read at startup. This stays deliberately unfixed until the cost of the distributed mediators has been felt.",
"crumbs": [
"3 [Part II — Cross the process boundary]{.en}[Partie II — Franchir la frontière de processus]{.fr}[Teil II — Die Prozessgrenze überschreiten]{.de}"
]
},
{
"objectID": "02-part-ii-processes.html#sec-step-18",
"href": "02-part-ii-processes.html#sec-step-18",
"title": "3 Part II — Cross the process boundary",
"section": "3.6 Step 18 — Run the fully external local version",
"text": "3.6 Step 18 — Run the fully external local version\nFive terminals, five processes, one local filesystem between them:\njava SensorService.java # terminal 1\njava Mediator.java consoleIn/outbox rot13/inbox # terminal 2\njava ProcessorService.java # terminal 3\njava Mediator.java rot13/outbox consoleOut/inbox # terminal 4\njava ActuatorService.java # terminal 5\nObserved: Hello World typed in terminal 1 appeared as Uryyb Jbeyq in terminal 5. The three middle terminals showed nothing new — each mediator prints one “Mediating: …” line at startup, and ProcessorService prints nothing at all. Afterwards each of the four mailbox directories held one .msg file: the same line, copied along the chain.\nCount it: five processes for what step 1 did in one statement. This is not the moment to optimise: it is not meant to be comfortable yet.\n\n\n\n\n\n\nFigure 3.1: The five processes and the four mailbox directories. In the web version, Play follows one line of text from the keyboard to the console.",
"crumbs": [
"3 [Part II — Cross the process boundary]{.en}[Partie II — Franchir la frontière de processus]{.fr}[Teil II — Die Prozessgrenze überschreiten]{.de}"
]
},
{
"objectID": "02-part-ii-processes.html#sec-part-ii-result",
"href": "02-part-ii-processes.html#sec-part-ii-result",
"title": "3 Part II — Cross the process boundary",
"section": "3.7 What part II moved",
"text": "3.7 What part II moved\n\n\n\n\n\n\n\n\nstage\nwhere the topology lives\nwho could rewire it\n\n\n\n\nstep 1\ninside the capability code\nwhoever edits that code\n\n\nsteps 7–8\nin main(), as mailbox names\nwhoever edits main()\n\n\nstep 18\nin the two Mediator.java <from> <to> command lines\nwhoever starts the processes\n\n\n\nThe topology has now left the source code altogether: no .java file contains the route. It lives in what the operator typed, which means a person is currently the orchestrator. What the five-process version bought is real — the wiring can change without touching any program — and what it cost is equally real: five processes, four copies of every message, and a program that no longer stops when you press Ctrl+D.",
"crumbs": [
"3 [Part II — Cross the process boundary]{.en}[Partie II — Franchir la frontière de processus]{.fr}[Teil II — Die Prozessgrenze überschreiten]{.de}"
]
},
{
"objectID": "03-part-iii-distributed.html",
"href": "03-part-iii-distributed.html",
"title": "4 Part III — Make it actually distributed",
"section": "",
"text": "4.1 Syncthing replicates; it does not deliver\nFive processes on one computer still share one filesystem. Steps 19 to 27 put them on two machines, replicate the message board between them with Syncthing, measure what that costs, and then break a mediator on purpose. By the end, the mediators’ price is a number rather than an opinion.\nSyncthing keeps a directory replicated between machines. That is all it is asked to do here. It knows nothing about Intent, Status, Event, ROT13 or mediators, and it has no concept of a consumer: no subscriptions, no topics, no delivery guarantees, no notion that anybody is waiting.\nThe trigger is still ours. Each service runs its own WatchService on a local directory; Syncthing only makes files appear there. That is why none of the three services changed a single line when the system became distributed.\nTwo consequences follow, and both show up later as observations rather than warnings:",
"crumbs": [
"4 [Part III — Make it actually distributed]{.en}[Partie III — Le rendre réellement distribué]{.fr}[Teil III — Es wirklich verteilen]{.de}"
]
},
{
"objectID": "03-part-iii-distributed.html#sec-syncthing-not-a-broker",
"href": "03-part-iii-distributed.html#sec-syncthing-not-a-broker",
"title": "4 Part III — Make it actually distributed",
"section": "",
"text": "replication is asynchronous — the .tmp → .msg rename is atomic on each machine separately, and nothing promises ordering or atomicity between machines;\nthe filesystem is a serious transport with its own strengths: files can be large, replicas survive a reboot, and every message is readable with cat.",
"crumbs": [
"4 [Part III — Make it actually distributed]{.en}[Partie III — Le rendre réellement distribué]{.fr}[Teil III — Es wirklich verteilen]{.de}"
]
},
{
"objectID": "03-part-iii-distributed.html#sec-one-layer",
"href": "03-part-iii-distributed.html#sec-one-layer",
"title": "4 Part III — Make it actually distributed",
"section": "4.2 Test one layer at a time",
"text": "4.2 Test one layer at a time\nBefore any Java touched the replicated folder, the dullest possible test ran first: write hello.txt on one machine, confirm it appears on the other, delete it, confirm the deletion travels back. Both directions worked.\nThat order matters. When the distributed run later failed, the question “is it replication or is it my program?” had already been answered for the transport, and the search could start one layer up.",
"crumbs": [
"4 [Part III — Make it actually distributed]{.en}[Partie III — Le rendre réellement distribué]{.fr}[Teil III — Es wirklich verteilen]{.de}"
]
},
{
"objectID": "03-part-iii-distributed.html#sec-keystroke-cost",
"href": "03-part-iii-distributed.html#sec-keystroke-cost",
"title": "4 Part III — Make it actually distributed",
"section": "4.3 What one keystroke costs",
"text": "4.3 What one keystroke costs\nWith the sensor on one machine and the mediators, ROT13 and the actuator on the other, one typed line produced four .msg files, one per mailbox:\n\n\n\nmailbox\ncontent\ntimestamp inside\n\n\n\n\nconsoleIn/outbox\nHello World\n23:02:05.315\n\n\nrot13/inbox\nHello World\n23:02:05.315\n\n\nrot13/outbox\nUryyb Jbeyq\n23:02:13.471\n\n\nconsoleOut/inbox\nUryyb Jbeyq\n23:02:13.471\n\n\n\nThe repeated timestamps are the evidence that two of those four publications are pure copies: the mediators republish the message unchanged, timestamp included. They compute identity(x) = x, as separate distributed processes.\nThe timing, taken from the four files’ modification times on one machine so that no clock skew enters: the sensor’s file appears at 01:02:05.432, the other three at 01:02:13.460, .504 and .532 — 8.10 s later, and within 72 ms of each other. So the chain’s own work took milliseconds; the eight seconds are Syncthing’s propagation. The same chain, run entirely on one machine, completes in about 24 ms.",
"crumbs": [
"4 [Part III — Make it actually distributed]{.en}[Partie III — Le rendre réellement distribué]{.fr}[Teil III — Es wirklich verteilen]{.de}"
]
},
{
"objectID": "03-part-iii-distributed.html#sec-break-a-mediator",
"href": "03-part-iii-distributed.html#sec-break-a-mediator",
"title": "4 Part III — Make it actually distributed",
"section": "4.4 Break a mediator",
"text": "4.4 Break a mediator\nStop the first mediator and type two lines. ConsoleIn is alive, ROT13 is alive, ConsoleOut is alive, Syncthing is alive — and the business flow is dead. The two lines pile up in consoleIn/outbox; nothing moves past it. The mediators are part of the availability chain.\nThen restart the mediator. Nothing is delivered. FileMessageBoard.watch registers a directory for ENTRY_CREATE and blocks in watcher.take(); it never lists what is already there. The two files are still on disk, in both replicas — so no data was lost. What has no memory is the subscription.\nThat distinction is worth keeping: the messages survived, the delivery did not. A broker answers this with session state and retained messages; in our own code it would be one line — list the existing .msg files before entering the watch loop — which the material deliberately does not write yet.",
"crumbs": [
"4 [Part III — Make it actually distributed]{.en}[Partie III — Le rendre réellement distribué]{.fr}[Teil III — Es wirklich verteilen]{.de}"
]
},
{
"objectID": "03-part-iii-distributed.html#sec-configurable-mediator",
"href": "03-part-iii-distributed.html#sec-configurable-mediator",
"title": "4 Part III — Make it actually distributed",
"section": "4.5 The mediator becomes an ordinary service",
"text": "4.5 The mediator becomes an ordinary service\nBefore removing the mediators, one asymmetry gets removed: the services receive their work as messages, while the mediator received its route as shell arguments. So the mediator is given only a name, ConfigurableMediator mediator1, from which it derives one permanent control mailbox, mediators/mediator1/inbox, and the route arrives as a message:\nROUTE\nconsoleIn/outbox\nrot13/inbox\nfrom and to travel in one message on purpose: as two, the mediator would briefly hold a new source with the old destination and forward to the wrong place. A route is one fact, and one fact belongs in one message.\nA short-lived orchestrator publishes both routes and exits, so the topology is visible in one place and is not in the data path. Running it after the services, and typing a line before it, shows both halves at once: the early line is stranded, the later one flows.\nWhat improved: the mediator now has an identity, takes configuration through its own inbox, keeps a generic capability, and gets its topology from an orchestrator. What did not improve: the data path. It is still event → mediator → copied event, still a process in the availability chain, still copying every message without adding meaning. And this version accepts exactly one route: waitForRoute(...) returns, then the mediator enters watch(route.from(), …) and never reads its control inbox again. Live rewiring is not promised, because one blocking watch cannot serve a control inbox and a source at the same time — the reason a subscription helper appears later.",
"crumbs": [
"4 [Part III — Make it actually distributed]{.en}[Partie III — Le rendre réellement distribué]{.fr}[Teil III — Es wirklich verteilen]{.de}"
]
},
{
"objectID": "03-part-iii-distributed.html#sec-part-iii-result",
"href": "03-part-iii-distributed.html#sec-part-iii-result",
"title": "4 Part III — Make it actually distributed",
"section": "4.6 What part III moved",
"text": "4.6 What part III moved\n\n\n\n\n\n\n\n\nstage\nwhere the topology lives\nin the data path?\n\n\n\n\nstep 18\nthe operator’s command lines\nthe mediators are\n\n\nstep 27\nan orchestrator, published as Intent\nthe mediators still are\n\n\n\nThe question the part ends on is therefore sharp rather than rhetorical: why can’t the service interested in the data simply listen to it itself?",
"crumbs": [
"4 [Part III — Make it actually distributed]{.en}[Partie III — Le rendre réellement distribué]{.fr}[Teil III — Es wirklich verteilen]{.de}"
]
},
{
"objectID": "04-part-iv-rewind.html",
"href": "04-part-iv-rewind.html",
"title": "5 Part IV — Rewind",
"section": "",
"text": "5.1 The obvious shortcut, and its trap\nSteps 28 to 34 go back to one JVM on purpose. With no replication delay and no five-terminal setup, the only thing that can change is who knows whom — so the idea can be tried in seconds instead of in a distributed debugging session.\nIf the first mediator only copies messages, delete it and let ROT13 read the source itself:\nThe mediator is gone. But ask the recurring question: ROT13 now contains the name of ConsoleIn’s mailbox. The topology moved out of the mediator and into the service. As the material puts it: “We removed the mediator… and put topology back into the service. Oops.”",
"crumbs": [
"5 [Part IV — Rewind]{.en}[Partie IV — Rembobinage]{.fr}[Teil IV — Zurückspulen]{.de}"
]
},
{
"objectID": "04-part-iv-rewind.html#sec-the-trap",
"href": "04-part-iv-rewind.html#sec-the-trap",
"title": "5 Part IV — Rewind",
"section": "",
"text": "listen(\"consoleIn.outbox\");",
"crumbs": [
"5 [Part IV — Rewind]{.en}[Partie IV — Rembobinage]{.fr}[Teil IV — Zurückspulen]{.de}"
]
},
{
"objectID": "04-part-iv-rewind.html#sec-capability-vs-topology",
"href": "04-part-iv-rewind.html#sec-capability-vs-topology",
"title": "5 Part IV — Rewind",
"section": "5.2 Capability is not topology",
"text": "5.2 Capability is not topology\nROT13 may know two things: I can transform text, and I am capable of listening for compatible text messages. It may not know my input always comes from consoleIn.outbox — that is deployment topology.\nSo the name is not compiled in; it arrives at runtime:\nTOPIC consoleIn.outbox\nROT13 learns its wiring from data. Note who sends it: in DynamicQueueRot13.java it is main() that publishes both TOPIC messages — a configurator, outside the data path, in the role the orchestrator played before. It cannot be ConsoleIn: if ConsoleIn told ROT13 what to subscribe to, ConsoleIn would have to know ROT13 exists, and the topology would simply have moved into a different capability.",
"crumbs": [
"5 [Part IV — Rewind]{.en}[Partie IV — Rembobinage]{.fr}[Teil IV — Zurückspulen]{.de}"
]
},
{
"objectID": "04-part-iv-rewind.html#sec-dynamic-mechanics",
"href": "04-part-iv-rewind.html#sec-dynamic-mechanics",
"title": "5 Part IV — Rewind",
"section": "5.3 What changes in the code",
"text": "5.3 What changes in the code\nlisten(...) is nothing exotic: a virtual thread that repeatedly calls take() on one of the same queues. subscribe(...) starts one such thread per subscribed name. The consequence is visible in the mailboxes:\n\nROT13 takes straight from consoleIn.outbox — the name it was told;\nrot13.inbox is no longer a payload mailbox. It carries control messages, and ROT13’s loop reads it to decide whether a message is a TOPIC to act on.\n\nNothing writes into rot13.inbox to move data anymore. The mailbox did not disappear; it changed job, from carrying payload to carrying Intent.\nOne observation from running it: after Ctrl+D, output stops but the program stays up. Nothing was interrupted — runConsoleIn returns on end of input, so the producer is gone, while both subscriber threads sit blocked in take() on sources that will never publish again. The JVM stays alive because main ends with Thread.currentThread().join(). “The flow stopped” always has to be traced to which participant stopped.",
"crumbs": [
"5 [Part IV — Rewind]{.en}[Partie IV — Rembobinage]{.fr}[Teil IV — Zurückspulen]{.de}"
]
},
{
"objectID": "04-part-iv-rewind.html#sec-route-topic-intent",
"href": "04-part-iv-rewind.html#sec-route-topic-intent",
"title": "5 Part IV — Rewind",
"section": "5.4 ROUTE and TOPIC are Intent",
"text": "5.4 ROUTE and TOPIC are Intent\nApply two tests to TOPIC consoleIn.outbox. Does it describe something that happened? No. Something currently true? No. It says please begin listening here — desired behaviour, which is Intent. The mediator’s ROUTE is the same kind of message: please forward from here to there.\nOne trap worth naming, because it is tempting in a defence: publishing an Intent is of course something that happened. Classification follows what the message says, not the fact that it exists.\nAnd one condition, which returns later: the dynamic version is not automatically superior. It makes sense only if the consumer actually understands the producer’s message contract.\nSTATIC MEDIATED DYNAMIC DIRECT\nProducer → Mediator → Consumer Intent → (Producer ──► Consumer)",
"crumbs": [
"5 [Part IV — Rewind]{.en}[Partie IV — Rembobinage]{.fr}[Teil IV — Zurückspulen]{.de}"
]
},
{
"objectID": "glossary.html",
"href": "glossary.html",
"title": "Glossary",
"section": "",
"text": "Every term below is defined where it is first used, and linked from every later mention. The arrow on an entry leads back to that page.",
"crumbs": [
"Appendices",
"[Glossary]{.en}[Glossaire]{.fr}[Glossar]{.de}"
]
}
]