Zum Inhalt springen

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.

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

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
Versuch.java
package de.drv.zahlenraten;
/** Der Rumpf eines Versuchs im JSON-Protokoll: {@code {"zahl": 42}} */
public record Versuch(int zahl) {
}
Fehler.java
package de.drv.zahlenraten;
/** Der Rumpf jeder Fehlerantwort im JSON-Protokoll: {@code {"fehler": "…"}} */
public record Fehler(String fehler) {
}

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.

JsonServer.java
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.
  • neuesSpiel ist dadurch nur noch eine Zeile.
  • Ein neues catch: Ist der Rumpf kein gültiges JSON – oder steht bei zahl ein Text –, wirft Jackson eine JacksonException. Das ist ein Fehler des Clients: 400.
  • Eine NumberFormatException gibt es nicht mehr. Die Zahl liest jetzt Jackson.

So sieht es im Moment aus:

Terminal-Fenster
$ 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 umgesetzt

501 heißt Not Implemented – genau das stimmt.

Arbeite im Demo-Projekt zahlenraten-5.

  1. Raten: Setze rate um: den Rumpf als Versuch lesen, den Spielleiter fragen, die Antwort als JSON zurückschicken. Es sind zwei Zeilen.

  2. Fehler als JSON: Im Moment meldet fehler noch 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.

  3. Was übersieht Jackson? Schicke {"zahl":50,"name":"Anna"} und {}. Was passiert jeweils – und warum?

  4. Für Schnelle – ein Test: Mach aus dem TextServerTest aus Teil 4 einen JsonServerTest. Den JsonMapper kannst du im Test genauso benutzen wie im Server.

Lösung
Terminal-Fenster
$ 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"} 400

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

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

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