streamalism.org

1. Prehľad

V tomto tutoriále predstavíme rámec Smooks.

Popíšeme, čo to je, vymenujeme jeho kľúčové vlastnosti a nakoniec sa naučíme, ako používať niektoré z jeho pokročilejších funkcií.

Najskôr si v krátkosti vysvetlíme, čo má rámec dosiahnuť.

2. Smokuje

Smooks je rámec pre aplikácie na spracovanie údajov - zaoberá sa štruktúrovanými údajmi, ako sú XML alebo CSV.

Poskytuje API aj konfiguračný model, ktorý nám umožňuje definovať transformácie medzi preddefinovanými formátmi (napríklad XML na CSV, XML na JSON a ďalšie).

Na nastavenie mapovania môžeme použiť aj množstvo nástrojov - vrátane skriptov FreeMarker alebo Groovy.

Okrem transformácií Smooks poskytuje aj ďalšie funkcie, ako napríklad overovanie správ alebo rozdelenie údajov.

2.1. Kľúčové vlastnosti

Pozrime sa na hlavné prípady použitia Smooks:

• Konverzia správ - transformácia údajov z rôznych zdrojových formátov do rôznych výstupných formátov
• Obohatenie správy - vyplnenie správy o ďalšie údaje, ktoré pochádzajú z externého zdroja údajov, napríklad z databázy
• Delenie údajov - spracovanie veľkých súborov (GB) a ich rozdelenie na menšie
• Väzba Java - vytváranie a vyplňovanie objektov Java zo správ
• Validácia správ - vykonávanie validácií ako regex alebo dokonca vytváranie vlastných pravidiel overovania

3. Počiatočná konfigurácia

Začnime so závislosťou Maven, ktorú musíme pridať do našej pom.xml:

 org.milyn milyn-smooks-all 1.7.0 

Najnovšiu verziu nájdete na serveri Maven Central.

4. Väzba Java

Začnime sa teraz zameraním na viazanie správ na triedy Java. Prejdeme si tu jednoduchú konverziu XML na Java.

4.1. Základné pojmy

Začneme jednoduchým príkladom. Zvážte nasledujúce XML:

 771 IN_PROGRESS 

Na splnenie tejto úlohy pomocou Smooks musíme urobiť dve veci: pripraviť POJO a konfiguráciu Smooks.

Pozrime sa, ako vyzerá náš model:

verejná trieda Objednávka {private Date creationDate; súkromné ​​Dlhé číslo; stav súkromného stavu; // ...} 

stav verejného výčtu {NOVÝ, IN_PROGRESS, DOKONČENÝ}

Poďme teraz k mapovaniu Smooks.

V zásade sú mapovania súbor XML, ktorý obsahuje transformačnú logiku. V tomto článku použijeme tri rôzne typy pravidiel:

• fazuľa - definuje mapovanie konkrétneho štruktúrovaného rezu do triedy Java
• hodnotu - definuje mapovanie pre konkrétnu vlastnosť fazule. Môže obsahovať pokročilejšiu logiku, ako sú dekodéry, ktoré sa používajú na mapovanie hodnôt na niektoré typy údajov (napríklad dátum alebo desatinný formát).
• wiring - umožňuje prepojiť fazuľu s inými fazuľami (napr Dodávateľ fazuľa bude pripojená k objednať fazuľa)

Pozrime sa tu na mapovania, ktoré v našom prípade použijeme:

      rrrr-MM-dd 

Teraz, keď je konfigurácia pripravená, skúsme vyskúšať, či je náš POJO zostavený správne.

Najprv musíme skonštruovať objekt Smooks a odovzdať vstupný XML ako prúd:

public Order convertOrderXMLToOrderObject (reťazcová cesta) vyvolá IOException, SAXException {Smooks smooks = nové Smooks (this.class.getResourceAsStream ("/ smooks-mapping.xml")); try {JavaResult javaResult = new JavaResult (); smooks.filterSource (nový StreamSource (this.class .getResourceAsStream (cesta)), javaResult); return (Objednávka) javaResult.getBean ("objednávka"); } nakoniec {smooks.close (); }}

A nakoniec, uistite sa, či je konfigurácia vykonaná správne:

@Test public void givenOrderXML_whenConvert_thenPOJOsConstructedCorrectly () vyvolá výnimku {XMLToJavaConverter xmlToJavaOrderConverter = nový XMLToJavaConverter (); Order order = xmlToJavaOrderConverter .converOrderXMLToOrderObject ("/ order.xml"); assertThat (order.getNumber (), je (771L)); assertThat (order.getStatus (), je (Status.IN_PROGRESS)); assertThat (order.getCreationDate (), je (nový SimpleDateFormat ("rrrr-MM-dd"). parse ("2018-01-14"));}

4.2. Pokročilá väzba - odkazovanie na iné fazule a zoznamy

Rozšírime náš predchádzajúci príklad o dodávateľ a objednávkové položky tagy:

 771 IN_PROGRESS Spoločnosť X 1234567 1 PX1234 9.99   1 RX990 120.32   

A teraz poďme aktualizovať náš model:

public class Order {// .. súkromný dodávateľ dodávateľa; súkromné ​​položky zoznamu; // ...}

public class Item {private String code; súkromná dvojitá cena; súkromné ​​celé číslo; // ...} 

public class Supplier {private String name; private String phoneNumber; // ...}

Musíme tiež rozšíriť mapovanie konfigurácie o dodávateľ a položka fazuľové definície.

Všimnite si, že sme definovali aj oddelené položky fazuľa, ktorá pojme všetky položka prvky v ArrayList.

Na záver použijeme Smooks elektrické vedenie atribút, spojiť to všetko dohromady.

Zoznámte sa s tým, ako budú v tomto prípade vyzerať mapovania:

      rrrr-MM-dd 

Na záver pridáme niekoľko tvrdení k nášmu predchádzajúcemu testu:

assertThat (order.getSupplier (), je (nový dodávateľ („spoločnosť X“, „1234567“)))); assertThat (order.getItems (), containsInAnyOrder (nová položka ("PX1234", 9,99,1), nová položka ("RX990", 120,32,1))));

5. Validácia správ

Spoločnosť Smooks prichádza s mechanizmom overovania založeným na pravidlách. Poďme sa pozrieť na to, ako sa používajú.

Definícia pravidiel je uložená v konfiguračnom súbore vnorenom do súboru pravidloBázy značka, ktorá môže obsahovať veľa pravidloBase prvkov.

Každý pravidloBase prvok musí mať nasledujúce vlastnosti:

• názov - jedinečný názov, ktorý sa používa len ako referencia
• src - cesta k zdrojovému súboru pravidla
• poskytovateľ - plne kvalifikovaný názov triedy, ktorý sa implementuje RuleProvider rozhranie

Spoločnosť Smooks je vybavená dvoma poskytovateľmi: RegexProvider a MVELProvider.

Prvý z nich slúži na validáciu jednotlivých polí v štýle podobnom regulárnemu výrazu.

Druhá sa používa na vykonávanie komplikovanejšej validácie v globálnom rozsahu dokumentu. Uvidíme ich v akcii.

5.1. RegexProvider

Poďme použiť RegexProvider na overenie dvoch vecí: formát mena zákazníka a telefónne číslo. RegexProvider ako zdroj vyžaduje súbor vlastností Java, ktorý by mala obsahovať overenie regulárneho výrazu spôsobom kľúč - hodnota.

Na splnenie našich požiadaviek použijeme nasledujúce nastavenie:

SupplierName = [A-Za-z0-9] * SupplierPhone = ^ [0-9 \ - \ +] {9,15} $

5.2. MVELProvider

Použijeme MVELProvider overiť, či celková cena pre každého objednávková položka je menej ako 200. Ako zdroj pripravíme súbor CSV s dvoma stĺpcami: názov pravidla a výraz MVEL.

Aby sme zistili, či je cena správna, potrebujeme nasledujúci údaj:

"max_total", "orderItem.quantity * orderItem.price <200,00"

5.3. Konfigurácia overenia

Keď sme pripravili zdrojové súbory pre pravidloBázy, prejdeme k implementácii konkrétnych validácií.

Validácia je ďalšia značka v konfigurácii Smooks, ktorá obsahuje nasledujúce atribúty:

• executeOn Cesta k validovanému prvku
• názov - odkaz na pravidloBase
• onFail - určuje, aké kroky sa urobia, keď sa overenie nepodarí

Použime overovacie pravidlá na náš konfiguračný súbor Smooks a skontrolujte, ako to vyzerá (všimnite si, že ak chceme použiť MVELProvider, sme nútení používať väzbu Java, preto sme importovali predchádzajúcu konfiguráciu Smooks):

Teraz, keď je konfigurácia pripravená, pokúsime sa vyskúšať, či overenie zlyhá na telefónnom čísle dodávateľa.

Opäť musíme konštruovať Smooks objekt a odovzdať vstupný XML ako prúd:

public ValidationResult validate (reťazcová cesta) vyvolá IOException, SAXException {Smooks smooks = new Smooks (OrderValidator.class .getResourceAsStream ("/ smooks / smooks-validation.xml")); try {StringResult xmlResult = new StringResult (); JavaResult javaResult = nový JavaResult (); ValidationResult validationResult = nový ValidationResult (); smooks.filterSource (nový StreamSource (OrderValidator.class .getResourceAsStream (cesta)), xmlResult, javaResult, validationResult); return validationResult; } nakoniec {smooks.close (); }} 

A nakoniec tvrdiť, ak došlo k chybe overenia:

@Test public void givenIncorrectOrderXML_whenValidate_thenExpectValidationErrors () vyvolá výnimku {OrderValidator orderValidator = nový OrderValidator (); ValidationResult validationResult = orderValidator .validate ("/ smooks / order.xml"); assertThat (validationResult.getErrors (), hasSize (1)); assertThat (validationResult.getErrors (). get (0) .getFailRuleResult (). getRuleName (), je ("dodávateľPhone")); }

6. Konverzia správy

Ďalšou vecou, ​​ktorú chceme urobiť, je previesť správu z jedného formátu do druhého.

V Smooks sa táto technika nazýva aj šablóna a podporuje:

• FreeMarker (preferovaná možnosť)
• XSL
• String šablóna

V našom príklade použijeme engine FreeMarker na prevod správy XML na niečo veľmi podobné EDIFACTU a dokonca pripravíme šablónu pre e-mailovú správu na základe objednávky XML.

Pozrime sa, ako pripraviť šablónu pre EDIFACT:

UNA: +.? 'UNH + $ {order.number} + $ {order.status} + $ {order.creationDate? Date}' CTA + $ {supply.name} + $ {supply.phoneNumber} 'LIN + $ {item.quantity} + $ { item.code} + $ {item.price} ' 

A pre e-mailovú správu:

Ahoj, číslo objednávky # $ {order.number} vytvorené dňa $ {order.creationDate? Date} je momentálne v stave $ {order.status}. Zvážte kontaktovanie dodávateľa „$ {supply.name}“ s telefónnym číslom: „$ {supply.phoneNumber}“. Objednávať položky: $ {item.quantity} X $ {item.code} (celková cena $ {item.price * item.quantity}) 

Konfigurácia Smooks je tentokrát veľmi základná (nezabudnite importovať predchádzajúcu konfiguráciu, aby ste mohli importovať nastavenia väzby Java):

    /path/to/template.ftl 

Tentokrát musíme len zložiť a StringResult k motoru Smooks:

Smooks smooks = nové Smooks (konfigurácia); StringResult stringResult = nový StringResult (); smooks.filterSource (nový StreamSource (OrderConverter.class .getResourceAsStream (cesta)), stringResult); return stringResult.toString ();

A môžeme to samozrejme vyskúšať:

@ Test public void givenOrderXML_whenApplyEDITemplate_thenConvertedToEDIFACT () vyvolá Výnimku {OrderConverter orderConverter = nový OrderConverter (); Reťazec edifact = orderConverter.convertOrderXMLtoEDIFACT ("/smooks/order.xml"); assertThat (edifact, je (EDIFACT_MESSAGE)); }

7. Záver

V tomto tutoriáli sme sa zamerali na to, ako prevádzať správy do rôznych formátov alebo ich transformovať na objekty Java pomocou Smooks. Tiež sme videli, ako vykonávať validácie na základe regulárnych výrazov alebo pravidiel obchodnej logiky.

Ako vždy, všetky tu použité kódy nájdete na GitHub.