Kotlin

Cette page est traduite de l'anglais. En cas de différence, la page anglaise fait foi. Lire la page en anglais

La bibliothèque Kotlin est com.getlingara:lingara-kotlin sur Maven Central. Elle s’exécute sur la JVM, nécessite Java 17 et Kotlin 2.2 ou version ultérieure, et utilise kotlinx.coroutines et kotlinx.serialization.

À quoi elle ressemble

Chaque appel est une fonction suspend. Annulez la coroutine pour annuler l’appel, ou utilisez withTimeout pour fixer une échéance ; vous voyez votre propre CancellationException, jamais une exception enveloppée.
Un flux est un EventStream, un Flow que vous collectez une seule fois. Collectez-le à l’intérieur de use, pour qu’il se ferme quand vous avez terminé. Les événements sont des data classes sous une interface scellée, identifiées avec when.
Les erreurs étendent la classe scellée LingaraException, si bien qu’un when sur elles est exhaustif. retryAfter est une Duration, ou null quand l’API n’a indiqué aucun délai.
Créez un client avec le builder LingaraClient { }. Il utilise le HttpClient du JDK, que vous pouvez remplacer par le vôtre.

Les exemples ci-dessous ajoutent la dépendance, créent un client, diffusent une liste de vocabulaire et gèrent une erreur.

Kotlin

implementation("com.getlingara:lingara-kotlin:0.1.0-alpha.6")

Kotlin

import com.getlingara.kotlin.LingaraClient

val client =
    LingaraClient {
        clientCredentials(System.getenv("LINGARA_CLIENT_ID"), System.getenv("LINGARA_CLIENT_SECRET"))
    }

Kotlin

import com.getlingara.kotlin.LingaraClient
import com.getlingara.kotlin.model.GenerateVocabularyEvent
import com.getlingara.kotlin.model.VocabRequest

val request = VocabRequest(level = 2, sourceLang = "en", targetLang = "zh", count = 8)
// The request is sent here; collect the stream once, inside use {}.
client.generateVocabulary(request).use { stream ->
    stream.collect { event ->
        when (event) {
            is GenerateVocabularyEvent.Item -> println("${event.data.word} ${event.data.translation}")
            is GenerateVocabularyEvent.Started -> Unit
        }
    }
}

Kotlin

try {
    client.getUsage()
} catch (e: LingaraException) {
    when (e) {
        // A refusal from the API: status, code (stable) and message (localised).
        is ApiException -> println("${e.status} ${e.code} ${e.message}; retry after ${e.retryAfter}")
        // The token endpoint refused the credentials or the scopes.
        is OAuthException -> println("${e.status} ${e.error} ${e.description}")
        is MaintenanceException -> println("under maintenance; retry after ${e.retryAfter}")
        // No usable answer: CONNECT, TLS, RESET, TIMEOUT, and so on.
        is TransportException -> println("transport: ${e.kind}")
    }
}
// A cancelled call throws the caller's own CancellationException instead.

Kotlin

À quoi elle ressemble

Ce que cette page encapsule