Message Formatter

A kliensek felé küldött általános hibaüzenetek már részletesebben is kifejtésre kerültek a Hibakezelés oldalon.

Azt azonban, hogy hogyan is áll elő az általános hibaüzenetben található lefordított hibaüzenet (SystemMessage.message field) az alábbi pontok hivatottak ismertetni.

1. Hibakódok használata

Azért, hogy az egyes hibaüzenetek a kódban egyszerűen újrafelhasználhatóak legyenek, az általános hibaüzenetek létrehozásakor csak a hibaüzenetek kódját állítjuk be (SystemMessage.code field), a hibaüzenetet (SystemMessage.message field) nem kézzel töltjük ki.

Ennek az az előnye, hogy amíg a hibakódhoz társított hibaüzenet szövege változhat, addig a hibakód állandó. Így a programkódban nem szükséges frissíteni a hibakódokat, elég magát a hibüzenetet módosítani.

Az ehhez szükséges hibakód - hibaüzenet hozzárendeléseket backend-service/src/main/resources mappában található message.properties fájl tartalmazza.

Dinamikus paraméterek a hibaüzenetben

Egyes hibaüzeneteknek lehetnek dinamikusan behelyettesítendő részei. Ilyenek lehetnek például: felhasználó neve vagy különböző értékek: összegek, születési dátum stb.

Természetesen az általános hibaüzenet létrehozásakor ezek a paraméterek is megadhatóak a SystemMessage.params tömbjében.

Több nyelvű hibaüzenetek használata

A hibakódok használatának másik előnye, hogy a szerveroldal akár nyelvesítve is képes lenne leküldeni a hibakód alapján a lefordított hibaüzenetet.

Pl.: Ha a klienstől megkapjuk mi az aktuálisan kiválasztott nyelv, akkor a szerveroldal képes lenne a beküldött nyelv és a hibakód alapján a megfelelő nyelvű hibaüzenetet visszaadni.

Fontos, hogy jelenleg az alkalmazás csak 1 nyelvet támogat, a több nyelv támogatásának bevezetése jövőbeli fejlesztés lesz.

2. A hibaüzenetek feloldása hibakód és paraméterek alapján

Ahogy azt a Hibakezelés oldalon korábban írtuk, a szerveren keletkező összes kivételt (Exception) a BaseExceptionHandler kezeli és alakítja át a SystemMessageResponse típusra.

Ahhoz azonban, hogy BaseExceptionHandler a hibakód, és a paraméterek alapján ki tudja tölteni a SystemMessage-ben található hibaüzeneteket, a MessageService-t használja.

2.1 A MessageService működése

1. A MessageService megkeresi a message.properties fájl beolvasása után, a hibakódhoz tartozó hibaüzenetet.
2. Ha az általános hibaüzenet nem tartalmazott paramétereket akkor egyszerűen visszaadja az így megkapott hibaüzenetet.
3. Ha vannak paraméterek, akkor behelyettesíti a hibaüzenet megfelelő részeibe (szükség esetén formázva) a paramétereket.

2.2 Speciális paraméterezési lehetőségek

Előfordulhat, hogy az általános hibaüzenet létrehozásakor, a SystemMessage.params mezőjében egy szám értéket adunk meg. Pl.: 1000000.

Egy számérték esetén előfordulhat, hogy szeretnénk ha a hibaüzenetbe nem csupán behelyettesítődne, hanem speciális formázást kapna. Például ha ez a szám egy fizetendő összeg, célszerű lehet 3 számjegyenként szóközzel elválasztva behelyettesíteni az üzenetbe. Pl.: Fizetendő összeg: 1 000 000.

Ahhoz, hogy a MessageService a kapott paramétert be tudja formázni két dolog szükséges:

• A messages.properties fájlban megfelelő formátumban legyen felvéve a hibakód és a paraméterek placeholdereit is tartalmazó hibaüzenet.
• Legyen definiálva a megfelelő MessageFormatter implementáció az összegek formázásához. A fenti példa esetén ez az AmountFormatter.

2.3 A MessageFormatter implementálása

Egy új MessageFormatter definiálásához két metódus implementálása szükséges:

• getMessageFormatter: Visszadja a formatter típusát ami MessageFormatterTypeEnum típusú kell legyen. (Ebből következik, hogy egy új formatter bevezetésekor ezt az MessageFormatterTypeEnum-ot is bővíteni kell.)
• formatMessage: Ebben a metódusban kell implementálni a formázási logikát.

A MessageFormatterTypeEnum bővítése

Amikor egy új MessageFormatter implementációt írunk, akkor az új formatter típushoz tartozó enum értéket fel kell vennünk a MessageFormatterTypeEnum-ba. Az ott value-ként megadott értéket kell használnunk a későbbiekben a messages.properties fájlban, amikor a hibaüzenetben meg akarjuk hivatkozni a formatter-t.

2.4 A message.properties fájl és annak használata

A message.properties fájl a backend-service/src/main/resources mappában található. Ebben a fájlban definiáljuk a rendszerben használt hibák kódjait és a hozzájuk tartozó hibaüzeneteket. Illetve, a hibaüzenetektől függetlenül szótárként is funkcionál.

2.4.1 Hibaüzenetek

Egy hibaüzenet 2 féle lehet:

• Normál (paraméterek nélküli):

  error.server.unknown=Ismeretlen szerverhiba
  

• Paraméterezett:
  • Formázást nem igénylő paraméterekkel:

    error.validation.size=A mező hossza legyen legalább {0} és legfeljebb {1} karakter!
    

  • Formázást igénylő paraméterekkel:

    error.validation.min-inclusive=A mező értéke legyen legalább {amount:0}!
    

Paraméterezett hibaüzenetek

A paraméterezett hibaüzenetek természetesen vegyítve tartalmazhatnak formázást igénylő és formázást nem igénylő paramétereket is.

2.4.1.1 Normál hibaüzenet

A normál hibaüzenetek esetén egyszerűen csak a hibakód=hibaüzenet formátumot kell követnünk a message.properties fájl bővítésénél.

Az ilyen hibaüzenetek esetén a MessageService módosítás nélkül visszaadja a definiált hibaüzenetet.

2.4.1.2 Paraméterezett hibaüzenet

2.4.1.2.1 Formázást nem igénylő paraméterekkel

A formázást nem igénylő paramétereket tartalmazó hibaüzenetek esetén az alábbi formátumot kell követni:

hibakód=üzeneteleje {n} üzenetközepe {m} üzenetvége.

Ahol az n és m placeholderek a paraméterek sorszámai 0-tól indexelve. Pl.:

hibakód=üzeneteleje {0} üzenetközepe {1} üzenetvége.

Ebben az esetben a MessageService a SystemMessage.params tömb 0. indexén található paramétert helyettesíti a {0} placeholder helyére, a tömb 1. indexén található paramétert helyettesíti az {1} placeholder helyére, és visszaadja az így feloldott hibaüzenetet.

2.4.1.2.2 Formázást igénylő paraméterekkel

A formázást igénylő paramétereket tartalmazó hibaüzenetek esetén az alábbi formátumot kell követni:

hibakód=üzeneteleje {formatter-type:n} üzenetközepe {formatter-type:m} üzenetvége.

Ahol az n és m placeholderek a paraméterek sorszámai 0-tól indexelve, a formatter-type placeholder pedig a MessageFormatterTypeEnum-ban definiált használni kívánt formatter value értéke. Pl. AmountFormatter esetén:

hibakód=üzeneteleje {amount:0} üzenetközepe {amount:1} üzenetvége.

Ebben az esetben a MessageService a SystemMessage.params tömb 0. indexén található paramétert helyettesíti a {0} placeholder helyére összegként formázva, a tömb 1. indexén található paramétert helyettesíti az {1} placeholder helyére összegként formázva, és visszaadja az így feloldott hibaüzenetet.

2.4.1.2.3 Formázást igénylő és nem igénylő paramétereket is tartalmazó hibaüzenetek

Természtesen az előző két pontban kifejtett paraméterezés vegyíthető is egymással:

hibakód=üzeneteleje {n} üzenetközepe {formatter-type:m} üzenetvége.

Ahol az n és m placeholderek a paraméterek sorszámai 0-tól indexelve, a formatter-type placeholder pedig a MessageFormatterTypeEnum-ban definiált használni kívánt formatter value értéke. Pl. AmountFormatter esetén:

hibakód=üzeneteleje {0} üzenetközepe {amount:1} üzenetvége.

Ebben az esetben a MessageService a SystemMessage.params tömb 0. indexén található paramétert helyettesíti a {0} placeholder helyére, a tömb 1. indexén található paramétert helyettesíti az {1} placeholder helyére összegként formázva, és visszaadja az így feloldott hibaüzenetet.

2.4.2 Szótár

A message.properties fájlba kerülhetnek bizonyos konstansok fordításai is. Pl.: adatbázisban tárolt konstansok fordításai, hónapok sorszámához tartozó hónapnevek fordításai stb.

Ennek célja, hogy amennyiben a felületen szeretnénk megjeleníteni például a hónapok neveit a hónapok sorszáma alapján, akkor ne a kliensen legyenek beégetve a megfelelő fordítások, hanem a szerver képes legyen leküldeni a hónap sorszáma alapján ezeket.

Ez egyben azt is jelenti, hogy semmiképp se a programkódba beégetve legyenek a kliens felé küldött üzenetek. Helyette definiáljuk a message.properties fájlba a fordításokat, és a kódban használjuk a TranslationService-t ezek feloldására.