Zum Inhalt springen

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.

  • eine HTTP-Anfrage und -Antwort lesen: Methode, Pfad, Statuscode, Rumpf
  • ein eigenes kleines Protokoll auf HTTP festlegen
  • einen Server mit com.sun.net.httpserver.HttpServer verstehen und starten
  • Exceptions in Statuscodes übersetzen

Demo-Code: zahlenraten-4

⤓ zahlenraten-4.zip herunterladen

Der 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 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

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.

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:

SpielNichtGefunden.java
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.

TextServer.java
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 "&lt;id&gt; 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 /spiele beginnt, an eine Methode: bearbeite.
  • Jede Anfrage läuft in einem eigenen virtuellen Thread – so können viele gleichzeitig spielen (siehe Parallelität).
  • bearbeite schaut 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: SpielNichtGefunden und NumberFormatException sind beide Unterklassen von IllegalArgumentException und müssen davor stehen.
  • Der letzte catch (Exception e) ist wichtig: Der HttpServer verschluckt Exceptions aus einem Handler – ohne ihn bekäme der Client gar keine Antwort, und auf der Konsole stünde nichts.
  • ServerStart hat nur eine Zeile: Server mit einem LokalerSpielleiter erzeugen und starten. Der Server kennt nur das Interface.

Starte ServerStart in IntelliJ. Der Server läuft, bis du ihn mit dem roten Quadrat stoppst. Jede Anfrage erscheint mit Statuscode in der Konsole.

  1. 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/spiele
    curl -X POST -d 50 localhost:8080/spiele/<id>/versuche

    Setze für <id> die ID aus der ersten Antwort ein. Probiere auch curl -v: Finde Methode, Pfad, Statuscode und Rumpf.

  2. Fehler provozieren: Bringe den Server dazu, jeden Statuscode aus der Tabelle oben zu liefern – außer 500. Welche Anfrage führt zu 404, obwohl es die ID gibt? Mit -w '%{http_code}\n' zeigt curl den Code an.

  3. Ein Argument für den Server: Erweitere ServerStart: Mit dem Argument gemein (in IntelliJ unter Run → Edit Configurations → Program arguments) startet der Server mit dem GemeinerSpielleiter. Was musst du am TextServer ändern?

  4. Für Schnelle – ein Test über das Netz: Schreibe TextServerTest. Er startet den Server auf Port 0 – das heißt: irgendein freier Port, den getPort() verrät – und spricht mit ihm über den HttpClient aus dem JDK (siehe Ströme). Prüfe: Halbieren findet die Zahl in höchstens sieben Versuchen, und abc, 0, eine unbekannte ID und ein unbekannter Pfad liefern 400, 400, 404 und 404.

Lösung

Eine Runde im Terminal – mit allen Fehlern:

Terminal-Fenster
$ curl -X POST localhost:8080/spiele
a13d3e7d-14eb-49e3-ab06-339ed0a081d1 1 100
$ curl -X POST -d 50 localhost:8080/spiele/a13d3e7d-14eb-49e3-ab06-339ed0a081d1/versuche
ZU_GROSS 1
$ curl -X POST -d 25 localhost:8080/spiele/a13d3e7d-14eb-49e3-ab06-339ed0a081d1/versuche
ZU_KLEIN 2
$ curl -w '%{http_code}\n' -X POST -d abc localhost:8080/spiele/a13d3e7d-14eb-49e3-ab06-339ed0a081d1/versuche
Keine Zahl
400
$ curl -w '%{http_code}\n' -X POST -d 0 localhost:8080/spiele/a13d3e7d-14eb-49e3-ab06-339ed0a081d1/versuche
Nur Zahlen von 1 bis 100: 0
400
$ curl -w '%{http_code}\n' -X POST -d 5 localhost:8080/spiele/xyz/versuche
Kein Spiel mit der ID xyz
404
$ curl -w '%{http_code}\n' localhost:8080/spiele
Unbekannt: GET /spiele
404

Die 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.

ServerStart.java
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.

TextServerTest.java
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());
}
}