Zahlenraten 4: Ein Protokoll
Bis jetzt laufen Konsole und Spielleiter im selben Programm. Jetzt soll der Spielleiter woanders sitzen – auf einem Server, im Netz. Dann muss die Frage „Wie fragt man ihn?“ eine Antwort bekommen, die beide Seiten verstehen: ein Protokoll.
Was du am Ende kannst
Abschnitt betitelt „Was du am Ende kannst“- eine HTTP-Anfrage und -Antwort lesen: Methode, Pfad, Statuscode, Rumpf
- ein eigenes kleines Protokoll auf HTTP festlegen
- einen Server mit
com.sun.net.httpserver.HttpSerververstehen und starten - Exceptions in Statuscodes übersetzen
Demo-Code: zahlenraten-4
⤓ zahlenraten-4.zip herunterladenDer fertige Stand aus der Vorführung – zum Nachlesen, Ausprobieren und Weiterbauen.
Entpacke die ZIP-Datei nach C:\dev\intellij. In IntelliJ: File → Open… → den Ordner zahlenraten-4 wählen → OK → Trust Project. IntelliJ erkennt die pom.xml und lädt die Bibliotheken selbst herunter – das dauert beim ersten Mal einen Moment.
Enthält: pom.xml, LokalerSpielleiterTest.java, SpielTest.java, Antwort.java, GemeinerSpielleiter.java, Hinweis.java, Konsole.java, LokalerSpielleiter.java, ServerStart.java, Spiel.java, SpielNichtGefunden.java, Spielleiter.java, Spielstart.java, Start.java, TextServer.java
Der Starter enthält die Lösung von Teil 3 – mit GemeinerSpielleiter und
LokalerSpielleiterTest – und einen fertigen Server: TextServer und
ServerStart. In diesem Teil wird gelesen, gestartet und ausprobiert.
HTTP in fünf Minuten
Abschnitt betitelt „HTTP in fünf Minuten“HTTP ist ein Protokoll aus Text: Der Client schickt eine Anfrage, der Server
schickt eine Antwort, dann ist das Gespräch vorbei. So sieht ein neues Spiel aus,
mitgeschnitten mit curl -v:
> POST /spiele HTTP/1.1 ← Methode, Pfad, Version> Host: localhost:8080 ← Kopfzeilen (Header)> User-Agent: curl/8.7.1> Accept: */*> ← leere Zeile: danach käme der Rumpf< HTTP/1.1 201 Created ← Statuscode< Date: Fri, 23 Oct 2026 12:27:32 GMT< Content-type: text/plain; charset=utf-8< Content-length: 43<a13d3e7d-14eb-49e3-ab06-339ed0a081d1 1 100 ← der Rumpf (Body)| Teil | wofür | bei uns |
|---|---|---|
| Methode | was der Client will | GET = lesen, POST = etwas Neues anlegen oder auslösen |
| Pfad | worum es geht | /spiele, /spiele/{id}/versuche |
| Statuscode | wie es ausgegangen ist | 2xx gut, 4xx der Client hat sich vertan, 5xx der Server |
| Rumpf | die eigentlichen Daten | eine Zahl, eine Antwort |
Die Statuscodes, die wir brauchen:
| Code | Name | wann |
|---|---|---|
200 |
OK | der Versuch wurde beurteilt |
201 |
Created | ein Spiel wurde angelegt |
400 |
Bad Request | keine Zahl oder eine außerhalb von 1 bis 100 |
404 |
Not Found | unbekannte Spiel-ID oder unbekannter Pfad |
409 |
Conflict | das Spiel ist schon vorbei |
500 |
Internal Server Error | ein Fehler im Server selbst |
Unser Protokoll
Abschnitt betitelt „Unser Protokoll“Jeder Aufruf aus dem Interface Spielleiter wird zu einer Anfrage:
| Java | Anfrage | Antwort |
|---|---|---|
neuesSpiel() |
POST /spiele |
201, Rumpf <id> 1 100 |
rate(id, 42) |
POST /spiele/<id>/versuche, Rumpf 42 |
200, Rumpf ZU_KLEIN 3 |
Die ID steht im Pfad – sie sagt, welches Spiel gemeint ist. Die Zahl steht im Rumpf – sie ist das, was der Client mitteilt. Und jede Exception aus dem Vertrag wird zu einem Statuscode.
Eine kleine Änderung am Vertrag
Abschnitt betitelt „Eine kleine Änderung am Vertrag“Bisher wirft der Spielleiter bei einer unbekannten ID und bei einer ungültigen
Zahl dieselbe IllegalArgumentException. Der Server will das aber
unterscheiden: 404 gegen 400. Deshalb gibt es eine neue Exception:
package de.drv.zahlenraten;
/** * Es gibt kein Spiel mit dieser ID. Eine Unterklasse von {@link IllegalArgumentException} – so * bleibt der Vertrag des {@link Spielleiter}s gültig, aber ein Server kann diesen Fall von einer * ungültigen Zahl unterscheiden. */public class SpielNichtGefunden extends IllegalArgumentException {
public SpielNichtGefunden(String spielId) { super("Kein Spiel mit der ID " + spielId); }
}LokalerSpielleiter und GemeinerSpielleiter werfen jetzt sie. Weil sie eine
Unterklasse von IllegalArgumentException ist, gilt der alte Vertrag
weiter: Wer IllegalArgumentException fängt, fängt sie mit. Alle Tests aus Teil 2
und 3 bleiben grün.
Der Server
Abschnitt betitelt „Der Server“package de.drv.zahlenraten;
import com.sun.net.httpserver.HttpExchange;import com.sun.net.httpserver.HttpServer;
import java.io.IOException;import java.io.InputStream;import java.io.OutputStream;import java.net.InetSocketAddress;import java.nio.charset.StandardCharsets;import java.util.concurrent.Executors;import java.util.regex.Matcher;import java.util.regex.Pattern;
/** * Ein Server für Zahlenraten mit einem einfachen Text-Protokoll: * * <pre> * POST /spiele → 201 "<id> 1 100" * POST /spiele/{id}/versuche "42" → 200 "ZU_KLEIN 3" * </pre> * * Er kennt nur das Interface {@link Spielleiter} – wer die Zahl wirklich kennt, wird ihm beim * Start übergeben. */public class TextServer {
private static final Pattern VERSUCHE = Pattern.compile("/spiele/([^/]+)/versuche");
private final Spielleiter spielleiter; private final int port; private HttpServer server;
/** @param port 0 heißt: irgendein freier Port – praktisch für Tests */ public TextServer(Spielleiter spielleiter, int port) { this.spielleiter = spielleiter; this.port = port; }
public void starte() throws IOException { server = HttpServer.create(new InetSocketAddress(port), 0); server.createContext("/spiele", this::bearbeite); server.setExecutor(Executors.newVirtualThreadPerTaskExecutor()); server.start(); System.out.println("Zahlenraten-Server auf http://localhost:" + getPort()); }
public void stoppe() { server.stop(0); }
public int getPort() { return server.getAddress().getPort(); }
/** Jede Anfrage kommt hier an. Das try sorgt dafür, dass jeder Fehler eine Antwort bekommt. */ private void bearbeite(HttpExchange anfrage) { String methode = anfrage.getRequestMethod(); String pfad = anfrage.getRequestURI().getPath(); int status; try { Matcher versuche = VERSUCHE.matcher(pfad); if (methode.equals("POST") && pfad.equals("/spiele")) { status = neuesSpiel(anfrage); } else if (methode.equals("POST") && versuche.matches()) { status = rate(anfrage, versuche.group(1)); } else { status = antworte(anfrage, 404, "Unbekannt: " + methode + " " + pfad); } } catch (SpielNichtGefunden e) { // Unterklasse – muss zuerst kommen status = fehler(anfrage, 404, e.getMessage()); } catch (NumberFormatException e) { // ebenfalls eine Unterklasse status = fehler(anfrage, 400, "Keine Zahl"); } catch (IllegalArgumentException e) { status = fehler(anfrage, 400, e.getMessage()); } catch (IllegalStateException e) { status = fehler(anfrage, 409, e.getMessage()); } catch (Exception e) { e.printStackTrace(); // sonst verschluckt der HttpServer die Exception status = fehler(anfrage, 500, "Interner Fehler"); } System.out.printf("%-4s %-55s %d%n", methode, pfad, status); }
/** POST /spiele */ private int neuesSpiel(HttpExchange anfrage) throws IOException { Spielstart start = spielleiter.neuesSpiel(); return antworte(anfrage, 201, start.id() + " " + start.von() + " " + start.bis()); }
/** POST /spiele/{id}/versuche mit einer Zahl als Rumpf */ private int rate(HttpExchange anfrage, String spielId) throws IOException { int zahl = Integer.parseInt(lies(anfrage).trim()); Antwort antwort = spielleiter.rate(spielId, zahl); return antworte(anfrage, 200, antwort.hinweis() + " " + antwort.versuche()); }
private static String lies(HttpExchange anfrage) throws IOException { try (InputStream rumpf = anfrage.getRequestBody()) { return new String(rumpf.readAllBytes(), StandardCharsets.UTF_8); } }
private static int antworte(HttpExchange anfrage, int status, String text) throws IOException { byte[] bytes = (text + "\n").getBytes(StandardCharsets.UTF_8); anfrage.getResponseHeaders().set("Content-Type", "text/plain; charset=utf-8"); anfrage.sendResponseHeaders(status, bytes.length); try (OutputStream aus = anfrage.getResponseBody()) { aus.write(bytes); } return status; }
private static int fehler(HttpExchange anfrage, int status, String meldung) { try { return antworte(anfrage, status, meldung); } catch (IOException e) { anfrage.close(); return status; } }
}HttpServer.createöffnet den Port.createContext("/spiele", …)leitet jede Anfrage, deren Pfad mit/spielebeginnt, an eine Methode:bearbeite.- Jede Anfrage läuft in einem eigenen virtuellen Thread – so können viele gleichzeitig spielen (siehe Parallelität).
bearbeiteschaut auf Methode und Pfad und verteilt weiter. Für den Pfad mit der ID hilft ein regulärer Ausdruck:group(1)ist das Stück zwischen/spiele/und/versuche.- Die
catch-Blöcke übersetzen Exceptions in Statuscodes. Die Reihenfolge zählt:SpielNichtGefundenundNumberFormatExceptionsind beide Unterklassen vonIllegalArgumentExceptionund müssen davor stehen. - Der letzte
catch (Exception e)ist wichtig: DerHttpSerververschluckt Exceptions aus einem Handler – ohne ihn bekäme der Client gar keine Antwort, und auf der Konsole stünde nichts. ServerStarthat nur eine Zeile: Server mit einemLokalerSpielleitererzeugen und starten. Der Server kennt nur das Interface.
Übung: Mit dem Server sprechen
Abschnitt betitelt „Übung: Mit dem Server sprechen“Starte ServerStart in IntelliJ. Der Server läuft, bis du ihn mit dem roten
Quadrat stoppst. Jede Anfrage erscheint mit Statuscode in der Konsole.
-
Spielen mit curl: Öffne ein Terminal (in IntelliJ unten links) und spiele eine ganze Runde – nur mit
curl:Terminal-Fenster curl -X POST localhost:8080/spielecurl -X POST -d 50 localhost:8080/spiele/<id>/versucheSetze für
<id>die ID aus der ersten Antwort ein. Probiere auchcurl -v: Finde Methode, Pfad, Statuscode und Rumpf. -
Fehler provozieren: Bringe den Server dazu, jeden Statuscode aus der Tabelle oben zu liefern – außer
500. Welche Anfrage führt zu404, obwohl es die ID gibt? Mit-w '%{http_code}\n'zeigt curl den Code an. -
Ein Argument für den Server: Erweitere
ServerStart: Mit dem Argumentgemein(in IntelliJ unter Run → Edit Configurations → Program arguments) startet der Server mit demGemeinerSpielleiter. Was musst du amTextServerändern? -
Für Schnelle – ein Test über das Netz: Schreibe
TextServerTest. Er startet den Server auf Port0– das heißt: irgendein freier Port, dengetPort()verrät – und spricht mit ihm über denHttpClientaus dem JDK (siehe Ströme). Prüfe: Halbieren findet die Zahl in höchstens sieben Versuchen, undabc,0, eine unbekannte ID und ein unbekannter Pfad liefern400,400,404und404.
Lösung
Eine Runde im Terminal – mit allen Fehlern:
$ curl -X POST localhost:8080/spielea13d3e7d-14eb-49e3-ab06-339ed0a081d1 1 100$ curl -X POST -d 50 localhost:8080/spiele/a13d3e7d-14eb-49e3-ab06-339ed0a081d1/versucheZU_GROSS 1$ curl -X POST -d 25 localhost:8080/spiele/a13d3e7d-14eb-49e3-ab06-339ed0a081d1/versucheZU_KLEIN 2$ curl -w '%{http_code}\n' -X POST -d abc localhost:8080/spiele/a13d3e7d-14eb-49e3-ab06-339ed0a081d1/versucheKeine Zahl400$ curl -w '%{http_code}\n' -X POST -d 0 localhost:8080/spiele/a13d3e7d-14eb-49e3-ab06-339ed0a081d1/versucheNur Zahlen von 1 bis 100: 0400$ curl -w '%{http_code}\n' -X POST -d 5 localhost:8080/spiele/xyz/versucheKein Spiel mit der ID xyz404$ curl -w '%{http_code}\n' localhost:8080/spieleUnbekannt: GET /spiele404Die letzte Anfrage ist ein GET – den Pfad gibt es, die Methode nicht. 409
kommt, wenn man nach RICHTIG weiterrät.
Am TextServer ändert sich für den gemeinen Spielleiter nichts. Er bekommt
einen Spielleiter – welchen, entscheidet nur ServerStart.
package de.drv.zahlenraten;
import java.io.IOException;
/** Startet den Server auf Port 8080 – mit dem Argument {@code gemein} gegen den Schummler. */public class ServerStart {
public static void main(String[] args) throws IOException { Spielleiter spielleiter = args.length > 0 && args[0].equals("gemein") ? new GemeinerSpielleiter() : new LokalerSpielleiter(); new TextServer(spielleiter, 8080).starte(); }
}Lösung
Der Test macht dasselbe wie halbiere im LokalerSpielleiterTest, nur dass jeder
Versuch eine HTTP-Anfrage ist und die Antwort erst zerlegt werden muss. In Teil 6
wird daraus eine Klasse, die genau das für jeden erledigt.
package de.drv.zahlenraten;
import static org.junit.jupiter.api.Assertions.assertEquals;import static org.junit.jupiter.api.Assertions.assertTrue;
import java.io.IOException;import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;
import org.junit.jupiter.api.AfterEach;import org.junit.jupiter.api.BeforeEach;import org.junit.jupiter.api.DisplayName;import org.junit.jupiter.api.Test;
/** Ein echter Server auf einem freien Port – und HTTP-Anfragen dagegen. */class TextServerTest {
private TextServer server; private final HttpClient client = HttpClient.newHttpClient();
@BeforeEach void starte() throws IOException { server = new TextServer(new LokalerSpielleiter(), 0); server.starte(); }
@AfterEach void stoppe() { server.stoppe(); }
private HttpResponse<String> post(String pfad, String rumpf) throws Exception { HttpRequest anfrage = HttpRequest.newBuilder(URI.create("http://localhost:" + server.getPort() + pfad)) .POST(HttpRequest.BodyPublishers.ofString(rumpf)) .build(); return client.send(anfrage, HttpResponse.BodyHandlers.ofString()); }
@Test @DisplayName("Ein Spiel über HTTP: anlegen, durch Halbieren raten – höchstens sieben Versuche") void ganzesSpiel() throws Exception { HttpResponse<String> angelegt = post("/spiele", ""); assertEquals(201, angelegt.statusCode()); String[] start = angelegt.body().trim().split(" "); // "<id> 1 100" assertEquals("1", start[1]); assertEquals("100", start[2]);
int von = 1; int bis = 100; while (true) { int mitte = (von + bis) / 2; HttpResponse<String> antwort = post("/spiele/" + start[0] + "/versuche", String.valueOf(mitte)); assertEquals(200, antwort.statusCode()); String[] teile = antwort.body().trim().split(" "); // "ZU_KLEIN 3" if (teile[0].equals("RICHTIG")) { assertTrue(Integer.parseInt(teile[1]) <= 7); break; } if (teile[0].equals("ZU_KLEIN")) { von = mitte + 1; } else { bis = mitte - 1; } } }
@Test @DisplayName("Fehler werden zu Statuscodes: 400, 404, 409") void fehler() throws Exception { String id = post("/spiele", "").body().trim().split(" ")[0]; assertEquals(400, post("/spiele/" + id + "/versuche", "abc").statusCode()); assertEquals(400, post("/spiele/" + id + "/versuche", "101").statusCode()); assertEquals(404, post("/spiele/gibt-es-nicht/versuche", "50").statusCode()); assertEquals(404, post("/gibt-es-nicht", "").statusCode()); }
}