9. Kommunikation mit dem Server
Der RdvMedecins-Server läuft (siehe das vorherige Kapitel, mit [CAPTCHA_TEST=test] in seiner Datei [.env] für die Tests). Die Beispiele 22 bis 25 fragen ihn vom Telefon aus ab.
9.0.1. Wo ist der Server?
Eine Webanwendung, die vom Server selbst ausgeliefert wird, muss sich diese Frage nicht stellen: Ihre Anfragen gehen an denselben Origin wie die Seite. Eine MOBILE Anwendung schon: Ihr muss die vollständige Adresse des Servers mitgeteilt werden. Das Telefon ist jedoch nicht der Rechner, auf dem der Server läuft:
| // =========================================================================
// common/Config.kt - WO befindet sich der JSON-Server? (Beispiele 22 bis 25)
// -------------------------------------------------------------------------
// Eine vom Server selbst ausgelieferte Webanwendung muss diese Frage nicht
// stellen: Ihre Anfragen gehen an denselben Ursprung (Origin) wie die
// Seite. Eine MOBILE Anwendung muss das: Man muss ihr die vollständige Adresse
// des Servers geben. Aber das Smartphone ist nicht der Rechner, auf dem der
// Server läuft:
// - "localhost" ist für das Smartphone (oder den Emulator) es SELBST. Der
// Befehl adb reverse tcp:8080 tcp:8080 behebt das: Er verbindet den
// Port 8080 des Smartphones mit dem Port 8080 des Rechners, über das USB-Kabel
// (oder, beim Emulator, direkt). Das ist die standardmäßig gewählte Lösung:
// http://localhost:8080;
// - der Android-Emulator sieht den Rechner außerdem unter der speziellen Adresse
// 10.0.2.2;
// - ein echtes Smartphone, das im selben WLAN wie der Rechner hängt, kann
// die Adresse des Rechners in diesem Netz verwenden (192.168.1.20 ...).
// Die Adresse wird zur COMPILE-Zeit festgelegt (BuildConfig, vgl. app/build.gradle.kts):
// gradlew installDebug -Pserver=http://10.0.2.2:8080
// =========================================================================
package fr.stahe.examples.common
import fr.stahe.examples.BuildConfig
object Config {
val serverUrl: String = BuildConfig.SERVER_URL
}
|
- „localhost“ ist für das Telefon (oder den Emulator) das Gerät SELBST. Der Befehl [adb reverse tcp:8080 tcp:8080] verbindet Port 8080 des Telefons über das USB-Kabel (oder direkt beim Emulator) mit Port 8080 des Rechners. Das ist die Standardlösung: [http://localhost:8080]. Der Befehl muss bei jedem Start des Emulators erneut ausgeführt werden;
- der Emulator sieht den Rechner außerdem unter der Sonderadresse [10.0.2.2];
- ein echtes Telefon im selben WLAN wie der Rechner kann die Adresse des Rechners in diesem Netz verwenden ([192.168.1.20] ...), sofern die Firewall des Rechners Datenverkehr über Port 8080 zulässt.
Die Adresse ist ein Feld der Klasse [BuildConfig], die zur Kompilierungszeit erzeugt wird (siehe [app/build.gradle.kts], Beispiel 01); sie kann geändert werden, ohne den Code anzupassen:
| gradlew installDebug -Pserver=http://10.0.2.2:8080
|
Schließlich fordert das Manifest die Berechtigung [INTERNET] an und erlaubt „unverschlüsselten“ HTTP-Verkehr ([usesCleartextTraffic]): Ab [Android] 9 ist standardmäßig nur HTTPS erlaubt.
9.1. Beispiel 22: Eine erste HTTP-Anfrage
Vom Server wird ein CAPTCHA angefordert: [GET /api/captcha] liefert [{ "id": "...", "svg": "<svg ...>" }]. Der HTTP-Client ist [OkHttp], der unter [Android] am häufigsten verwendete (das Äquivalent des Pakets [http] von [Flutter]).
| // =========================================================================
// ex22/Ex22Activity.kt - eine erste HTTP-Anfrage an den Server
// -------------------------------------------------------------------------
// Der JSON-Server von RdvMedecins muss laufen (Port 8080). Wir fordern von ihm
// ein CAPTCHA an: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
//
// - OkHttp, der am häufigsten genutzte HTTP-Client unter Android: Wir beschreiben die
// Anfrage (Request), der Client führt sie aus (newCall(...).execute()) und
// liefert die Antwort: ihren Statuscode (code), ihre Header
// (headers), ihren Body (body);
// - execute() BLOCKIERT bis zur Antwort: Android verbietet den Aufruf
// im UI-Thread. withContext(Dispatchers.IO)
// führt ihn in einem anderen Thread aus, und die Coroutine WARTET auf das Ergebnis;
// - Json.parseToJsonElement(text): der JSON-Body -> Kotlin-Objekte;
// - die Adresse des Servers hängt davon ab, wo die Anwendung läuft
// (Emulator, Smartphone ...): vgl. common/Config.kt;
// - drei anzuzeigende Zustände: wird geladen, erfolgreich, fehlerhaft;
// - das CAPTCHA-Bild ist SVG: vgl. common/SvgImage.kt.
// =========================================================================
package fr.stahe.examples.ex22
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Button
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.LinearProgressIndicator
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import fr.stahe.examples.common.Config
import fr.stahe.examples.common.SvgImage
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive
import okhttp3.OkHttpClient
import okhttp3.Request
// was GET /api/captcha zurückgibt
data class Captcha(val id: String, val svg: String)
// ein HTTP-Client: ein aufwendig zu erzeugendes Objekt, das nur EINMAL erzeugt wird
val client = OkHttpClient()
// die Anfrage: eine SUSPEND-Funktion, die das CAPTCHA liefert oder eine Exception auslöst
suspend fun readCaptcha(): Captcha = withContext(Dispatchers.IO) {
val request = Request.Builder().url("${Config.serverUrl}/api/captcha").build()
client.newCall(request).execute().use { response ->
// OkHttp löst bei einer Fehlerantwort (4xx,
// 5xx) KEINE Exception aus: der Statuscode wird geprüft
if (!response.isSuccessful) {
throw Exception("the server responded ${response.code} ${response.message}")
}
val json = Json.parseToJsonElement(response.body!!.string()).jsonObject
Captcha(json["id"]!!.jsonPrimitive.content, json["svg"]!!.jsonPrimitive.content)
}
}
class Ex22Activity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
setContent { ExamplesTheme { CaptchaPage() } }
}
}
@Composable
fun CaptchaPage() {
var captcha by remember { mutableStateOf<Captcha?>(null) }
var loading by remember { mutableStateOf(true) }
var error by remember { mutableStateOf<String?>(null) }
var requestCount by remember { mutableIntStateOf(0) }
// die Nummer der ANFORDERUNG: Eine Änderung startet den Effekt unten neu
var demand by remember { mutableIntStateOf(0) }
// die Anfrage, sobald der Bildschirm erscheint (demand = 0), danach bei jeder
// neuen Anforderung. Trifft eine Anforderung ein, bevor die Antwort auf die
// vorherige da ist, wird die vorherige Coroutine ABGEBROCHEN: ihre veraltete Antwort
// wird nie angezeigt
LaunchedEffect(demand) {
loading = true
error = null
try {
captcha = readCaptcha()
requestCount++
} catch (e: CancellationException) {
throw e // die Coroutine wurde abgebrochen (neue Anforderung): nichts anzuzeigen
} catch (e: Exception) {
// überhaupt keine Antwort (Server gestoppt, falsche Adresse ...) oder Fehler
error = e.message ?: e.toString()
captcha = null
}
loading = false
}
ExamplePage("Example 22 - a first HTTP request") {
Text("Server: ${Config.serverUrl}", color = Color.Gray)
Spacer(Modifier.height(12.dp))
if (loading) LinearProgressIndicator(Modifier.fillMaxWidth())
error?.let {
Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFFFEBEE))) {
Text("Unable to get a captcha: $it.\nIs the RdvMedecins JSON server running (port 8080)?", Modifier.padding(12.dp))
}
}
val c = captcha
if (c != null && !loading) {
SvgImage(
c.svg,
height = 60.dp,
modifier = Modifier.border(1.dp, Color(0xFFE0E0E0), RoundedCornerShape(6.dp)).padding(4.dp),
)
Spacer(Modifier.height(8.dp))
Text("id: ${c.id}", fontFamily = FontFamily.Monospace, fontSize = 11.sp)
}
Spacer(Modifier.height(12.dp))
Button(onClick = { demand++ }, enabled = !loading) { Text("Another image") }
Spacer(Modifier.height(8.dp))
Text("$requestCount successful request(s)", color = Color.Gray)
}
}
|
- Zeile 66: ein HTTP-Client, ein Objekt, dessen Erzeugung aufwendig ist und das nur EINMAL erzeugt wird;
- Zeilen 69–71: die Anfrage, eine SUSPEND-Funktion. Die Anfrage ([Request]) wird beschrieben; der Client führt sie aus ([newCall(...).execute()]) und liefert die Antwort: ihren Statuscode, ihre Header und ihren Body. [execute()] BLOCKIERT bis zur Antwort: [Android] verbietet den Aufruf im Ausführungs-Thread des Bildschirms ([NetworkOnMainThreadException]). [withContext(Dispatchers.IO)] führt sie in einem für I/O reservierten Thread aus, und die Coroutine WARTET auf das Ergebnis;
- Zeilen 74–75: [OkHttp] wirft bei einer Fehlerantwort (4xx, 5xx) keine Exception; stattdessen prüft man den Statuscode. Es wirft jedoch eine [IOException], wenn überhaupt keine Antwort eintrifft (Server nicht erreichbar, falsche Adresse);
- Zeilen 77–78: der JSON-Body, „von Hand“ gelesen: [jsonObject], [jsonPrimitive.content];
- Zeilen 103–116: Die Anfrage wird von einem [LaunchedEffect] ausgelöst, dessen Schlüssel eine ANFRAGENUMMER ist: Die Schaltfläche „Another image“ erhöht sie, wodurch der Effect neu gestartet wird. Trifft eine Anfrage ein, bevor die vorherige geantwortet hat, wird die vorherige Coroutine ABGEBROCHEN: Ihre inzwischen veraltete Antwort wird nie angezeigt;
- Zeilen 122–136: drei anzuzeigende Zustände: in Bearbeitung (ein Fortschrittsbalken), Fehler und Erfolg.
Das CAPTCHA-Bild liegt im SVG-Format vor, das [Android] nicht von sich aus anzeigen kann: Die Bibliothek [AndroidSVG] rendert es zu einem Bild ([Bitmap]):
| // =========================================================================
// common/SvgImage.kt - ein als Text vorliegendes SVG-Bild zeichnen
// -------------------------------------------------------------------------
// Das CAPTCHA-Bild wird vom Server im SVG-Format erzeugt (ein Text,
// der eine Zeichnung beschreibt). Android kann es nicht von allein anzeigen: Die
// Bibliothek AndroidSVG zeichnet es in ein Bild (ein Bitmap),
// das Compose mit der Komponente Image anzeigt.
// =========================================================================
package fr.stahe.examples.common
import android.graphics.Bitmap
import android.graphics.Canvas
import androidx.compose.foundation.Image
import androidx.compose.foundation.layout.height
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.asImageBitmap
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import com.caverock.androidsvg.SVG
@Composable
fun SvgImage(svg: String, modifier: Modifier = Modifier, height: Dp = 50.dp, description: String? = null) {
// die Zeichnung wird nur neu erstellt, wenn sich der SVG-Text ändert (remember(svg))
val image = remember(svg) {
val document = SVG.getFromString(svg)
// 3-mal größer als die "natürliche" Größe gezeichnet: ein scharfes Bild
val scale = 3f
val width = (document.documentWidth.takeIf { it > 0 } ?: 150f)
val tall = (document.documentHeight.takeIf { it > 0 } ?: 50f)
val bitmap = Bitmap.createBitmap((width * scale).toInt(), (tall * scale).toInt(), Bitmap.Config.ARGB_8888)
val canvas = Canvas(bitmap)
canvas.scale(scale, scale)
document.renderToCanvas(canvas)
bitmap.asImageBitmap()
}
Image(image, contentDescription = description, contentScale = ContentScale.Fit, modifier = modifier.height(height))
}
|


Halten Sie den Server an und klicken Sie auf „Another image“: Der Fehler wird angezeigt.
9.2. Beispiel 23: Anmeldung, Cookie und Sitzung
Der Server legt das JWT-Token in einem COOKIE ab. In einem Browser ist der Browser dafür zuständig, Cookies zu speichern und zurückzusenden; der Code der Anwendung muss nichts tun. Auf einem Telefon gibt es keinen Browser: Dies muss die Anwendung selbst übernehmen. [OkHttp] tut dies, wenn man ihm einen „Cookie-Behälter“ ([CookieJar]) mitgibt:
| // =========================================================================
// common/HttpClient.kt - ein HTTP-Client, der COOKIES verwaltet
// -------------------------------------------------------------------------
// Der RdvMedecins-Server legt das JWT-Token in einem COOKIE (httpOnly) ab.
// In einem Browser speichert der Browser die Cookies und sendet sie
// bei jeder Anfrage zurück: Der Code der Anwendung muss sich um nichts kümmern.
// Auf einem Smartphone gibt es KEINEN Browser: Die Anwendung muss
// seine Rolle übernehmen, das heißt:
// 1. den Header "Set-Cookie" jeder Antwort lesen und die Cookies speichern;
// 2. sie im Header "Cookie" jeder Anfrage zurücksenden.
// Die Bibliothek OkHttp erledigt das für uns, wenn wir ihr einen CookieJar geben
// (ein "Cookie Jar"): eine Klasse mit zwei Funktionen, saveFromResponse
// (speichern) und loadForRequest (herausholen). Dieser speichert die Cookies
// auch auf dem Gerät (SharedPreferences): Wir bleiben angemeldet, wenn wir die Anwendung
// beenden und neu starten.
// =========================================================================
package fr.stahe.examples.common
import android.content.Context
import android.content.SharedPreferences
import androidx.core.content.edit
import okhttp3.Cookie
import okhttp3.CookieJar
import okhttp3.HttpUrl
import okhttp3.HttpUrl.Companion.toHttpUrl
import okhttp3.OkHttpClient
import java.util.concurrent.TimeUnit
class DeviceCookieJar(private val storage: SharedPreferences) : CookieJar {
// Cookie-Name -> das Cookie (sein Wert, seine Domain, sein Ablaufdatum ...)
private val cookies = mutableMapOf<String, Cookie>()
init {
// die bei einer früheren Nutzung gespeicherten Cookies: Jedes
// wird in Form seines Set-Cookie-Headers gespeichert
val base = Config.serverUrl.toHttpUrl()
for (text in storage.getStringSet(KEY, emptySet()).orEmpty()) {
Cookie.parse(base, text)?.let { cookies[it.name] = it }
}
}
// die Antwort bringt Cookies mit: Wir speichern sie. Ein bereits abgelaufenes Cookie
// (so löscht der Server es beim Logout) wird entfernt
@Synchronized
override fun saveFromResponse(url: HttpUrl, cookies: List<Cookie>) {
for (c in cookies) {
if (c.expiresAt < System.currentTimeMillis() || c.value.isEmpty()) {
this.cookies.remove(c.name)
} else {
this.cookies[c.name] = c
}
}
storage.edit { putStringSet(KEY, this@DeviceCookieJar.cookies.values.map { it.toString() }.toSet()) }
}
// eine Anfrage geht hinaus: die Cookies, die sie betreffen (Adresse, Pfad) und nicht abgelaufen sind
@Synchronized
override fun loadForRequest(url: HttpUrl): List<Cookie> =
cookies.values.filter { it.expiresAt >= System.currentTimeMillis() && it.matches(url) }
companion object {
private const val KEY = "rdvmedecins.cookies"
}
}
// der HTTP-Client der Beispiele: ein einziger für die ganze Anwendung
fun createHttpClient(context: Context): OkHttpClient = OkHttpClient.Builder()
.cookieJar(DeviceCookieJar(context.getSharedPreferences("examples", Context.MODE_PRIVATE)))
// keine Antwort nach 10 Sekunden: Die Anfrage schlägt fehl
.connectTimeout(10, TimeUnit.SECONDS)
.readTimeout(10, TimeUnit.SECONDS)
.build()
|
- Zeile 29: Ein [CookieJar] hat zwei Funktionen: [saveFromResponse] (Cookies einer Antwort speichern) und [loadForRequest] (die Cookies für eine Anfrage abrufen);
- Zeilen 33–38: Beim Start werden Cookies, die während einer früheren Sitzung gespeichert wurden – auf dem Gerät gesichert ([SharedPreferences], eine kleine Schlüssel-Wert-Datei; siehe Beispiel 20) –, in Form ihres Headers [Set-Cookie] wieder abgerufen;
- Zeilen 44–53: Ein bereits abgelaufenes oder leeres Cookie wird entfernt; so löscht der Server das Cookie bei der Abmeldung; [@Synchronized]: [OkHttp] kann diese Funktionen aus mehreren Threads gleichzeitig aufrufen;
- Zeilen 67–72: der HTTP-Client aus den Beispielen, mit seinem Jar und seinen Timeouts.
Der Client wird einmal für die gesamte Anwendung im Objekt [Application] erzeugt (im Manifest deklariert), das [Android] beim Start erzeugt, bevor irgendeine Activity beginnt:
| // =========================================================================
// ExamplesApplication.kt - das "Application"-Objekt
// -------------------------------------------------------------------------
// Android erzeugt beim Start der Anwendung EIN Application-Objekt, vor
// jeder Activity, und behält es, bis die Anwendung endet (es wird in
// AndroidManifest.xml deklariert, android:name=".ExamplesApplication"). Es ist
// der Ort für alles, was von ALLEN Activities gemeinsam genutzt werden muss:
// hier der HTTP-Client und sein Cookie Jar (Beispiele 23 bis 25). Eine
// Activity erhält es mit (application as ExamplesApplication).api.
// =========================================================================
package fr.stahe.examples
import android.app.Application
import fr.stahe.examples.common.Api
import fr.stahe.examples.common.createHttpClient
import okhttp3.OkHttpClient
class ExamplesApplication : Application() {
// by lazy: wird bei der ersten Anforderung erzeugt
val httpClient: OkHttpClient by lazy { createHttpClient(this) }
val api: Api by lazy { Api(httpClient) }
}
|
Eine asynchrone Aktion (anmelden, speichern usw.) hat einen Status, den der Bildschirm anzeigen muss: Läuft sie? Endete sie mit einem Fehler? Eine kleine Klasse übernimmt dies:
| // =========================================================================
// ex23/Command.kt - eine AKTION, ihr Zustand, ihr Ergebnis
// -------------------------------------------------------------------------
// Eine asynchrone Aktion (Anmelden, Speichern ...) hat einen Zustand,
// den der Bildschirm anzeigen muss: Läuft sie GERADE (Button deaktiviert)? Endete sie
// mit einem FEHLER (Meldung)? Es ist das Muster "Command", auf das
// Wesentliche reduziert:
//
// val loginCommand = remember { Command() }
// scope.launch { loginCommand.execute { logIn() } } // startet die Aktion
// loginCommand.inProgress, loginCommand.error // ihr Zustand
//
// Ihre beiden Properties sind von Compose beobachtete Zustände: Der Bildschirm wird
// neu gezeichnet, wenn die Aktion beginnt und wenn sie endet.
// =========================================================================
package fr.stahe.examples.ex23
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import kotlinx.coroutines.CancellationException
class Command {
var inProgress by mutableStateOf(false)
private set
var error by mutableStateOf<String?>(null)
private set
// führt die Aktion aus, sofern nicht bereits eine andere läuft
suspend fun execute(action: suspend () -> Unit) {
if (inProgress) return // kein doppeltes Absenden (doppeltes Drücken des Buttons)
inProgress = true
error = null
try {
action()
} catch (e: CancellationException) {
throw e // eine abgebrochene Coroutine muss abgebrochen bleiben
} catch (e: Exception) {
error = e.message ?: e.toString() // der Fehler wird BEHALTEN, um angezeigt zu werden
} finally {
// finally: wird in ALLEN Fällen ausgeführt, bei Erfolg oder Fehler
inProgress = false
}
}
fun clearError() {
error = null
}
}
|
- Zeile 31: verhindert die doppelte Übermittlung (doppeltes Tippen auf die Schaltfläche);
- Zeilen 40–42: [finally]: wird in ALLEN Fällen ausgeführt, bei Erfolg und bei Fehler.
Der Anmeldebildschirm:
| // =========================================================================
// ex23/Ex23Activity.kt - Anmeldung am RdvMedecins-Server
// -------------------------------------------------------------------------
// 1. beim Start: GET /api/auth/me - sind wir bereits angemeldet?
// (Die Anwendung kann beendet worden sein; der Server liest seinerseits das ihm
// vorgelegte Cookie);
// 2. Anmeldung: POST /api/auth/login, JSON-Body { login, password,
// captchaId, captcha }. Bei Erfolg sendet der Server das Cookie
// des JWT-Tokens (Header Set-Cookie);
// 3. geschützte Anfrage: GET /api/doctors. Das Cookie wird mitgesendet;
// 4. Abmeldung: POST /api/auth/logout - der Server löscht das Cookie.
// Es ist der HTTP-Client der Anwendung (common/HttpClient.kt) mit seinem
// Cookie Jar, der das Cookie speichert und zurücksendet.
// =========================================================================
package fr.stahe.examples.ex23
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.text.withStyle
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import fr.stahe.examples.ExamplesApplication
import fr.stahe.examples.common.Config
import fr.stahe.examples.common.SvgImage
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonArray
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.jsonArray
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive
import kotlinx.serialization.json.put
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
// die wenigen Meldungen, die dieses Beispiel braucht (Beispiel 25 verwendet Wörterbücher)
val messages = mapOf(
"LOGIN.ERROR" to "Incorrect login or password.",
"ERRORS.WRONG_CAPTCHA" to "The characters do not match the image.",
"ERRORS.TOO_MANY_ATTEMPTS" to "Too many failed attempts. Try again later.",
)
// eine Antwort, die kein 2xx ist, wird zu einer Exception, die ihren Code und ihren Body behält
class ErrorResponse(val code: Int, val body: String) : Exception("the server responded $code")
// eine auf das Wesentliche reduzierte HTTP-Antwort
data class Response(val code: Int, val body: String)
class Ex23Activity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
// der HTTP-Client der Anwendung mit seinem Cookie Jar
val client = (application as ExamplesApplication).httpClient
setContent { ExamplesTheme { LoginPage(client) } }
}
}
// eine Anfrage im Ein-/Ausgabe-Thread ausführen
suspend fun send(client: OkHttpClient, request: Request): Response = withContext(Dispatchers.IO) {
client.newCall(request).execute().use { Response(it.code, it.body?.string().orEmpty()) }
}
@Composable
fun LoginPage(client: OkHttpClient) {
var user by remember { mutableStateOf<JsonObject?>(null) } // null: niemand ist angemeldet
var doctors by remember { mutableStateOf<JsonArray?>(null) }
var captcha by remember { mutableStateOf<JsonObject?>(null) }
var ready by remember { mutableStateOf(false) } // ist die erste Prüfung abgeschlossen?
var serverError by remember { mutableStateOf<String?>(null) }
val loginCommand = remember { Command() }
var login by remember { mutableStateOf("admin") }
var password by remember { mutableStateOf("") }
var captchaAnswer by remember { mutableStateOf("") }
val scope = rememberCoroutineScope()
fun url(path: String) = "${Config.serverUrl}/api$path"
// eine GET-Anfrage, deren JSON-Body wir wollen; eine Exception, wenn es kein 2xx ist
suspend fun read(path: String): JsonElement {
val r = send(client, Request.Builder().url(url(path)).build())
if (r.code >= 300) throw ErrorResponse(r.code, r.body)
return Json.parseToJsonElement(r.body)
}
// ein POST mit JSON-Body
suspend fun post(path: String, body: JsonObject): Response =
send(client, Request.Builder().url(url(path)).post(body.toString().toRequestBody("application/json".toMediaType())).build())
suspend fun loadCaptcha() {
captcha = read("/captcha").jsonObject
captchaAnswer = ""
}
suspend fun loadDoctors() {
doctors = read("/doctors").jsonArray
}
// 1. wer ist angemeldet? 200 -> der Benutzer; 401 -> niemand
LaunchedEffect(Unit) {
try {
user = read("/auth/me").jsonObject
loadDoctors()
} catch (e: ErrorResponse) {
// "catch (e: Type)": fängt NUR diesen Exception-Typ ab
if (e.code == 401) loadCaptcha() else serverError = "The server responded ${e.code}."
} catch (e: java.io.IOException) {
serverError = "Is the RdvMedecins JSON server running (${Config.serverUrl})?"
}
ready = true
}
// 2. die Anmeldung: eine vom Command ausgeführte Aktion, die ihren Fehler behält
suspend fun logIn() {
val r = post(
"/auth/login",
buildJsonObject {
put("login", login.trim())
put("password", password)
put("captchaId", captcha?.get("id")?.jsonPrimitive?.content)
put("captcha", captchaAnswer)
},
)
if (r.code != 200) {
// der JSON-Body der Fehlerantwort: { statusCode, key, ... }
val key = Json.parseToJsonElement(r.body).jsonObject["key"]!!.jsonPrimitive.content
loadCaptcha() // jedes Bild wird nur einmal verwendet
throw Exception("${r.code} - ${messages[key] ?: key}")
}
password = ""
user = Json.parseToJsonElement(r.body).jsonObject
loadDoctors()
}
// 4. die Abmeldung
suspend fun logOut() {
post("/auth/logout", JsonObject(emptyMap()))
user = null
doctors = null
loadCaptcha()
}
// ein JSON-Text -> sein Wert, ohne die Anführungszeichen
fun JsonObject.text(key: String) = this[key]?.jsonPrimitive?.content.orEmpty()
ExamplePage("Example 23 - logging in to the server") {
val u = user
when {
!ready -> Text("Checking the session...", color = Color.Gray)
// angemeldet
u != null -> Card(Modifier.fillMaxWidth()) {
Column(Modifier.padding(12.dp)) {
Text(
buildAnnotatedString {
append("Logged in: ")
withStyle(SpanStyle(fontWeight = FontWeight.Bold)) { append(u.text("name")) }
append(" (${u.text("login")}), role ${u.text("role")}")
},
)
Spacer(Modifier.height(8.dp))
Text("GET /api/doctors", style = MaterialTheme.typography.titleSmall)
for (d in doctors.orEmpty()) {
val o = d.jsonObject
Text("• ${o.text("title")} ${o.text("firstName")} ${o.text("lastName")}")
}
Spacer(Modifier.height(8.dp))
Text("Stop then restart the application: you stay logged in.", color = Color.Gray)
Spacer(Modifier.height(8.dp))
OutlinedButton(onClick = { scope.launch { logOut() } }) { Text("Log out") }
}
}
// nicht angemeldet: das Formular
serverError == null -> Card(Modifier.fillMaxWidth()) {
Column(Modifier.padding(12.dp)) {
OutlinedTextField(login, { login = it }, label = { Text("Login") }, singleLine = true, modifier = Modifier.fillMaxWidth())
OutlinedTextField(
password,
{ password = it },
label = { Text("Password") },
singleLine = true,
visualTransformation = PasswordVisualTransformation(),
modifier = Modifier.fillMaxWidth(),
)
Spacer(Modifier.height(12.dp))
Row(verticalAlignment = Alignment.CenterVertically) {
captcha?.let { SvgImage(it.text("svg"), height = 50.dp) }
TextButton(onClick = { scope.launch { runCatching { loadCaptcha() } } }) { Text("Another image") }
}
OutlinedTextField(
captchaAnswer,
{ captchaAnswer = it },
label = { Text("Copy the characters of the image") },
singleLine = true,
modifier = Modifier.fillMaxWidth(),
)
Spacer(Modifier.height(16.dp))
// dieser Teil folgt dem Zustand des Commands
Button(onClick = { scope.launch { loginCommand.execute { logIn() } } }, enabled = !loginCommand.inProgress) {
Text(if (loginCommand.inProgress) "Logging in..." else "Log in")
}
loginCommand.error?.let { Text(it, color = Color.Red, modifier = Modifier.padding(top = 12.dp)) }
Spacer(Modifier.height(8.dp))
Text("Accounts: admin, pelissier, martin... (password = login).", color = Color.Gray, fontSize = 12.sp)
}
}
}
serverError?.let {
Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFFFEBEE))) { Text(it, Modifier.padding(12.dp)) }
}
}
}
|
- Zeile 92: der HTTP-Client der Anwendung ([application as ExamplesApplication]: eine Typumwandlung);
- Zeilen 138–148: Beim Start [GET /api/auth/me]: Sind wir bereits angemeldet? Die Anwendung wurde möglicherweise beendet; das Cookie blieb jedoch auf dem Gerät erhalten. [catch (e: ErrorResponse)] fängt NUR diesen Exception-Typ ab; ein 401 bedeutet „nicht autorisiert“;
- Zeilen 152–170: [POST /api/auth/login], JSON-Body, erzeugt von [buildJsonObject]. Schlägt der Versuch fehl, liefert der Body der Antwort den Fehlercode; ein neues CAPTCHA wird angefordert (jedes Bild wird nur einmal verwendet);
- Zeilen 174–178: Abmeldung, [POST /api/auth/logout]: Der Server löscht das Cookie;
- Zeile 182: eine LOKALE Erweiterungsfunktion, um Text aus einem JSON-Objekt zu lesen;
- Zeilen 236–239: Die Schaltfläche verfolgt den Zustand des Befehls.



Beenden Sie die Anwendung (indem Sie sie aus der Liste der zuletzt verwendeten Apps entfernen) und starten Sie das Beispiel dann neu: Sie sind weiterhin angemeldet.
9.3. Beispiel 24: Eine Zugriffsschicht für die API
Beispiel 23 wiederholt für jede Anfrage dieselben Schritte: Serveradresse, Präfix [/api], JSON-Body, Prüfung des Statuscodes und Lesen des Fehler-Bodys. Diese werden in drei Schichten zusammengefasst. Die erste Schicht führt eine Anfrage aus und wandelt JEDEN Fehler in eine einzige Exception-Klasse um:
| // =========================================================================
// common/ApiError.kt - EINE Klasse für alle API-Fehler
// -------------------------------------------------------------------------
// Alle Fehlerantworten des RdvMedecins-Servers haben dieselbe Form:
// { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Eine Anfrage kann aber auch AUF ANDERE WEISE scheitern: gar keine Antwort
// (Netzwerk ausgefallen, Server gestoppt, falsche Adresse) oder eine Antwort, die
// nicht von unserem Server stammt (eine Fehlerseite eines Proxys). Wir wandeln
// all das in EINE Exception-Klasse um, ApiError, die den vom Server gesendeten Übersetzungsschlüssel
// (und gegebenenfalls dessen Parameter sowie
// den Fehler jedes Feldes) trägt.
// =========================================================================
package fr.stahe.examples.common
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.jsonObject
class ApiError(
val statusCode: Int, // 0: der Server hat nicht geantwortet
val key: String, // z. B.: "ERRORS.LOGIN_TAKEN"
val params: Map<String, String> = emptyMap(),
val fields: Map<String, String> = emptyMap(),
) : Exception("$statusCode $key") {
override fun toString() = "$statusCode $key"
// companion object: was zur KLASSE gehört (das "static" von Java)
companion object {
// eine Fehlerantwort (4xx, 5xx) -> ein ApiError
fun fromResponse(statusCode: Int, body: String): ApiError {
// runCatching: das Ergebnis oder null, wenn der Body kein JSON ist
// (dann hat nicht unser Server geantwortet)
val json = runCatching { Json.parseToJsonElement(body).jsonObject }.getOrNull()
val key = (json?.get("key") as? JsonPrimitive)?.content
if (json == null || key == null) {
return ApiError(statusCode, if (statusCode >= 500) "ERRORS.SERVER_UNREACHABLE" else "ERRORS.SERVER_ERROR")
}
return ApiError(statusCode, key, strings(json["params"]), strings(json["fields"]))
}
// ein JSON-Objekt { "name": "ERRORS..." } -> Map<String, String> (sonst leer)
private fun strings(json: Any?): Map<String, String> =
(json as? JsonObject)?.mapValues { (_, v) -> (v as? JsonPrimitive)?.content ?: v.toString() } ?: emptyMap()
}
}
// =========================================================================
// common/Api.kt - Anfragen an die API in einer Zeile
// -------------------------------------------------------------------------
// In Beispiel 23 wiederholt jede Anfrage dieselben Schritte: Serveradresse,
// Präfix /api, JSON-Body, Prüfung des Statuscodes, Lesen des
// Fehler-Bodys ... Sie werden hier zusammengefasst:
//
// val json = api.get("/doctors")
// api.post("/appointments", buildJsonObject { put("day", day); put("slotId", 3) })
//
// - bei Erfolg gibt die Funktion den JSON-Body zurück (ein JsonElement:
// ein Objekt, ein Array ...) oder null bei leerem Body;
// - bei einem Fehler löst sie einen ApiError aus.
// Es sind SUSPEND-Funktionen: Sie warten auf die Antwort des Servers, ohne
// das Smartphone zu blockieren. Die Anfrage selbst wird in einem für
// Ein-/Ausgabe reservierten Thread ausgeführt (Dispatchers.IO): Android
// verbietet Netzwerkzugriffe im UI-Thread.
// Alle Anfragen laufen über die Funktion request: Dort würde
// ein ALLEN gemeinsames Problem behandelt (vgl. die Fallstudie und die
// Antwort 401). Verwendet von den Beispielen 24 und 25.
// =========================================================================
package fr.stahe.examples.common
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import java.io.IOException
class Api(private val client: OkHttpClient) {
suspend fun request(method: String, url: String, body: JsonElement? = null): JsonElement? =
withContext(Dispatchers.IO) {
// ein JSON-Body (der Server weist einen POST ohne Body zurück)
val httpBody = body?.toString()?.toRequestBody("application/json".toMediaType())
val request = Request.Builder().url("${Config.serverUrl}/api$url").method(method, httpBody).build()
try {
// use: die Antwort wird am Ende des Blocks geschlossen (freigegeben)
client.newCall(request).execute().use { response ->
val text = response.body?.string().orEmpty()
if (!response.isSuccessful) throw ApiError.fromResponse(response.code, text)
if (text.isEmpty()) null else Json.parseToJsonElement(text)
}
} catch (e: IOException) {
// KEINE Antwort (Netzwerk, Server gestoppt, falsche Adresse)
throw ApiError(0, "ERRORS.SERVER_UNREACHABLE")
}
}
suspend fun get(url: String) = request("GET", url)
// ein POST hat immer einen JSON-Body: standardmäßig {}
suspend fun post(url: String, body: JsonElement = JsonObject(emptyMap())) = request("POST", url, body)
suspend fun put(url: String, body: JsonElement) = request("PUT", url, body)
suspend fun delete(url: String, body: JsonElement? = null) = request("DELETE", url, body)
}
|
- Zeilen 37–47: Bei Erfolg liefert die Funktion den JSON-Body ([JsonElement]) oder [null] bei leerem Body; bei Misserfolg einen [ApiError];
- Zeilen 55–62: Abkürzungen je nach HTTP-Methode.
Die ausgetauschten JSON-Objekte werden zu [Kotlin]- und [@Serializable]-Klassen:
| // =========================================================================
// common/Types.kt - die mit der RdvMedecins-API ausgetauschten JSON-Objekte
// (vgl. das Kapitel über die Blackbox, das jede Route beschreibt)
// -------------------------------------------------------------------------
// Jede Klasse ist @Serializable: Das Plugin kotlinx.serialization schreibt für
// sie den Code, der sie aus JSON aufbaut. Beim Lesen wird die Form des empfangenen JSON
// GEPRÜFT: Ein fehlendes Feld oder eines vom falschen Typ löst beim Empfang eine
// Exception aus und nicht erst später mitten in der Anzeige.
// val u = json.decodeFromJsonElement<User>(response)
// Ein OPTIONALES Feld hat einen Standardwert (login: String? = null).
// =========================================================================
package fr.stahe.examples.common
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.serializer
enum class Role { ADMIN, DOCTOR, USER }
// POST /api/auth/login, GET /api/auth/me
@Serializable
data class User(val login: String, val name: String, val role: Role)
// GET /api/captcha
@Serializable
data class Captcha(val id: String, val svg: String)
// ein Arzt oder ein Client (GET /api/doctors, GET /api/clients ...)
@Serializable
data class Person(
val id: Int,
val version: Int,
val title: String,
val firstName: String,
val lastName: String,
val login: String? = null, // nur für den ADMIN
) {
val fullName get() = "$title $firstName $lastName"
}
// der Name einer Person, sonst nichts
@Serializable
data class Identity(val title: String, val firstName: String, val lastName: String) {
override fun toString() = "$title $firstName $lastName"
}
// eine Zeile von GET /api/schedule
@Serializable
data class ScheduleSlot(
val id: Int,
val startHour: Int,
val startMinute: Int,
val endHour: Int,
val endMinute: Int,
val free: Boolean,
val patient: Identity?,
val mine: Boolean,
val bookable: Boolean,
val appointmentId: Int?,
) {
// "8:00 - 8:20"
val timeRange: String
get() {
fun hm(h: Int, m: Int) = "$h:${m.toString().padStart(2, '0')}"
return "${hm(startHour, startMinute)} - ${hm(endHour, endMinute)}"
}
}
// GET /api/schedule?doctorId=...&day=...
@Serializable
data class Schedule(val doctor: Person, val day: String, val slots: List<ScheduleSlot>, val info: String?)
// der JSON-Reader: ignoreUnknownKeys, die vom Client nicht verwendeten Felder
// werden ignoriert (der Server kann welche hinzufügen, ohne den Client zu beschädigen)
val apiJson = Json { ignoreUnknownKeys = true }
// JsonElement -> Kotlin-Objekt: eine "reified" generische Funktion (der Typ T
// ist zur Laufzeit bekannt); serializer<T>(): der vom Plugin geschriebene Code
inline fun <reified T> JsonElement?.read(): T =
apiJson.decodeFromJsonElement(serializer<T>(), this ?: throw IllegalStateException("empty response"))
|
- Zeile 37: Ein optionales Feld hat einen Standardwert; [Identity?]: ein Objekt oder [null];
- Zeile 76: [ignoreUnknownKeys]: Felder, die der Client nicht verwendet, werden ignoriert (der Server kann sie hinzufügen, ohne den Client zu beschädigen);
- Zeilen 80–81: Eine GENERISCHE Erweiterungsfunktion ist „reified“ ([reified]: Der Typ [T] ist zur Laufzeit bekannt, was [inline] erlaubt). [serializer<T>()]: der vom Plugin für [T] geschriebene Code. Das Lesen PRÜFT das Format des JSON: Ein fehlendes Feld oder ein Feld mit falschem Typ löst schon beim Empfang eine Exception aus und nicht erst später mitten in der Anzeige.
Die zweite Schicht: eine typsichere Funktion pro Route der API. Die Bildschirme kennen weder URL noch [OkHttp] noch JSON mehr. Dies ist das clientseitige Äquivalent der DAO-Schicht auf der Serverseite; im Architekturleitfaden von [Android] ein „Repository“:
| // =========================================================================
// ex24/RdvMedecins.kt - die Schicht für den API-Zugriff
// -------------------------------------------------------------------------
// Eine typisierte Funktion pro API-Route. Die Bildschirme kennen weder die
// URLs noch OkHttp noch das JSON-Format: Sie rufen Funktionen auf, die
// Kotlin-Objekte zurückgeben (Person, Schedule ...).
// Es ist das clientseitige Gegenstück zur serverseitigen DAO-Schicht: Ändert sich die
// API (eine URL, ein Feldname), wird nur diese Datei geändert. Im
// Android-Architekturleitfaden ist es ein "Repository".
// =========================================================================
package fr.stahe.examples.ex24
import android.net.Uri
import fr.stahe.examples.common.Schedule
import fr.stahe.examples.common.Api
import fr.stahe.examples.common.Person
import fr.stahe.examples.common.read
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put
class RdvMedecins(private val api: Api) {
suspend fun getDoctors(): List<Person> = api.get("/doctors").read()
suspend fun getClients(): List<Person> = api.get("/clients").read()
// Uri.Builder baut "doctorId=1&day=2030-01-15" und kodiert, was kodiert werden muss
suspend fun getSchedule(doctorId: Int, day: String): Schedule {
val params = Uri.Builder()
.appendQueryParameter("doctorId", "$doctorId")
.appendQueryParameter("day", day)
.build().encodedQuery
return api.get("/schedule?$params").read()
}
// clientId: optional; der Schlüssel wird nur dann ins JSON geschrieben, wenn er nicht null ist
suspend fun book(day: String, slotId: Int, clientId: Int? = null) {
api.post(
"/appointments",
buildJsonObject {
put("day", day)
put("slotId", slotId)
if (clientId != null) put("clientId", clientId)
},
)
}
suspend fun cancelAppointment(appointmentId: Int) {
api.delete("/appointments/$appointmentId")
}
}
|
- Zeile 22: [api.get("/doctors").read()]: Der erwartete Typ [List<Person>] wird aus dem Rückgabetyp der Funktion abgeleitet;
- Zeilen 28–31: [Uri.Builder] konstruiert die Parameterzeichenkette und kodiert dabei die nötigen Informationen.
Die dritte Schicht: der Zustand des Bildschirms und seine Aktionen in einem [ViewModel] (siehe Beispiel 20). Dieses Mal besteht der Zustand aus Eigenschaften von [Compose] ([mutableStateOf]), die leichter zu lesen sind als ein [StateFlow], wenn nur der Bildschirm sie beobachtet:
| // =========================================================================
// ex24/ScheduleModel.kt - das "View Model" des Bildschirms
// -------------------------------------------------------------------------
// Der Android-Architekturleitfaden empfiehlt die Trennung von:
// - der VIEW: den @Composable-Funktionen, die anzeigen und die Aktionen des
// Benutzers weitergeben;
// - dem VIEW MODEL (ViewModel): dem Zustand des Bildschirms (der gewählte Arzt,
// der Tag, der empfangene Terminkalender ...), den Aktionen (wählen, buchen, stornieren)
// und den Aufrufen der API-Zugriffsschicht.
// Die View enthält keine Logik mehr: Sie ist leicht lesbar; das View Model
// hat keine Komponenten: Es ist leicht testbar. Und es überlebt die
// Neuerstellung der Activity (Bildschirmdrehung).
// Die Aktionen starten ihre Coroutines in viewModelScope: Sie werden
// abgebrochen, wenn das ViewModel zerstört wird (Activity endgültig geschlossen).
//
// Es übernimmt auch, was wir nicht für jeden Bildschirm neu schreiben wollen:
// - einen CACHE: Der Terminkalender jedes bereits gelesenen (Arzt, Tag) wird behalten; die
// Rückkehr dorthin zeigt ihn sofort an, während er im Hintergrund erneut gelesen wird;
// - VERALTETE Antworten werden ignoriert: Ein neues Lesen BRICHT das
// vorherige ab (vgl. Beispiel 19).
// =========================================================================
package fr.stahe.examples.ex24
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import fr.stahe.examples.common.Schedule
import fr.stahe.examples.common.ScheduleSlot
import fr.stahe.examples.common.ApiError
import fr.stahe.examples.common.Person
import fr.stahe.examples.common.Role
import fr.stahe.examples.common.User
import kotlinx.coroutines.Job
import kotlinx.coroutines.launch
import java.time.LocalDate
// eine dem Benutzer angezeigte Meldung
data class Message(val success: Boolean, val text: String)
class ScheduleModel(private val rdvmedecins: RdvMedecins) : ViewModel() {
// ─── der Zustand: Compose-Zustände, nur hier änderbar ───
var user by mutableStateOf<User?>(null)
private set
var doctors by mutableStateOf(listOf<Person>())
private set
var clients by mutableStateOf(listOf<Person>())
private set
var doctorId by mutableStateOf<Int?>(null)
private set
var day by mutableStateOf(LocalDate.now().plusDays(1).toString()) // morgen, "2026-10-06"
private set
var clientId by mutableStateOf<Int?>(null)
private set
var schedule by mutableStateOf<Schedule?>(null)
private set
var loading by mutableStateOf(false)
private set
var message by mutableStateOf<Message?>(null)
private set
private val cache = mutableMapOf<String, Schedule>()
private var reading: Job? = null
// ─── berechnete Werte ───
val loggedIn get() = user != null
val isManager get() = user.let { it != null && it.role != Role.USER }
// ─── die Aktionen ───
fun changeUser(u: User?) {
user = u
doctors = emptyList()
clients = emptyList()
schedule = null
doctorId = null
cache.clear() // die Rechte haben sich geändert: Alles wird vergessen
if (u == null) return
viewModelScope.launch {
try {
doctors = rdvmedecins.getDoctors()
if (isManager) clients = rdvmedecins.getClients() // ein USER würde 403 erhalten
} catch (e: ApiError) {
message = Message(false, e.toString())
}
}
}
fun chooseDoctor(id: Int?) {
doctorId = id
message = null
readSchedule()
}
fun chooseDay(d: LocalDate) {
day = d.toString()
message = null
readSchedule()
}
fun chooseClient(id: Int?) {
clientId = id
}
fun book(s: ScheduleSlot) = act("Slot ${s.timeRange} booked.") {
rdvmedecins.book(day, s.id, if (isManager) clientId else null)
}
fun cancel(s: ScheduleSlot) = act("Appointment at ${s.timeRange} cancelled.") { rdvmedecins.cancelAppointment(s.appointmentId!!) }
// eine Aktion, dann IMMER ein erneutes Lesen des Terminkalenders: Der SERVER ist die Referenz
private fun act(success: String, action: suspend () -> Unit) {
viewModelScope.launch {
message = try {
action()
Message(true, success)
} catch (e: ApiError) {
Message(false, e.toString())
}
readSchedule()
}
}
private fun readSchedule() {
val id = doctorId ?: return
val key = "$id/$day"
// ein älteres Lesen läuft noch: Es wird abgebrochen
reading?.cancel()
// zuerst der Cache (oder nichts), dann das Lesen
schedule = cache[key]
loading = true
reading = viewModelScope.launch {
try {
val read = rdvmedecins.getSchedule(id, day)
cache[key] = read
schedule = read
} catch (e: ApiError) {
schedule = null
message = Message(false, e.toString())
}
loading = false
}
}
}
|
- Zeilen 44–62: der Zustand, der nur hier geändert werden kann;
- Zeilen 70–83: ein Benutzerwechsel – alles wird geleert (die Berechtigungen haben sich geändert) und dann neu geladen. [viewModelScope.launch]: eine Coroutine, die so lange lebt wie das [ViewModel];
- Zeilen 111–119: Jede Aktion endet IMMER damit, den Terminkalender neu zu lesen: Der SERVER hat die maßgebliche Version;
- Zeilen 123–140: das Lesen des Terminkalenders: Jeder ältere, noch laufende Lesevorgang wird abgebrochen; der Cache liefert sofort eine Antwort, die dann durch die Antwort des Servers ersetzt wird.
Die View, die das Modell einfach nur anzeigt. Die Anmeldung übernimmt eine wiederverwendbare Komponente, die Leiste [common/LoginBar.kt] (das Formular aus Beispiel 23, mit [Api] neu geschrieben):
| // =========================================================================
// common/LoginBar.kt - Anmeldung / Abmeldung in einer Leiste
// -------------------------------------------------------------------------
// Das Formular aus Beispiel 23, auf eine Leiste reduziert und mit Api.kt neu geschrieben.
// Die Komponente ruft onUserChange mit dem angemeldeten Benutzer (oder
// null) bei jeder Änderung auf - auch beim Start, nach der
// Abfrage von GET /api/auth/me. Verwendet von den Beispielen 24 und 25.
// =========================================================================
package fr.stahe.examples.common
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ExitToApp
import androidx.compose.material.icons.filled.Check
import androidx.compose.material.icons.filled.Person
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.unit.dp
import kotlinx.coroutines.launch
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put
@Composable
fun LoginBar(api: Api, onUserChange: (User?) -> Unit) {
var user by remember { mutableStateOf<User?>(null) }
var captcha by remember { mutableStateOf<Captcha?>(null) }
var login by rememberSaveable { mutableStateOf("admin") }
var password by rememberSaveable { mutableStateOf("") }
var captchaAnswer by rememberSaveable { mutableStateOf("") }
var error by remember { mutableStateOf<String?>(null) }
val scope = rememberCoroutineScope()
fun changeUser(u: User?) {
user = u
onUserChange(u)
}
suspend fun newCaptcha() {
captcha = api.get("/captcha").read<Captcha>()
captchaAnswer = ""
}
// beim Start: sind wir bereits angemeldet?
LaunchedEffect(Unit) {
try {
changeUser(api.get("/auth/me").read<User>())
} catch (e: ApiError) {
changeUser(null) // 401: niemand ist angemeldet
try {
newCaptcha()
} catch (e: ApiError) {
error = "Is the JSON server running (${Config.serverUrl})?"
}
}
}
suspend fun logIn() {
error = null
try {
val body = buildJsonObject {
put("login", login.trim())
put("password", password)
put("captchaId", captcha?.id)
put("captcha", captchaAnswer)
}
val u = api.post("/auth/login", body).read<User>()
password = ""
changeUser(u)
} catch (e: ApiError) {
error = e.toString() // "401 LOGIN.ERROR"
runCatching { newCaptcha() }
}
}
suspend fun logOut() {
runCatching { api.post("/auth/logout") }
changeUser(null)
runCatching { newCaptcha() }
}
Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFECEFF1))) {
val u = user
if (u != null) {
Row(Modifier.padding(8.dp), verticalAlignment = Alignment.CenterVertically) {
Icon(Icons.Default.Person, contentDescription = null)
Spacer(Modifier.width(8.dp))
Text("${u.name} (${u.role})", Modifier.weight(1f))
TextButton(onClick = { scope.launch { logOut() } }) {
Icon(Icons.AutoMirrored.Filled.ExitToApp, contentDescription = null)
Text("Log out")
}
}
} else {
Column(Modifier.padding(8.dp)) {
Row {
OutlinedTextField(login, { login = it }, label = { Text("login") }, singleLine = true, modifier = Modifier.weight(1f))
Spacer(Modifier.width(8.dp))
OutlinedTextField(
password,
{ password = it },
label = { Text("password") },
singleLine = true,
visualTransformation = PasswordVisualTransformation(),
modifier = Modifier.weight(1f),
)
}
Row(verticalAlignment = Alignment.CenterVertically) {
// das SVG-Bild des CAPTCHAs, von UNSEREM Server erzeugt (vgl. Beispiel 22)
captcha?.let { SvgImage(it.svg, height = 40.dp) }
Spacer(Modifier.width(8.dp))
OutlinedTextField(captchaAnswer, { captchaAnswer = it }, label = { Text("captcha") }, singleLine = true, modifier = Modifier.weight(1f))
IconButton(onClick = { scope.launch { logIn() } }) {
Icon(Icons.Default.Check, contentDescription = "Log in")
}
}
error?.let { Text(it, color = Color.Red) }
}
}
}
}
// =========================================================================
// ex24/Ex24Activity.kt - ein Terminkalender mit der API-Zugriffsschicht
// -------------------------------------------------------------------------
// Anmelden (obere Leiste), einen Arzt und einen Tag wählen:
// Der Terminkalender wird angezeigt. ADMIN und DOCTOR können für einen Patienten buchen und
// stornieren; ein Patient (martin ...) bucht für sich selbst. Jede Aktion
// endet mit einem erneuten Lesen des Terminkalenders.
// Drei Schichten, von unten nach oben:
// Api (common/Api.kt) die HTTP-Anfragen, die Fehler;
// RdvMedecins (RdvMedecins.kt) eine typisierte Funktion pro API-Route;
// ScheduleModel (ScheduleModel.kt) der Zustand und die Aktionen des Bildschirms;
// und die View weiter unten, die nur das Modell anzeigt.
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)
package fr.stahe.examples.ex24
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.AddCircle
import androidx.compose.material.icons.filled.Close
import androidx.compose.material.icons.filled.DateRange
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerDialog
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.LinearProgressIndicator
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.SuggestionChip
import androidx.compose.material3.SuggestionChipDefaults
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.rememberDatePickerState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.lifecycle.viewmodel.compose.viewModel
import fr.stahe.examples.ExamplesApplication
import fr.stahe.examples.common.Api
import fr.stahe.examples.common.LoginBar
import fr.stahe.examples.common.ScheduleSlot
import fr.stahe.examples.common.DropdownList
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import java.time.Instant
import java.time.LocalDate
import java.time.ZoneOffset
class Ex24Activity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
val api = (application as ExamplesApplication).api
setContent { ExamplesTheme { SchedulePage(api) } }
}
}
@Composable
fun SchedulePage(api: Api) {
// viewModel { ... }: das Modell der Activity, das von diesem Block bei der
// ersten Anforderung erzeugt wird (es braucht einen Parameter: die API-Zugriffsschicht)
val model = viewModel { ScheduleModel(RdvMedecins(api)) }
var calendarOpen by remember { mutableStateOf(false) }
ExamplePage("Example 24 - an API access layer") {
LoginBar(api, onUserChange = { model.changeUser(it) })
if (model.loggedIn) {
DropdownList(
label = "Doctor",
value = model.doctorId,
choices = listOf<Int?>(null) + model.doctors.map { it.id },
text = { id -> model.doctors.find { it.id == id }?.fullName ?: "-- choose a doctor --" },
onChange = { model.chooseDoctor(it) },
modifier = Modifier.fillMaxWidth(),
)
Row(verticalAlignment = Alignment.CenterVertically) {
Text("Day: ${model.day}")
IconButton(onClick = { calendarOpen = true }) { Icon(Icons.Default.DateRange, contentDescription = "choose the day") }
}
if (model.isManager) {
DropdownList(
label = "Patient",
value = model.clientId,
choices = listOf<Int?>(null) + model.clients.map { it.id },
text = { id -> model.clients.find { it.id == id }?.fullName ?: "-- patient to book for --" },
onChange = { model.chooseClient(it) },
modifier = Modifier.fillMaxWidth(),
)
}
model.message?.let { m ->
Card(colors = CardDefaults.cardColors(containerColor = if (m.success) Color(0xFFE8F5E9) else Color(0xFFFFEBEE))) {
Text(m.text, Modifier.padding(10.dp))
}
}
if (model.loading) LinearProgressIndicator(Modifier.fillMaxWidth())
model.schedule?.let { schedule ->
// info: der vom Server gesendete Schlüssel, wenn ein Patient bereits einen bevorstehenden Termin hat
schedule.info?.let { Text(it, color = Color(0xFF1976D2)) }
Text(
"Schedule of ${schedule.day} - ${schedule.doctor.fullName}",
style = MaterialTheme.typography.titleSmall,
modifier = Modifier.padding(vertical = 8.dp),
)
for (s in schedule.slots) {
SlotRow(s, onBook = { model.book(s) }, onCancel = { model.cancel(s) })
}
}
}
}
if (calendarOpen) {
val state = rememberDatePickerState(
initialSelectedDateMillis = LocalDate.parse(model.day).atStartOfDay(ZoneOffset.UTC).toInstant().toEpochMilli(),
)
DatePickerDialog(
onDismissRequest = { calendarOpen = false },
confirmButton = {
TextButton(onClick = {
state.selectedDateMillis?.let { model.chooseDay(Instant.ofEpochMilli(it).atZone(ZoneOffset.UTC).toLocalDate()) }
calendarOpen = false
}) { Text("OK") }
},
) { DatePicker(state = state) }
}
}
// eine Zeile des Terminkalenders: der Zeitraum, der Belegende, die erlaubten Buttons
@Composable
fun SlotRow(s: ScheduleSlot, onBook: () -> Unit, onCancel: () -> Unit) {
ListItem(
leadingContent = { Text(s.timeRange, Modifier.width(96.dp)) },
headlineContent = {
if (s.free) {
SuggestionChip(
onClick = {},
label = { Text("Free") },
colors = SuggestionChipDefaults.suggestionChipColors(containerColor = Color(0xFFC8E6C9)),
)
} else {
SuggestionChip(
onClick = {},
label = { Text(s.patient?.toString() ?: "Booked") },
colors = SuggestionChipDefaults.suggestionChipColors(
containerColor = if (s.mine) Color(0xFFC5CAE9) else Color(0xFFE0E0E0),
),
)
}
},
// die Buttons folgen den vom Server berechneten Rechten
trailingContent = {
when {
s.bookable -> IconButton(onClick = onBook) {
Icon(Icons.Default.AddCircle, contentDescription = "Book", tint = Color(0xFF2E7D32))
}
s.appointmentId != null -> IconButton(onClick = onCancel) {
Icon(Icons.Default.Close, contentDescription = "Cancel", tint = Color.Red)
}
}
},
)
}
|
- Zeile 79: [viewModel [ ... ]]: das Modell, das von diesem Block bei der ersten Anforderung erzeugt wird (es benötigt einen Parameter);
- Zeilen 86–90: die Liste der Ärzte: Ihre Optionen sind [Int?] und [null] für „-- choose a doctor --“;
- Zeilen 169–172: Die Schaltflächen in jeder Zeile entsprechen den vom SERVER BERECHNETEN Berechtigungen ([bookable], [appointmentId]).



Links und in der Mitte reserviert ADMIN das erste Zeitfenster für Jean MARTIN; rechts, angemeldet als [martin]: Der Server hat [bookable] für alle Zeitfenster auf [false] gesetzt, weil dieser Patient bereits einen bevorstehenden Termin hat, wie der Schlüssel [SCHEDULE.ALREADY_BOOKED_INFO] anzeigt. Dieser rohe Schlüssel ist wenig aussagekräftig: Beispiel 25 übersetzt die Schlüssel des Servers.
9.4. Beispiel 25: Vom Server zurückgegebene Fehler
Der Server validiert ALLES, was er empfängt (siehe Beispiel 07), und antwortet im Fall einer Ablehnung mit einem JSON-Fehler, der den Schlüssel der allgemeinen Meldung und den Fehlerschlüssel JEDES Feldes enthält:
| 400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
409 { key: 'ERRORS.CONCURRENT_UPDATE' }
|
Es gibt viele solcher Schlüssel. Die Clients des Servers – [Vue.js], [Angular], [React], und [Flutter] – übersetzen sie mit JSON-Wörterbüchern, eines pro Sprache. Statt diese Hunderte von Texten in [strings.xml]-Dateien zu kopieren (und die Tabelle Schlüssel → Ressource aus Beispiel 21 zu schreiben), verwenden wir diese Wörterbücher unverändert weiter. Sie liegen im Ordner [assets/] der Anwendung: Dateien, die mit der Anwendung ausgeliefert und über ihren Pfad gelesen werden ([assets/i18n/ex25_fr.json], [ex25_en.json]):
| // =========================================================================
// ex25/Dictionary.kt - die mit den anderen Clients geteilten Wörterbücher
// -------------------------------------------------------------------------
// Der RdvMedecins-Server liefert nur SCHLÜSSEL ("ERRORS.LOGIN_TAKEN"),
// und zwar viele: die Fehlermeldungen jedes Feldes, jeder
// Route ... Die Web-Clients (Vue.js, Angular, React) und Flutter dieses
// Servers übersetzen sie mit JSON-WÖRTERBÜCHERN, eines pro Sprache, in denen
// jeder Text seinen Schlüssel hat:
// { "ERRORS": { "LOGIN_TAKEN": "This login is already used..." } }
// Statt diese Hunderte von Texten in strings.xml-Dateien zu kopieren (und
// die Tabelle Schlüssel -> Ressource aus Beispiel 21 zu schreiben), verwenden wir
// diese Wörterbücher unverändert weiter. Sie liegen im Ordner assets/ der
// Anwendung: mit ihr ausgelieferte Dateien, die über ihren Pfad gelesen werden.
// - t("FORM.ADDED", mapOf("name" to "Marie DUPONT")): der Text der
// aktuellen Sprache, in dem die Parameter {{name}} ersetzt werden;
// - ein unbekannter Schlüssel wird unverändert angezeigt: So sehen wir, was fehlt.
// Die Sprache bleibt die der ANWENDUNG (Beispiel 21): Das Wörterbuch
// wird entsprechend gewählt.
// =========================================================================
package fr.stahe.examples.ex25
import android.content.Context
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.platform.LocalConfiguration
import androidx.compose.ui.platform.LocalContext
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
class Dictionary(context: Context, file: String) {
// der Inhalt der JSON-Datei, einmal für alle Mal gelesen
private val root: JsonObject = context.assets.open(file).bufferedReader().use { reader ->
Json.parseToJsonElement(reader.readText()) as JsonObject
}
// "FORM.ADDED" -> root["FORM"]["ADDED"]; null, wenn nicht vorhanden
private fun find(key: String): String? {
var node: JsonElement? = root
for (part in key.split('.')) {
node = (node as? JsonObject)?.get(part)
}
return (node as? JsonPrimitive)?.takeIf { it.isString }?.content
}
fun t(key: String, params: Map<String, String> = emptyMap()): String {
val text = find(key) ?: return key
// {{name}} -> der Wert des Parameters name (oder {{name}}, wenn er nicht angegeben ist)
return Regex("\\{\\{(\\w+)\\}\\}").replace(text) { m -> params[m.groupValues[1]] ?: m.value }
}
}
// das Wörterbuch der aktuellen Sprache: assets/i18n/<prefix>_<language>.json
@Composable
fun rememberDictionary(prefix: String): Dictionary {
val context = LocalContext.current
val language = LocalConfiguration.current.locales[0].language.let { if (it == "fr") "fr" else "en" }
// nur neu gelesen, wenn sich die Sprache ändert
return remember(language) { Dictionary(context, "i18n/${prefix}_$language.json") }
}
|
- Zeilen 34–35: die JSON-Datei, einmalig gelesen ([context.assets.open]);
- Zeilen 39–48: ["FORM.ADDED"] → [root["FORM"]["ADDED"]]; ein unbekannter Schlüssel wird unverändert angezeigt: So sieht man, was fehlt;
- Zeile 50: Die Parameter [{{name}}] werden durch einen regulären Ausdruck ersetzt;
- Zeilen 56–60: das Wörterbuch der Sprache der ANWENDUNG (Beispiel 21), nur bei einer Änderung neu gelesen.
Das Modell des Bildschirms: Dieses Formular führt auf dem Telefon keine Validierung durch; alles wird an den Server gesendet.
| // =========================================================================
// ex25/ClientsModel.kt - der Zustand des Client-Bildschirms
// -------------------------------------------------------------------------
// Dieses Formular führt ABSICHTLICH keine Validierung auf dem Smartphone durch:
// Alles wird an den Server gesendet, der im Fall einer Ablehnung mit
// einem JSON-Fehler antwortet (von common/Api.kt in einen ApiError umgewandelt):
//
// 400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
// 409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
// 409 { key: 'ERRORS.CONCURRENT_UPDATE' } (optimistisches Sperren)
//
// Der Fehler JEDES Feldes (ApiError.fields) wird im Zustand gespeichert und
// unter dem Feld angezeigt; seine Meldung ist der vom Server gesendete SCHLÜSSEL,
// den der Bildschirm übersetzt. Die Änderung eines Feldes löscht dessen Fehler.
// Der Zustand liegt in einem ViewModel: Ein Sprachwechsel erstellt die Activity NEU
// (vgl. Beispiel 21), und die laufende Eingabe darf nicht verloren gehen.
// =========================================================================
package fr.stahe.examples.ex25
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.lifecycle.ViewModel
import fr.stahe.examples.common.Api
import fr.stahe.examples.common.ApiError
import fr.stahe.examples.common.Person
import fr.stahe.examples.common.Role
import fr.stahe.examples.common.User
import fr.stahe.examples.common.read
import fr.stahe.examples.ex23.Command
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put
// eine zu übersetzende Meldung: ein Schlüssel und seine Parameter
data class KeyMessage(val key: String, val params: Map<String, String> = emptyMap())
class ClientsModel(private val api: Api) : ViewModel() {
var user by mutableStateOf<User?>(null)
private set
var clients by mutableStateOf(listOf<Person>())
private set
// das Formular: editedId == null -> Erstellung, sonst Aktualisierung
var editedId by mutableStateOf<Int?>(null)
private set
private var version = 0
// die eingegebenen Werte, nach Feldnamen (die vom Server erwarteten Namen)
var input by mutableStateOf(empty)
private set
// der Fehler jedes Feldes (ein Übersetzungsschlüssel), vom Server zurückgegeben
var errors by mutableStateOf(mapOf<String, String>())
private set
// die allgemeine Meldung des letzten Fehlers und die eines Erfolgs
var pageError by mutableStateOf<ApiError?>(null)
private set
var success by mutableStateOf<KeyMessage?>(null)
private set
// Senden an den Server: ein Command (Beispiel 23), das angibt, ob es läuft
val sending = Command()
val isAdmin get() = user?.role == Role.ADMIN
suspend fun onUserChange(u: User?) {
user = u
clients = emptyList()
if (u?.role == Role.ADMIN) reload()
}
private suspend fun reload() {
clients = try {
api.get("/clients").read()
} catch (e: ApiError) {
emptyList()
}
}
private fun clearMessages() {
errors = emptyMap()
pageError = null
success = null
}
// ein geändertes Feld: Sein Wert ändert sich, sein Fehler verschwindet
fun change(field: String, value: String) {
input = input + (field to value)
errors = errors - field
}
fun newForm() {
editedId = null
version = 0
input = empty
clearMessages()
}
fun edit(c: Person) {
editedId = c.id
// die zusammen mit dem Datensatz gelesene VERSION geht mit der Aktualisierung zurück: Hat
// jemand den Datensatz zwischenzeitlich geändert, antwortet der Server mit 409
// CONCURRENT_UPDATE
version = c.version
input = mapOf("title" to c.title, "firstName" to c.firstName, "lastName" to c.lastName, "login" to (c.login ?: ""), "password" to "")
clearMessages()
}
suspend fun save() {
clearMessages()
val body = buildJsonObject {
for ((field, value) in input) put(field, value)
put("version", version)
}
try {
val id = editedId
val client: Person = (if (id == null) api.post("/clients", body) else api.put("/clients/$id", body)).read()
val key = if (id == null) "FORM.ADDED" else "FORM.UPDATED"
newForm() // Formular geleert, Meldungen gelöscht ...
// ... außer dieser
success = KeyMessage(key, mapOf("name" to "${client.firstName} ${client.lastName}", "login" to (client.login ?: "")))
reload()
} catch (e: ApiError) {
pageError = e // die allgemeine Meldung
errors = e.fields // der Fehler jedes Feldes
}
}
suspend fun remove(c: Person) {
clearMessages()
try {
api.delete("/clients/${c.id}")
success = KeyMessage("FORM.DELETED", mapOf("name" to "${c.firstName} ${c.lastName}"))
} catch (e: ApiError) {
pageError = e
}
reload()
}
companion object {
val empty = mapOf("title" to "Mr", "firstName" to "", "lastName" to "", "login" to "", "password" to "")
}
}
|
- Zeilen 49–53: die Eingabe nach Feldname (die vom Server erwarteten Namen) und der Fehler zu jedem Feld (eine Übersetzung);
- Zeilen 88–90: Das Ändern eines Feldes löscht seinen Fehler;
- Zeile 105: Die aus dem Datensatz gelesene VERSION wird mit der Änderung zurückgesendet; hat jemand den Datensatz in der Zwischenzeit geändert, antwortet der Server mit einem 409 [CONCURRENT_UPDATE] (optimistisches Sperren);
- Zeilen 110–126: das Speichern: Im Fehlerfall werden die allgemeine Meldung und der Fehler zu jedem Feld ([e.fields]) im Zustand abgelegt.
Der Bildschirm:
| // =========================================================================
// ex25/Ex25Activity.kt - Anzeige der Fehler des SERVERS
// -------------------------------------------------------------------------
// Die Verwaltung der Clients (Admin-Konto), vgl. ClientsModel.kt. Der Bildschirm
// zeigt unter jedem Feld den Fehler an, den der Server ihm zugeordnet hat,
// übersetzt über die Wörterbücher (Dictionary.kt), und die allgemeine Meldung
// am Ende des Formulars.
// Zum Ausprobieren: einen leeren Namen, einen Titel "Dr", einen Namensvetter (Alice DURAND), ein
// bereits vergebenes Login (martin), denselben Datensatz auf zwei Geräten geändert ...
// =========================================================================
package fr.stahe.examples.ex25
import android.os.Bundle
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.appcompat.app.AppCompatActivity
import androidx.appcompat.app.AppCompatDelegate
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Edit
import androidx.compose.material.icons.filled.MoreVert
import androidx.compose.material.icons.outlined.Delete
import androidx.compose.material3.Button
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.DropdownMenu
import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.text.input.VisualTransformation
import androidx.compose.ui.text.withStyle
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import androidx.core.os.LocaleListCompat
import androidx.lifecycle.viewmodel.compose.viewModel
import fr.stahe.examples.ExamplesApplication
import fr.stahe.examples.common.Api
import fr.stahe.examples.common.LoginBar
import fr.stahe.examples.common.DropdownList
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import fr.stahe.examples.ex16.ConfirmDialog
import fr.stahe.examples.ex16.rememberConfirmation
import kotlinx.coroutines.launch
class Ex25Activity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
val api = (application as ExamplesApplication).api
setContent { ExamplesTheme { ClientsPage(api) } }
}
}
@Composable
fun ClientsPage(api: Api) {
val model = viewModel { ClientsModel(api) }
val dict = rememberDictionary("ex25")
// eine Abkürzung: t("KEY") ruft dict.t("KEY") auf
fun t(key: String, params: Map<String, String> = emptyMap()) = dict.t(key, params)
val confirmation = rememberConfirmation()
val scope = rememberCoroutineScope()
var languageMenu by remember { mutableStateOf(false) }
// ein Eingabefeld mit seinem Fehler (ein Server-Schlüssel), übersetzt
@Composable
fun Field(field: String, secret: Boolean = false) {
val error = model.errors[field]
OutlinedTextField(
value = model.input[field].orEmpty(),
onValueChange = { model.change(field, it) },
label = { Text(t("FORM.${field.uppercase()}")) },
singleLine = true,
isError = error != null,
supportingText = error?.let { e -> { Text(t(e)) } },
visualTransformation = if (secret) PasswordVisualTransformation() else VisualTransformation.None,
modifier = Modifier.fillMaxWidth(),
)
}
ExamplePage(
title = t("FORM.PAGE_TITLE"),
// die Sprache: ein Menü
actions = {
IconButton(onClick = { languageMenu = true }) { Icon(Icons.Default.MoreVert, contentDescription = "language") }
DropdownMenu(expanded = languageMenu, onDismissRequest = { languageMenu = false }) {
for (l in listOf("fr", "en")) {
DropdownMenuItem(text = { Text(l.uppercase()) }, onClick = {
languageMenu = false
AppCompatDelegate.setApplicationLocales(LocaleListCompat.forLanguageTags(l))
})
}
}
},
) {
LoginBar(api, onUserChange = { u -> scope.launch { model.onUserChange(u) } })
if (model.user != null && !model.isAdmin) {
Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFFFF8E1))) {
Text(t("FORM.ADMIN_ONLY"), Modifier.padding(12.dp))
}
}
if (model.isAdmin) {
for (c in model.clients) {
ListItem(
headlineContent = { Text(c.fullName) },
supportingContent = { Text(c.login ?: "") },
trailingContent = {
Row {
IconButton(onClick = { model.edit(c) }) { Icon(Icons.Default.Edit, contentDescription = t("FORM.EDIT")) }
IconButton(onClick = {
scope.launch {
val name = "${c.firstName} ${c.lastName}"
if (confirmation.confirm(t("FORM.DELETE_CONFIRM", mapOf("name" to name)))) model.remove(c)
}
}) {
Icon(Icons.Outlined.Delete, contentDescription = t("FORM.DELETE"), tint = Color.Red)
}
}
},
)
}
Card(Modifier.fillMaxWidth()) {
Column(Modifier.padding(12.dp)) {
Text(t(if (model.editedId == null) "FORM.TITLE_ADD" else "FORM.TITLE_EDIT"), style = MaterialTheme.typography.titleMedium)
// ein Titel "Dr", den der Server ablehnen wird: um ERRORS.INVALID_TITLE zu sehen
DropdownList(
label = t("FORM.TITLE"),
value = model.input["title"].orEmpty(),
choices = listOf("Mr", "Mme", "Melle", "Dr"),
onChange = { model.change("title", it) },
error = model.errors["title"]?.let { t(it) },
modifier = Modifier.width(200.dp),
)
Field("firstName")
Field("lastName")
Field("login")
Field("password", secret = true)
Row(Modifier.padding(top = 12.dp)) {
Button(onClick = { scope.launch { model.sending.execute { model.save() } } }, enabled = !model.sending.inProgress) {
Text(t("FORM.SAVE"))
}
Spacer(Modifier.width(8.dp))
OutlinedButton(onClick = { model.newForm() }) { Text(t("FORM.CANCEL")) }
}
model.success?.let { s ->
Text(t(s.key, s.params), color = Color(0xFF2E7D32), modifier = Modifier.padding(top = 12.dp))
}
// die allgemeine Meldung und der HTTP-Status zum Verständnis
model.pageError?.let { e ->
Text(
buildAnnotatedString {
withStyle(SpanStyle(color = Color.Red)) { append(t(e.key, e.params)) }
withStyle(SpanStyle(color = Color.Gray, fontSize = 12.sp)) { append(" ($e)") }
},
modifier = Modifier.padding(top = 12.dp),
)
}
}
}
}
}
ConfirmDialog(confirmation)
}
|
- Zeilen 79–81: das Wörterbuch und eine Abkürzung [t(...)];
- Zeilen 88–96: ein Feld und sein Fehler, ein Server-Schlüssel, übersetzt;
- Zeilen 106–111: die Sprache in einem Menü der oberen Leiste ([DropdownMenu]);
- Zeilen 170–174: die allgemeine Meldung und der HTTP-Status zur Information.



Links ein Datensatz mit leerem Vor- und Nachnamen: Fehler 400; in der Mitte ein Namensvetter von Alice DURAND: Fehler 409; rechts derselbe Fehler auf Französisch: Die aktuelle Eingabe hat die Neuerstellung der Activity dank [ViewModel] überstanden.