Uvod u Smooksa

1. Pregled

U ovom uputstvu predstavit ćemo Smooksov okvir.

Opisat ćemo što je to, navesti njegove ključne značajke i na kraju naučiti kako koristiti neke od njegovih naprednijih funkcionalnosti.

Prije svega, objasnimo ukratko što je okvir namijenjen postizanju.

2. Smooksi

Smooks je okvir za programe za obradu podataka - koji se bave strukturiranim podacima kao što su XML ili CSV.

Pruža i API-je i model konfiguracije koji nam omogućuju definiranje transformacija između unaprijed definiranih formata (na primjer XML u CSV, XML u JSON i više).

Također možemo koristiti brojne alate za postavljanje našeg mapiranja - uključujući FreeMarker ili Groovy skripte.

Osim transformacija, Smooks pruža i druge značajke poput provjere valjanosti poruka ili razdvajanja podataka.

2.1. Glavne značajke

Pogledajmo glavne primjere Smooksa:

  • Pretvorba poruka - transformacija podataka iz različitih izvornih formata u različite izlazne formate
  • Obogaćivanje poruka - popunjavanje poruke dodatnim podacima koji dolaze iz vanjskog izvora podataka poput baze podataka
  • Podjela podataka - obrada velikih datoteka (GB) i njihovo dijeljenje na manje
  • Java obvezujuće - konstruiranje i popunjavanje Java objekata iz poruka
  • Provjera valjanosti poruke - izvođenje provjera valjanosti poput regularnog izraza ili čak stvaranje vlastitih pravila provjere valjanosti

3. Početna konfiguracija

Krenimo od ovisnosti o Mavenu koju trebamo dodati svojoj pom.xml:

 org.milyn milyn-smooks-svi 1.7.0 

Najnoviju verziju možete pronaći na Maven Central.

4. Java vezanje

Krenimo sada s fokusiranjem na vezivanje poruka za Java klase. Ovdje ćemo proći kroz jednostavnu pretvorbu XML u Javu.

4.1. Osnovni koncepti

Počet ćemo s jednostavnim primjerom. Razmotrite sljedeći XML:

 771 IN_PROGRES 

Da bismo ovaj zadatak izvršili sa Smooksom, moramo učiniti dvije stvari: pripremiti POJO-ove i Smooks konfiguraciju.

Pogledajmo kako izgleda naš model:

narudžba javne klase {privatni Datum kreiranjaDat; privatni Long broj; status privatnog statusa; // ...} 
status javnog popisa {NEW, IN_PROGRESS, FINISHED}

Sada, prijeđimo na Smooksova preslikavanja.

U osnovi, preslikavanja su XML datoteka koja sadrži logiku transformacije. U ovom ćemo članku koristiti tri različite vrste pravila:

  • grah - definira mapiranje konkretnog strukturiranog odjeljka u klasu Java
  • vrijednost - definira mapiranje za određeno svojstvo graha. Može sadržavati napredniju logiku poput dekodera, koji se koriste za mapiranje vrijednosti u neke vrste podataka (poput datuma ili decimalnog formata)
  • wIring - omogućuje nam povezivanje graha s drugim grahom (na primjer Dobavljač grah će biti ožičen Narudžba grah)

Pogledajmo ovdje preslikavanja koja ćemo koristiti u našem slučaju:

      gggg-MM-dd 

Sada, s pripremljenom konfiguracijom, pokušajmo testirati je li naš POJO pravilno konstruiran.

Prvo, moramo konstruirati Smooks objekt i proslijediti ulazni XML kao tok:

javni nalog convertOrderXMLToOrderObject (put niza) baca IOException, SAXException {Smooks smooks = novi Smooks (this.class.getResourceAsStream ("/ smooks-mapping.xml")); isprobajte {JavaResult javaResult = novi JavaResult (); smooks.filterSource (novi StreamSource (this.class .getResourceAsStream (path)), javaResult); return (Narudžba) javaResult.getBean ("narudžba"); } napokon {smooks.close (); }}

I na kraju, potvrdite je li konfiguracija ispravno izvedena:

@Test javna praznina givenOrderXML_whenConvert_thenPOJOsConstructedCorrect () baca iznimku {XMLToJavaConverter xmlToJavaOrderConverter = new XMLToJavaConverter (); Order order = xmlToJavaOrderConverter .converOrderXMLToOrderObject ("/ order.xml"); assertThat (order.getNumber (), je (771L)); assertThat (order.getStatus (), je (Status.IN_PROGRESS)); assertThat (order.getCreationDate (), je (novi SimpleDateFormat ("yyyy-MM-dd"). parse ("2018-01-14"));}

4.2. Napredno vezivanje - referenciranje ostalih graha i popisa

Proširimo naš prethodni primjer s dobavljač i stavke narudžbe oznake:

 771 IN_PROGRESS Tvrtka X 1234567 1 PX1234 9.99   1 RX990 120.32   

A sada ažurirajmo naš model:

narudžba javne klase {// .. privatni dobavljač dobavljač; privatne stavke s popisa; // ...}
predmet javne klase {privatni kod niza; privatno Dvostruka cijena; privatna Integer količina; // ...} 
dobavljač javne klase {naziv privatnog niza; private String phoneNumber; // ...}

Također moramo proširiti mapiranje konfiguracije s dobavljač i artikal definicije graha.

Primijetite da smo također definirali razdvojene predmeta grah, koji će držati sve artikal elementi u ArrayList.

Napokon, poslužit ćemo se Smooksima ožičenje atribut, kako biste sve to povezali.

Pogledajte kako će preslikavanja izgledati u ovom slučaju:

      gggg-MM-dd 

Na kraju ćemo dodati nekoliko tvrdnji u naš prethodni test:

assertThat (order.getSupplier (), je (novi dobavljač ("Tvrtka X", "1234567"))); assertThat (order.getItems (), containsInAnyOrder (nova stavka ("PX1234", 9,99,1), nova stavka ("RX990", 120,32,1)));

5. Provjera valjanosti poruka

Smooks dolazi s mehanizmom provjere valjanosti koji se temelji na pravilima. Pogledajmo kako se koriste.

Definicija pravila pohranjena je u konfiguracijskoj datoteci, ugniježđenoj u baze pravila oznaka koja može sadržavati mnogo ruleBase elementi.

Svaki ruleBase element mora imati sljedeća svojstva:

  • Ime - jedinstveni naziv, korišten samo za referencu
  • src - put do izvorne datoteke pravila
  • davatelja usluga - potpuno kvalificirani naziv klase, koji provodi RuleProvider sučelje

Smooks dolazi s dva dobavljača iz kutije: RegexProvider i MVELProvider.

Prvo se koristi za provjeru valjanosti pojedinih polja u stilu sličnom regularnom izrazu.

Drugi se koristi za obavljanje složenijih provjera valjanosti u globalnom opsegu dokumenta. Pogledajmo ih na djelu.

5.1. RegexProvider

Iskoristimo RegexProvider za provjeru valjanosti dviju stvari: formata imena kupca i telefonskog broja. RegexProvider kao izvor zahtijeva datoteku svojstava Java, koja treba sadržavati provjeru regularnih izraza na način ključ / vrijednost.

Kako bismo udovoljili našim zahtjevima, poslužit ćemo se sljedećim postavkama:

providerName = [A-Za-z0-9] * dobavljačPhone = ^ [0-9 \ - \ +] {9,15} $

5.2. MVELProvider

Koristit ćemo MVELProvider za provjeru valjanosti ako je ukupna cijena za svaki narudžba-stavka je manje od 200. Kao izvor pripremit ćemo CSV datoteku s dva stupca: naziv pravila i izraz MVEL.

Da bismo provjerili je li cijena točna, potreban nam je sljedeći unos:

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

5.3. Konfiguracija provjere valjanosti

Nakon što pripremimo izvorne datoteke za baze pravila, prijeći ćemo na provođenje konkretnih provjera valjanosti.

Provjera valjanosti je još jedna oznaka u Smooks konfiguraciji, koja sadrži sljedeće atribute:

  • executeOn - put do provjerenog elementa
  • Ime - referenca na ruleBase
  • onFail - određuje koje će se radnje poduzeti kada provjera valjanosti ne uspije

Primijenimo pravila provjere valjanosti na našu konfiguracijsku datoteku Smooks i provjerimo kako izgleda (imajte na umu da ako želimo koristiti MVELProvider, prisiljeni smo koristiti Java vezivanje, pa smo zato uvezli prethodnu Smooks konfiguraciju):

Sada, kad je konfiguracija spremna, pokušajmo testirati hoće li provjera valjanosti uspjeti na telefonskom broju dobavljača.

Opet, moramo konstruirati Smooksi objekt i proslijedi ulazni XML kao tok:

public ValidationResult validate (String path) baca IOException, SAXException {Smooks smooks = novi Smooks (OrderValidator.class .getResourceAsStream ("/ smooks / smooks-validation.xml")); isprobajte {StringResult xmlResult = new StringResult (); JavaResult javaResult = novi JavaResult (); ValidationResult validationResult = novo ValidationResult (); smooks.filterSource (novi StreamSource (OrderValidator.class .getResourceAsStream (put)), xmlResult, javaResult, validationResult); vratiti validationResult; } napokon {smooks.close (); }} 

I na kraju ustvrdite, ako se dogodila pogreška u provjeri:

@Test javna praznina givenIncorrectOrderXML_whenValidate_thenExpectValidationErrors () baca izuzetak {OrderValidator orderValidator = new OrderValidator (); ValidationResult validationResult = orderValidator .validate ("/ smooks / order.xml"); assertThat (validationResult.getErrors (), hasSize (1)); assertThat (validationResult.getErrors (). get (0) .getFailRuleResult (). getRuleName (), je ("providerPhone")); }

6. Pretvorba poruka

Sljedeće što želimo učiniti je pretvoriti poruku iz jednog formata u drugi.

U Smooksu se ova tehnika naziva i predloškom i podržava:

  • FreeMarker (poželjna opcija)
  • XSL
  • Niz predložak

U našem primjeru koristit ćemo mehanizam FreeMarker za pretvorbu XML poruke u nešto vrlo slično EDIFACT-u, pa čak i pripremiti predložak za poruku e-pošte na temelju XML narudžbe.

Pogledajmo kako pripremiti predložak za EDIFACT:

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

A za e-poruku:

Pozdrav, broj narudžbe # $ {order.number} stvoren $ {order.creationDate? Date} trenutno je u statusu $ {order.status}. Razmislite o tome da kontaktirate dobavljača "$ {provider.name}" s telefonskim brojem: "$ {provider.phoneNumber}". Stavke za narudžbu: $ {item.quantity} X $ {item.code} (ukupna cijena $ {item.price * item.quantity}) 

Konfiguracija Smooksa ovaj je put vrlo osnovna (samo ne zaboravite uvesti prethodnu konfiguraciju kako biste uvezli postavke vezivanja Java):

    /path/to/template.ftl 

Ovaj put moramo samo proći StringResult za Smooksov motor:

Smooks smooks = novi Smooks (config); StringResult stringResult = novi StringResult (); smooks.filterSource (novi StreamSource (OrderConverter.class .getResourceAsStream (put)), stringResult); vratiti stringResult.toString ();

I mi to možemo, naravno, testirati:

@Test javna praznina givenOrderXML_whenApplyEDITemplate_thenConvertedToEDIFACT () baca izuzetak {OrderConverter orderConverter = new OrderConverter (); Niz edifact = orderConverter.convertOrderXMLtoEDIFACT ("/smooks/order.xml"); assertThat (edifakt je (EDIFACT_MESSAGE)); }

7. Zaključak

U ovom smo se vodiču usredotočili na to kako pretvoriti poruke u različite formate ili ih pretvoriti u Java objekte pomoću Smooksa. Također smo vidjeli kako izvršiti provjere valjanosti na temelju pravila regularnog izraza ili poslovne logike.

Kao i uvijek, sav ovdje korišten kod može se pronaći na GitHubu.