-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
OY-5034 Parannettu kirjaston dokumentaatiota
- Loading branch information
Showing
1 changed file
with
35 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"><html><head><meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\" /><title></title></head><body style=\"margin: 0; font-family: 'Open Sans', Arial, sans-serif;\"><H1>Otsikko</h1><p>Viestin sisältö</p><p>Ystävällisin terveisin<br/>Opintopolku</p></body></html>") | ||
| .withHtmlSisalto("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" | ||
| \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"><html><head><meta http-equiv=\"Content-Type\" | ||
| content=\"text/html; charset=UTF-8\" /><title></title></head><body style=\"margin: 0; font-family: 'Open Sans', | ||
| Arial, sans-serif;\"><H1>Otsikko</h1><p>Viestin sisältö</p><p>Ystävällisin terveisin<br/>Opintopolku</p></body></html>") | ||
| .withKielet("fi") | ||
| .withVastaanottajat(ViestinvalitysBuilder.vastaanottajatBuilder() | ||
| .withVastaanottaja(Optional.empty(), "[email protected]") | ||
|
|
@@ -64,6 +73,28 @@ Tai luoda viestejä erillisinä lähetyksinä | |
| .withLahettaja(Optional.empty(), "[email protected]") | ||
| .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 | ||
|
|
||