From d0c7ca23b0a7179836b1b77abd7295b52be2c32b Mon Sep 17 00:00:00 2001 From: Santeri Korri Date: Tue, 14 Jan 2025 09:12:14 +0200 Subject: [PATCH] OY-5034 Parannettu kirjaston dokumentaatiota --- kirjasto/README.md | 39 +++++++++++++++++++++++++++++++++++---- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/kirjasto/README.md b/kirjasto/README.md index cc35d507..bd36b797 100644 --- a/kirjasto/README.md +++ b/kirjasto/README.md @@ -1,6 +1,8 @@ ## Viestinvälityspalvelu kirjasto -Kirjaston avulla asiakasjärjestelmät voivat käyttää viestinvälityspalvelua java-rajapinnan läpi. +Kirjaston avulla asiakasjärjestelmät voivat käyttää viestinvälityspalvelua java-rajapinnan läpi. Käyttöön tarvitaan +tämä riippuvuus, sekä käyttäjätunnus jolla on tarvittavat oikeudet viestien lähettämiseksi. Kirjaston transitiiviset +riippuvuudet on pyritty minimoimaan. ### Käyttö @@ -16,9 +18,13 @@ Client instanssi luodaan builderilla, esim: .build() ``` -Tämän jälkeen client-instanssilla voi luoda pyyntöjä jotka luovat liitteitä, lähetyksiä, ja viestejä, sekä tarkastelevat näiden tilaa, Esim. seuraavasti: +Tämän jälkeen client-instanssilla voi luoda pyyntöjä jotka luovat liitteitä, lähetyksiä, ja viestejä, sekä tarkastella +näiden tilaa, Esim. seuraavasti: -Voidaan joko luoda ensin lähetys ja liittää samaan lähetykseen useita viestejä +Voidaan joko luoda ensin lähetys ja liittää samaan lähetykseen useita viestejä. Lähetysten käyttö on tarpeellista esim. +tilanteissa joissa a) haluataan tarkastella useita vastaanottajakohtaisesti kustomoituja viestejä kokonaisuutena, tai +b) viestin kokonaisvastaanottajamäärä ylittää yksittäisen viestin maksimivastaanottajamäärän (ks. lähetysrajapinnan +Viesti-luokka), jolloin viesti täytyy palastella useammaksi viestiksi. ``` LuolahetysResponse luoLahetysResponse = viestinvalitysClient.luoLahetys( @@ -33,7 +39,10 @@ ViestinvalitysBuilder.lahetysBuilder() ViestinvalitysBuilder.viestiBuilder() .withOtsikko("viestin otsikko") -.withHtmlSisalto("

Otsikko

Viestin sisältö

Ystävällisin terveisin
Opintopolku

") +.withHtmlSisalto("

Otsikko

Viestin sisältö

Ystävällisin terveisin
Opintopolku

") .withKielet("fi") .withVastaanottajat(ViestinvalitysBuilder.vastaanottajatBuilder() .withVastaanottaja(Optional.empty(), "test@example.com") @@ -64,6 +73,28 @@ Tai luoda viestejä erillisinä lähetyksinä .withLahettaja(Optional.empty(), "noreply@opintopolku.fi") .build()) ``` + +On suositeltavaa käyttää builder-luokkia lähetysten, viestien jne. luomiseen. Tällöin kaikki pakolliset kentät tulevat +kaikissa tilanteissa täytettyä. + +### Validointi + +Rajapinta pyrkii validoimaan kaikkien pyyntöjen kaikki kentät, ja kaikille kentille on pyritty asettamaan esim. +maksimipituus. Erityisesti tulee huomata että yksittäisellä viestillä on maksimimäärä vastaanottajia, ja tätä +suuremmalle vastaanottajajoukolle suunnatut viestit tulee palastella useammaksi yksittäiseksi viestiksi. Yksittäisten +kenttien rajoitteet on pyritty kuvaamaan kattavasti Swagger-kuvauksessa, joka puolestaan pyrkii perustumaan suoraan +lähdekoodissa olevien vakioihin ylläpidettävyyden varmistamiseksi. + +### Idempotency-avain -toiminnallisuus + +Rajapinta sisältää toiminnallisuuden jonka avulla voidaan varmistua siitä ettei samaa viestiä lähetetä toistuvasti +viestinvälityspalvelun tai asiakasjärjestelmän virheen seurauksena. Viestin mukaan voidaan liittää uniikki +idempotencyKey-avain, joka tallennetaan viestinvälityspalveluun. Mikäli sama asiakasjärjestelmä (ts. cas-identiteetti) +yrittää lähettää uutta viestiä samalla avaimella, palautetaan aikaisemman viestin tiedot. + +HUOMAA että jos lähetettävä viesti on palasteltu useammaksi viestiksi koska vastaanottajien kokonaismäärä ylittää +yksittäisen viestin maksimivastaanottajamäärä, pitää kaikille viesteille luonnollisesti olla oma idempotency-avain! + ### Kirjaston päivitys Jos kirjastoa on tarve muuttaa tai päivittää, nosta projektin parent-pomissa oleva revision