Zahlenraten 5: JSON
Unser Text-Protokoll funktioniert – aber nur, weil wir es uns ausgedacht haben.
Wer ZU_KLEIN 3 liest, muss wissen, dass das zweite Wort die Zahl der Versuche
ist. Kommt ein drittes Feld dazu, muss jeder Client neu zerlegen. Deshalb nimmt
man fast immer ein Standardformat: JSON.
Was du am Ende kannst
Abschnitt betitelt „Was du am Ende kannst“- JSON lesen und schreiben – von Hand und mit Jackson
- eine Bibliothek über Maven einbinden
- Records in JSON verwandeln und zurück
- Fehler als JSON melden
Demo-Code: zahlenraten-5
⤓ zahlenraten-5.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-5 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, Fehler.java, GemeinerSpielleiter.java, Hinweis.java, JsonServer.java, Konsole.java, LokalerSpielleiter.java, ServerStart.java, Spiel.java, SpielNichtGefunden.java, Spielleiter.java, Spielstart.java, Start.java, Versuch.java
Der Starter enthält die Lösung von Teil 4 – nur dass der TextServer einem
JsonServer gewichen ist. Der legt schon Spiele an. Raten kann er noch nicht.
JSON (JavaScript Object Notation) ist Text mit wenigen Regeln:
{ "id": "0ce68407-54e7-4c79-806a-3e6cc0708207", "von": 1, "bis": 100}| JSON | Beispiel | in Java |
|---|---|---|
| Objekt | {"zahl": 42} |
ein Record (oder eine Map) |
| Zeichenkette | "ZU_KLEIN" |
String – oder ein Enum |
| Zahl | 42, 3.5 |
int, double, … |
| Wahrheitswert | true, false |
boolean |
| Liste | [1, 2, 3] |
List oder Array |
| nichts | null |
null |
Namen stehen immer in doppelten Anführungszeichen. Die Reihenfolge der Felder in einem Objekt spielt keine Rolle.
Das Protokoll in JSON
Abschnitt betitelt „Das Protokoll in JSON“| Anfrage | Antwort |
|---|---|
POST /spiele |
201, {"id":"…","von":1,"bis":100} |
POST /spiele/<id>/versuche mit {"zahl":42} |
200, {"hinweis":"ZU_KLEIN","versuche":3} |
| ein Fehler | 400, 404 oder 409 mit {"fehler":"…"} |
Pfade und Statuscodes bleiben, wie sie waren. Nur die Rümpfe sind jetzt JSON. Für jede Art von Rumpf gibt es einen Record – zwei kennen wir schon, zwei sind neu:
| JSON | Record |
|---|---|
{"id":…,"von":…,"bis":…} |
Spielstart |
{"hinweis":…,"versuche":…} |
Antwort |
{"zahl":…} |
Versuch – neu |
{"fehler":…} |
Fehler – neu |
package de.drv.zahlenraten;
/** Der Rumpf eines Versuchs im JSON-Protokoll: {@code {"zahl": 42}} */public record Versuch(int zahl) {}package de.drv.zahlenraten;
/** Der Rumpf jeder Fehlerantwort im JSON-Protokoll: {@code {"fehler": "…"}} */public record Fehler(String fehler) {}Jackson
Abschnitt betitelt „Jackson“Das JDK kann JSON nicht selbst lesen. Die bekannteste Bibliothek dafür ist
Jackson. In Maven bindet man sie mit einer
Abhängigkeit in der pom.xml ein:
<dependency> <groupId>tools.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>3.2.4</version></dependency>Nach dem Ändern der pom.xml in IntelliJ das kleine Maven-Symbol oben rechts im
Editor klicken (Load Maven Changes) – dann lädt Maven Jackson herunter.
Zum Benutzen braucht man ein Objekt – den JsonMapper – und zwei Methoden:
JsonMapper json = JsonMapper.builder().build();
String text = json.writeValueAsString(new Antwort(Hinweis.ZU_KLEIN, 3));// {"hinweis":"ZU_KLEIN","versuche":3}
Versuch versuch = json.readValue("{\"zahl\":42}", Versuch.class);// Versuch[zahl=42]Jackson erkennt die Komponenten eines Records an ihren Namen. Ein Enum wird zu seinem Namen als Zeichenkette – und wieder zurück.
Der JSON-Server
Abschnitt betitelt „Der JSON-Server“package de.drv.zahlenraten;
import com.sun.net.httpserver.HttpExchange;import com.sun.net.httpserver.HttpServer;
import tools.jackson.core.JacksonException;import tools.jackson.databind.json.JsonMapper;
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;
/** * Der Zahlenraten-Server mit JSON statt Text: * * <pre> * POST /spiele → 201 {"id":"…","von":1,"bis":100} * POST /spiele/{id}/versuche {"zahl":42} → 200 {"hinweis":"ZU_KLEIN","versuche":3} * Fehler → 4xx {"fehler":"…"} * </pre> * * <p>Übung: {@code rate} antwortet noch mit 501, und Fehler kommen noch als Text. */public class JsonServer {
private static final Pattern VERSUCHE = Pattern.compile("/spiele/([^/]+)/versuche");
private final Spielleiter spielleiter; private final int port; private final JsonMapper json = JsonMapper.builder().build(); private HttpServer server;
public JsonServer(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 (JSON) auf http://localhost:" + getPort()); }
public void stoppe() { server.stop(0); }
public int getPort() { return server.getAddress().getPort(); }
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 = fehler(anfrage, 404, "Unbekannt: " + methode + " " + pfad); } } catch (SpielNichtGefunden e) { status = fehler(anfrage, 404, e.getMessage()); } catch (JacksonException e) { status = fehler(anfrage, 400, "Kein gültiges JSON"); } catch (IllegalArgumentException e) { status = fehler(anfrage, 400, e.getMessage()); } catch (IllegalStateException e) { status = fehler(anfrage, 409, e.getMessage()); } catch (Exception e) { e.printStackTrace(); status = fehler(anfrage, 500, "Interner Fehler"); } System.out.printf("%-4s %-55s %d%n", methode, pfad, status); }
/** POST /spiele – der Spielstart ist ein Record, Jackson macht JSON daraus. */ private int neuesSpiel(HttpExchange anfrage) throws IOException { return antworte(anfrage, 201, spielleiter.neuesSpiel()); }
/** POST /spiele/{id}/versuche mit {"zahl": 42} */ private int rate(HttpExchange anfrage, String spielId) throws IOException { return antworteText(anfrage, 501, "Übung: noch nicht umgesetzt"); }
// ----- Werkzeuge ---------------------------------------------------------------------
/** Liest den Rumpf als JSON in einen Record vom Typ {@code typ}. */ <T> T lies(HttpExchange anfrage, Class<T> typ) throws IOException { try (InputStream rumpf = anfrage.getRequestBody()) { return json.readValue(rumpf, typ); } }
/** Schreibt ein Objekt – meist einen Record – als JSON. */ int antworte(HttpExchange anfrage, int status, Object nachricht) throws IOException { byte[] bytes = json.writeValueAsBytes(nachricht); anfrage.getResponseHeaders().set("Content-Type", "application/json; charset=utf-8"); anfrage.sendResponseHeaders(status, bytes.length); try (OutputStream aus = anfrage.getResponseBody()) { aus.write(bytes); } return status; }
/** Schreibt einfachen Text – wie im Text-Protokoll. */ int antworteText(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; }
/** Eine Fehlerantwort – Übung: als {"fehler": "…"} statt als Text. */ private int fehler(HttpExchange anfrage, int status, String meldung) { try { return antworteText(anfrage, status, meldung); } catch (IOException e) { anfrage.close(); return status; } }
}Der Aufbau ist derselbe wie beim TextServer. Neu sind:
- Zwei Werkzeuge:
lies(anfrage, Versuch.class)macht aus dem Rumpf einen Record,antworte(anfrage, 201, start)aus einem Record den Rumpf. neuesSpielist dadurch nur noch eine Zeile.- Ein neues
catch: Ist der Rumpf kein gültiges JSON – oder steht beizahlein Text –, wirft Jackson eineJacksonException. Das ist ein Fehler des Clients:400. - Eine
NumberFormatExceptiongibt es nicht mehr. Die Zahl liest jetzt Jackson.
So sieht es im Moment aus:
$ curl -X POST localhost:8080/spiele{"id":"0ce68407-54e7-4c79-806a-3e6cc0708207","von":1,"bis":100}$ curl -X POST -d '{"zahl":50}' localhost:8080/spiele/0ce68407-54e7-4c79-806a-3e6cc0708207/versucheÜbung: noch nicht umgesetzt501 heißt Not Implemented – genau das stimmt.
Übung: Raten in JSON
Abschnitt betitelt „Übung: Raten in JSON“Arbeite im Demo-Projekt zahlenraten-5.
-
Raten: Setze
rateum: den Rumpf alsVersuchlesen, den Spielleiter fragen, dieAntwortals JSON zurückschicken. Es sind zwei Zeilen. -
Fehler als JSON: Im Moment meldet
fehlernoch Text. Ändere es so, dass jeder Fehler als{"fehler":"…"}kommt. Probiere danach mit curl: einen Rumpf, der kein JSON ist, eine Zahl außerhalb des Bereichs,{"zahl":"viel"}und eine unbekannte ID. -
Was übersieht Jackson? Schicke
{"zahl":50,"name":"Anna"}und{}. Was passiert jeweils – und warum? -
Für Schnelle – ein Test: Mach aus dem
TextServerTestaus Teil 4 einenJsonServerTest. DenJsonMapperkannst du im Test genauso benutzen wie im Server.
Lösung
$ curl -X POST -d '{"zahl":50}' localhost:8080/spiele/0ce68407-…/versuche{"hinweis":"ZU_KLEIN","versuche":1}$ curl -w ' %{http_code}\n' -X POST -d 'zweiundvierzig' localhost:8080/spiele/0ce68407-…/versuche{"fehler":"Kein gültiges JSON"} 400$ curl -w ' %{http_code}\n' -X POST -d '{"zahl":500}' localhost:8080/spiele/0ce68407-…/versuche{"fehler":"Nur Zahlen von 1 bis 100: 500"} 400Zu Stufe 3: Das unbekannte Feld name ignoriert Jackson 3 einfach. Bei {}
fehlt zahl – Jackson setzt dann den Standardwert für int ein, also 0. Das
Spiel lehnt die 0 ab: 400, Nur Zahlen von 1 bis 100: 0. Gut, dass die
Regel im Kern steht und nicht im Server.
package de.drv.zahlenraten;
import com.sun.net.httpserver.HttpExchange;import com.sun.net.httpserver.HttpServer;
import tools.jackson.core.JacksonException;import tools.jackson.databind.json.JsonMapper;
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;
/** * Der Zahlenraten-Server mit JSON statt Text: * * <pre> * POST /spiele → 201 {"id":"…","von":1,"bis":100} * POST /spiele/{id}/versuche {"zahl":42} → 200 {"hinweis":"ZU_KLEIN","versuche":3} * Fehler → 4xx {"fehler":"…"} * </pre> */public class JsonServer {
private static final Pattern VERSUCHE = Pattern.compile("/spiele/([^/]+)/versuche");
private final Spielleiter spielleiter; private final int port; private final JsonMapper json = JsonMapper.builder().build(); private HttpServer server;
public JsonServer(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 (JSON) auf http://localhost:" + getPort()); }
public void stoppe() { server.stop(0); }
public int getPort() { return server.getAddress().getPort(); }
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 = fehler(anfrage, 404, "Unbekannt: " + methode + " " + pfad); } } catch (SpielNichtGefunden e) { status = fehler(anfrage, 404, e.getMessage()); } catch (JacksonException e) { status = fehler(anfrage, 400, "Kein gültiges JSON"); } catch (IllegalArgumentException e) { status = fehler(anfrage, 400, e.getMessage()); } catch (IllegalStateException e) { status = fehler(anfrage, 409, e.getMessage()); } catch (Exception e) { e.printStackTrace(); status = fehler(anfrage, 500, "Interner Fehler"); } System.out.printf("%-4s %-55s %d%n", methode, pfad, status); }
/** POST /spiele – der Spielstart ist ein Record, Jackson macht JSON daraus. */ private int neuesSpiel(HttpExchange anfrage) throws IOException { return antworte(anfrage, 201, spielleiter.neuesSpiel()); }
/** POST /spiele/{id}/versuche mit {"zahl": 42} */ private int rate(HttpExchange anfrage, String spielId) throws IOException { Versuch versuch = lies(anfrage, Versuch.class); return antworte(anfrage, 200, spielleiter.rate(spielId, versuch.zahl())); }
// ----- Werkzeuge ---------------------------------------------------------------------
/** Liest den Rumpf als JSON in einen Record vom Typ {@code typ}. */ <T> T lies(HttpExchange anfrage, Class<T> typ) throws IOException { try (InputStream rumpf = anfrage.getRequestBody()) { return json.readValue(rumpf, typ); } }
/** Schreibt ein Objekt – meist einen Record – als JSON. */ int antworte(HttpExchange anfrage, int status, Object nachricht) throws IOException { byte[] bytes = json.writeValueAsBytes(nachricht); anfrage.getResponseHeaders().set("Content-Type", "application/json; charset=utf-8"); anfrage.sendResponseHeaders(status, bytes.length); try (OutputStream aus = anfrage.getResponseBody()) { aus.write(bytes); } return status; }
/** Schreibt einfachen Text – wie im Text-Protokoll. */ int antworteText(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; }
/** Eine Fehlerantwort als {"fehler": "…"}. */ private int fehler(HttpExchange anfrage, int status, String meldung) { try { return antworte(anfrage, status, new Fehler(meldung)); } catch (IOException e) { anfrage.close(); return status; } }
}Lösung
Der Test schickt dieselben Records, die der Server benutzt. Damit ist er auch ein kleiner Client – und genau den bauen wir in Teil 6 richtig.
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;
import tools.jackson.databind.json.JsonMapper;
class JsonServerTest {
private final JsonMapper json = JsonMapper.builder().build(); private final HttpClient client = HttpClient.newHttpClient(); private JsonServer server;
@BeforeEach void starte() throws IOException { server = new JsonServer(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 mit JSON – die Antworten lassen sich direkt in Records lesen") void ganzesSpiel() throws Exception { HttpResponse<String> angelegt = post("/spiele", ""); assertEquals(201, angelegt.statusCode()); Spielstart start = json.readValue(angelegt.body(), Spielstart.class); assertEquals(1, start.von());
int von = start.von(); int bis = start.bis(); while (true) { int mitte = (von + bis) / 2; String anfrage = json.writeValueAsString(new Versuch(mitte)); Antwort antwort = json.readValue(post("/spiele/" + start.id() + "/versuche", anfrage).body(), Antwort.class); if (antwort.hinweis() == Hinweis.RICHTIG) { assertTrue(antwort.versuche() <= 7); break; } if (antwort.hinweis() == Hinweis.ZU_KLEIN) { von = mitte + 1; } else { bis = mitte - 1; } } }
@Test @DisplayName("Fehler kommen als {\"fehler\": …} mit dem passenden Statuscode") void fehler() throws Exception { String id = json.readValue(post("/spiele", "").body(), Spielstart.class).id();
HttpResponse<String> keinJson = post("/spiele/" + id + "/versuche", "zweiundvierzig"); assertEquals(400, keinJson.statusCode()); assertEquals("Kein gültiges JSON", json.readValue(keinJson.body(), Fehler.class).fehler());
assertEquals(400, post("/spiele/" + id + "/versuche", "{\"zahl\": 101}").statusCode()); assertEquals(400, post("/spiele/" + id + "/versuche", "{\"zahl\": \"viel\"}").statusCode()); assertEquals(404, post("/spiele/gibt-es-nicht/versuche", "{\"zahl\": 50}").statusCode()); }
}