Introduksjon til Smooks

1. Oversikt

I denne opplæringen introduserer vi Smooks-rammeverket.

Vi vil beskrive hva det er, liste opp hovedfunksjonene, og til slutt lære å bruke noen av de mer avanserte funksjonalitetene.

La oss først forklare kort hva rammeverket er ment å oppnå.

2. Smooks

Smooks er et rammeverk for databehandlingsapplikasjoner - håndtering av strukturerte data som XML eller CSV.

Den gir både APIer og en konfigurasjonsmodell som lar oss definere transformasjoner mellom forhåndsdefinerte formater (for eksempel XML til CSV, XML til JSON og mer).

Vi kan også bruke en rekke verktøy for å sette opp kartleggingen vår - inkludert FreeMarker eller Groovy-skript.

I tillegg til transformasjoner, leverer Smooks også andre funksjoner som meldingsvalidering eller datadeling.

2.1. Nøkkelegenskaper

La oss ta en titt på Smooks 'viktigste brukssaker:

Meldingskonvertering - transformasjon av data fra forskjellige kildeformater til forskjellige utdataformater
Meldingsberikelse - fyll ut meldingen med tilleggsdata som kommer fra ekstern datakilde som database
Datadeling - behandling av store filer (GBs) og deling av dem i mindre
Java-binding - konstruere og fylle ut Java-objekter fra meldinger
Meldingsvalidering - utføre valideringer som regex, eller til og med lage dine egne valideringsregler

3. Innledende konfigurasjon

La oss starte med Maven-avhengigheten vi trenger å legge til i vår pom.xml:

 org.milyn milyn-smooks-all 1.7.0

Den siste versjonen finner du på Maven Central.

4. Java Binding

La oss nå begynne med å fokusere på å binde meldinger til Java-klasser. Vi går gjennom en enkel XML til Java-konvertering her.

4.1. Enkle konsepter

Vi begynner med et enkelt eksempel. Vurder følgende XML:

 771 IN_PROGRESS

For å utføre denne oppgaven med Smooks, må vi gjøre to ting: forberede POJO-ene og Smooks-konfigurasjonen.

La oss se hvordan modellen vår ser ut:

public class Order {private Date creationDate; privat Langt nummer; privat status status; // ...}

offentlig enum Status {NEW, IN_PROGRESS, FINISHED}

La oss nå gå videre til Smooks-kartlegginger.

I utgangspunktet er kartleggingen en XML-fil som inneholder transformasjonslogikk. I denne artikkelen bruker vi tre forskjellige typer regler:

bønne - definerer kartleggingen av en konkret strukturert del til Java-klassen
verdi - definerer kartleggingen for den spesielle egenskapen til bønnen. Kan inneholde mer avansert logikk som dekodere, som brukes til å kartlegge verdier til noen datatyper (som dato eller desimalformat)
wiring - lar oss koble en bønne til andre bønner (for eksempel Leverandør bønne blir koblet til Rekkefølge bønne)

La oss ta en titt på kartleggingen vi bruker i vårt tilfelle her:

      åååå-MM-dd

Nå, med konfigurasjonen klar, la oss prøve å teste om vår POJO er konstruert riktig.

Først må vi konstruere et Smooks-objekt og sende XML-inngang som en strøm:

offentlig Orden converOrderXMLToOrderObject (strengbane) kaster IOException, SAXException {Smooks smooks = new Smooks (this.class.getResourceAsStream ("/ smooks-mapping.xml")); prøv {JavaResult javaResult = new JavaResult (); smooks.filterSource (ny StreamSource (this.class .getResourceAsStream (sti)), javaResult); returner (Bestilling) javaResult.getBean ("ordre"); } til slutt {smooks.close (); }}

Og til slutt, hevder om konfigurasjonen er riktig:

@Test offentlig ugyldighet gittOrderXML_whenConvert_thenPOJOsConstructedCorrectly () kaster Unntak {XMLToJavaConverter xmlToJavaOrderConverter = ny XMLToJavaConverter (); Bestillingsordre = xmlToJavaOrderConverter .converOrderXMLToOrderObject ("/ order.xml"); assertThat (order.getNumber (), er (771L)); assertThat (order.getStatus (), er (Status.IN_PROGRESS)); assertThat (order.getCreationDate (), er (ny SimpleDateFormat ("åååå-MM-dd"). parse ("2018-01-14"));}

4.2. Avansert binding - Henvisning til andre bønner og lister

La oss utvide vårt forrige eksempel med leverandør og ordre-varer tagger:

 771 IN_PROGRESS Company X 1234567 1 PX1234 9.99   1 RX990 120.32

Og nå la oss oppdatere modellen vår:

offentlig klasse Bestill {// .. privat leverandør leverandør; private Listelementer; // ...}

public class Item {private String code; privat dobbel pris; privat Heltall kvantitet; // ...}

offentlig klasse leverandør {privat strengnavn; privat strengnummer; // ...}

Vi må også utvide konfigurasjonskartleggingen med leverandør og punkt bønne definisjoner.

Legg merke til at vi også har definert atskilt gjenstander bønne, som vil holde alle punkt elementer i ArrayList.

Til slutt vil vi bruke Smooks ledninger attributt, for å pakke det hele sammen.

Ta en titt på hvordan kartlegginger vil se ut i dette tilfellet:

      åååå-MM-dd

Til slutt vil vi legge til noen påstander i vår forrige test:

assertThat (order.getSupplier (), er (ny leverandør ("Company X", "1234567"))); assertThat (order.getItems (), inneholderInAnyOrder (ny vare ("PX1234", 9.99,1), ny vare ("RX990", 120.32,1)));

5. Validering av meldinger

Smooks kommer med valideringsmekanisme basert på regler. La oss ta en titt på hvordan de brukes.

Definisjon av reglene er lagret i konfigurasjonsfilen, nestet i ruleBases tag, som kan inneholde mange ruleBase elementer.

Hver ruleBase elementet må ha følgende egenskaper:

Navn - unikt navn, bare brukt som referanse
src - sti til regelkildefilen
forsørger - fullt kvalifisert klassenavn, som implementeres RuleProvider grensesnitt

Smooks kommer med to leverandører ut av esken: RegexProvider og MVELTilbyder.

Den første brukes til å validere individuelle felt i regex-lignende stil.

Den andre brukes til å utføre mer komplisert validering i dokumentets globale omfang. La oss se dem i aksjon.

5.1. RegexProvider

La oss bruke RegexProvider for å validere to ting: formatet på kundenavnet og telefonnummeret. RegexProvider som kilde krever en Java-egenskapsfil, som bør inneholde regex-validering på nøkkelverdimåte.

For å oppfylle våre krav, bruker vi følgende oppsett:

leverandørnavn = [A-Za-z0-9] * leverandørPhone = ^ [0-9 \ - \ +] {9,15} $

5.2. MVELProvider

Vi bruker MVELProvider for å validere om totalprisen for hver bestillingsvare er mindre enn 200. Som kilde forbereder vi en CSV-fil med to kolonner: regelnavn og MVEL-uttrykk.

For å sjekke om prisen er riktig, trenger vi følgende oppføring:

"max_total", "orderItem.quantity * orderItem.price <200.00"

5.3. Valideringskonfigurasjon

Når vi har forberedt kildefilene for ruleBases, vil vi gå videre til implementering av konkrete valideringer.

En validering er en annen tag i Smooks-konfigurasjon, som inneholder følgende attributter:

executeOn - sti til det validerte elementet
Navn - referanse til ruleBase
onFail - spesifiserer hvilke tiltak som vil bli tatt når validering mislykkes

La oss bruke valideringsregler på Smooks-konfigurasjonsfilen og sjekke hvordan den ser ut (Vær oppmerksom på at hvis vi vil bruke MVELTilbyder, vi er tvunget til å bruke Java-binding, så det er derfor vi har importert tidligere Smooks-konfigurasjon):

Nå, med konfigurasjonen klar, la oss prøve å teste om validering mislykkes på leverandørens telefonnummer.

Igjen må vi konstruere Smooks objekt og pass inn XML som en strøm:

offentlig ValidationResult validere (strengbane) kaster IOException, SAXException {Smooks smooks = new Smooks (OrderValidator.class .getResourceAsStream ("/ smooks / smooks-validation.xml")); prøv {StringResult xmlResult = new StringResult (); JavaResult javaResult = ny JavaResult (); ValidationResult validationResult = new ValidationResult (); smooks.filterSource (ny StreamSource (OrderValidator.class .getResourceAsStream (sti)), xmlResult, javaResult, validationResult); return validationResult; } til slutt {smooks.close (); }}

Og til slutt hevde, hvis valideringsfeil oppstod:

@Test offentlig ugyldighet gittIncorrectOrderXML_whenValidate_thenExpectValidationErrors () kaster unntak {OrderValidator orderValidator = ny OrderValidator (); ValidationResult validationResult = orderValidator .validate ("/ smooks / order.xml"); assertThat (validationResult.getErrors (), hasSize (1)); assertThat (validationResult.getErrors (). get (0) .getFailRuleResult (). getRuleName (), er ("providerPhone")); }

6. Meldingskonvertering

Den neste tingen vi vil gjøre er å konvertere meldingen fra ett format til et annet.

I Smooks kalles denne teknikken også templating og den støtter:

FreeMarker (foretrukket alternativ)
XSL
String mal

I vårt eksempel bruker vi FreeMarker-motoren til å konvertere XML-meldinger til noe som ligner på EDIFACT, og til og med utarbeide en mal for e-postmeldingen basert på XML-rekkefølge.

La oss se hvordan vi forbereder en mal for EDIFACT:

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

Og for e-postmeldingen:

Hei, bestillingsnummer # $ {order.number} opprettet på $ {order.creationDate? Date} er for øyeblikket i $ {order.status} -status. Vurder å kontakte leverandøren "$ {provider.name}" med telefonnummeret: "$ {supplier.phoneNumber}". Bestillingsvarer: $ {item.quantity} X $ {item.code} (totalpris $ {item.price * item.quantity})

Smooks-konfigurasjonen er veldig grunnleggende denne gangen (bare husk å importere den forrige konfigurasjonen for å importere Java-bindingsinnstillinger):

    / sti / til / mal.ftl

Denne gangen må vi bare passere en StringResult til Smooks-motor:

Smooks smooks = nye Smooks (config); StringResult stringResult = ny StringResult (); smooks.filterSource (ny StreamSource (OrderConverter.class .getResourceAsStream (sti)), stringResult); return stringResult.toString ();

Og vi kan selvfølgelig teste det:

@Test offentlig ugyldighet gittOrderXML_whenApplyEDITemplate_thenConvertedToEDIFACT () kaster Unntak {OrderConverter orderConverter = ny OrderConverter (); String edifact = orderConverter.convertOrderXMLtoEDIFACT ("/smooks/order.xml"); assertThat (edifact, er (EDIFACT_MESSAGE)); }

7. Konklusjon

I denne opplæringen fokuserte vi på hvordan du konverterer meldinger til forskjellige formater, eller transformerer dem til Java-objekter ved hjelp av Smooks. Vi så også hvordan vi kan utføre valideringer basert på regex eller forretningslogikkregler.

Som alltid kan all koden som brukes her, bli funnet på GitHub.

streamalism.org