Sestavování textových zpráv pomocí šablon nejen v Ujorm

Ujorm verze 1.74 obsahuje nový, samostatný modul, který nabízí třídy pro sestavování textových zpráv pomocí šablony a parametrů. Pro srovnání přikládám vzorové použití standardní Java knihovny. Všechny třídy se liší především způsobem zápisu parametrů v šabloně. Použité ukázky kódu jsem zkopíroval z jUnit testů projektu Ujorm.

Třída MsgFormatter

Metoda MsgFormatter.format() z knihovny Ujorm je určena pro rychlé použití šablony, která označuje vkládané parametry dvojicí složených uvozovek "{}", pořadí parametrů vkládaných do šablony je dáno pořadím v metodě. Vzorová ukázka použití je tady:

    assertEquals("TEST"    , MsgFormatter.format("TE{}T", "S"));
    assertEquals("TE, S, T", MsgFormatter.format("TE", "S", "T"));
    assertEquals("TES{}"   , MsgFormatter.format("TE{}{}", "S"));

Výhodou je absence výjimek způsobených chybným počtem parametrů, protože přebytečné parametry se zapisují na konec zprávy oddělené čárkou s mezerou a ty chybějící se pouze nenahradí za značku. Pokud má výsledná zpráva obsahovat sekvenci "{}", je nutné ji vložit do šablony jako parametr. Třída nepodporuje formátování hodnot parametrů, v případě takové potřeby použijte raději následující třídu ze stejné knihovny.

Třída MessageService

Tato třída je také z knihovny Ujorm. Parametry metody MessageService.format() v šabloně se označují výrazem typu "${PRICE}", kde PRICE je název parametru, který může být volitelně doplněný formátem podle vzoru "${PRICE,%.2f}". Popis formátu je shdoný je shodný s metodou String.format(). Parametry šablony se předávají v objektu typu  Map<String, Object>, ukázka použití následuje:

    String expected = "On 2017-01-15, we spent 254.00 EUR.";
    String template = "On ${DAY,%tF}, we spent ${PRICE,%.2f} EUR.";
    MessageService instance = new MessageService();
    Map<String,Object> params = instance.map
          ( "DAY", LocalDateTime.of(2017, Month.JANUARY, 15, 12, 30)
          , "PRICE", new BigDecimal("254"));
    String result = new MessageService().format(template, params);
    assertEquals(expected, result);

Další ukázky použití najdete v jUnit testu. Pro srovnání uvádím dále ještě dvě metody ze standardní Java knihovny.

Třída String

Statická metoda String.format() vytváří interně instanci třídy Formatter. Pozice parametrů se označují výrazem začínajícím znakem procenta (například "%s") a volitelné formátování hodnoty parametru. Příklad použití:

    String expected = "On 2017-01-15, we spent 254.00 EUR.";
    String template = "On %tF, we spent %.2f EUR.";
    LocalDateTime day = LocalDateTime.of(2017, Month.JANUARY, 15, 12, 30);
    String result = String.format(ENGLISH, template, day, new BigDecimal("254"));
    assertEquals(expected, result);

Pokud je parametrů méně, než značek, metoda vyhazuje výjimku MissingFormatArgumentException, pokud je jich naopak více, tak jsou ignrorovány.

Třída MessageFormat

Poslední metoda MessageFormat.format() je také statická metoda ze standardní Java knihovny a také podporuje formátování parametrů. Místo určené pro vkládání pametrů se označuje výrazy číslovanými od nuly podle vzoru "{0}, "{1}" a konkrétní parametry se vkládájí pomocí pole. Příklad použití:

    String expected = "On 2017-01-15, we spent 254.00 EUR.";
    String template = "On {0,date,yyyy-MM-dd}, we spent {1,number,#.00} EUR.";
    Date day = Date.from(LocalDateTime.of(2017, Month.JANUARY, 15, 12, 30)
              .atZone(ZoneId.systemDefault()).toInstant());
    Object[] params = { day, new BigDecimal("254")};
    String result = new MessageFormat(template, ENGLISH).format(params);
    assertEquals(expected, result);

Výchozí Locale se bere z operačního systému, argument typu java.time.LocalDateTime není bohužel podporovaný a vyhazuje výjimku IllegalArgumentException.

Performance

Přikládám přibližnou výkonnost jednotlivých tříd, tolerance naměřených hodnot může být až 10%. Pro každý formatter proběhlo 5_000_000 iterací ve kterých se do jednoduché šablony (bez formátování) dosadily tři krátké argumenty.

Třída	Čas [ms]	Výkon (větší je lepší)
MsgFormatter	1158	100.00%
MessageService	2268	51.06%
String	12243	9.46%
MessageFormat	5023	23.05%

Další podrobnosti o testu najdete tady, Na závěr přikládám popis Maven závislosti:

   <dependency>
     <groupId>org.ujorm</groupId>
     <artifactId>ujo-tools</artifactId>
     <version>1.74</version>
   </dependency>