streamalism.org

1. Prehľad

V tomto tutoriále sa dozvieme, ako používať knižnicu XStream na serializáciu objektov Java na XML.

2. Funkcie

Existuje mnoho zaujímavých výhod použitia programu XStream na serializáciu a deserializáciu XML:

• Pri správnej konfigurácii vytvára veľmi dobre čistý XML
• Poskytuje významné príležitosti pre prispôsobenie výstupu XML
• Podpora pre objektové grafy, vrátane cyklických odkazov
• Pre väčšinu prípadov použitia je inštancia XStream bezpečné pre vlákna, po nakonfigurovaní (pri používaní anotácií existujú výhrady)
• Jasné správy sú poskytované počas spracovanie výnimiek pomôcť diagnostikovať problémy
• Počnúc verziou 1.4.7 máme bezpečnostné prvky k dispozícii na zakázanie serializácie určitých typov

3. Nastavenie projektu

Aby sme mohli v našom projekte použiť XStream, pridáme nasledujúcu závislosť Maven:

 com. thoughtworks.xstream xstream 1.4.9 

4. Základné použitie

The XStream triedy je fasáda pre API. Pri vytváraní inštancie XStream, musíme sa postarať aj o bezpečnosť vlákien:

XStream xstream = nový XStream ();

Keď je inštancia vytvorená a nakonfigurovaná, môže byť zdieľaná vo viacerých vláknach na zhromažďovanie a zrušenie zdieľania, pokiaľ nepovolíte spracovanie anotácií.

4.1. Vodiči

Podporovaných je niekoľko ovládačov, ako napr DomDriver, StaxDriver, XppDriver, a viac. Tieto ovládače majú odlišné charakteristiky výkonu a využívania zdrojov.

Ovládač XPP3 sa používa predvolene, ale samozrejme môžeme ovládač ľahko zmeniť:

XStream xstream = nový XStream (nový StaxDriver ()); 

4.2. Generuje sa XML

Začnime definovaním jednoduchého POJO pre - Zákazník:

verejná trieda Zákazník {private String firstName; private String priezvisko; súkromné ​​Dátum nar; // štandardný konštruktor, nastavovatelia a getri}

Poďme teraz vygenerovať XML reprezentáciu objektu:

Zákazník zákazník = nový zákazník („John“, „Doe“, nový dátum ()); Reťazec dataXml = xstream.toXML (zákazník);

Pri použití predvolených nastavení sa vytvorí nasledujúci výstup:

 John Doe 1986-02-14 03: 46: 16.381 UTC 

Z tohto výstupu jasne vidíme, že značka obsahujúca používa úplný názov triedy Zákazník predvolene.

Existuje veľa dôvodov, prečo by sme sa mohli rozhodnúť, že predvolené správanie nevyhovuje našim potrebám. Napríklad nám nemusí byť príjemné odhaľovať štruktúru balíka našej aplikácie. Taktiež vygenerovaný XML je podstatne dlhší.

5. Aliasy

An alias je názov, ktorý by sme chceli použiť pre prvky namiesto použitia predvolených názvov.

Napríklad môžeme nahradiť com.baeldung.pojo.Zákazník s zákazník registráciou aliasu pre Zákazník trieda. Môžeme tiež pridať aliasy pre vlastnosti triedy. Použitím aliasov môžeme dosiahnuť, aby bol náš výstup XML oveľa čitateľnejší a menej špecifický pre Javu.

5.1. Aliasy triedy

Aliasy je možné registrovať programovo alebo pomocou anotácií.

Poďme teraz komentovať naše Zákazník trieda s @XStreamAlias:

@XStreamAlias ​​(„zákazník“)

Teraz musíme nakonfigurovať našu inštanciu tak, aby používala túto anotáciu:

xstream.processAnnotations (Customer.class);

Prípadne, ak si prajeme programovo nakonfigurovať alias, môžeme použiť nasledujúci kód:

xstream.alias ("zákazník", Customer.class);

Či už použijete alias alebo programovú konfiguráciu, výstup pre a Zákazník objekt bude oveľa čistejší:

 John Doe 1986-02-14 03: 46: 16.381 UTC 

5.2. Poľné prezývky

Môžeme tiež pridať aliasy pre polia pomocou rovnakej anotácie, ktorá sa použila pre triedy aliasingu. Napríklad keby sme chceli pole krstné meno má byť nahradený fn v reprezentácii XML by sme mohli použiť nasledujúcu anotáciu:

@XStreamAlias ​​("fn") súkromný reťazec meno;

Rovnaký cieľ môžeme dosiahnuť aj programovo:

xstream.aliasField ("fn", Customer.class, "meno");

The aliasField metóda akceptuje tri argumenty: alias, ktorý chceme použiť, triedu, v ktorej je vlastnosť definovaná, a názov vlastnosti, ktorú chceme alias použiť.

Bez ohľadu na to, ktorá metóda sa použije, výstup je rovnaký:

 John Doe 1986-02-14 03: 46: 16.381 UTC 

5.3. Predvolené aliasy

Pre triedy je vopred zaregistrovaných niekoľko aliasov. Tu je niekoľko z nich:

alias ("float", Float.class); alias ("dátum", Date.class); alias ("gregoriánsky kalendár", Calendar.class); alias ("url", URL.class); alias ("zoznam", List.class); alias ("locale", Locale.class); alias ("mena", Currency.class);

6. Zbierky

Teraz pridáme zoznam Kontaktné údaje vnútri Zákazník trieda.

súkromný zoznam contactDetailsList;

Pri predvolenom nastavení spracovania zberu je toto výstup:

 John Doe 1986-02-14 04:14: 05.874 UTC 6673543265 0124-2460311 4676543565 0120-223312 

Predpokladajme, že musíme vynechať contactDetailsList rodičovské značky, a my jednoducho chceme každého Kontaktné údaje prvkom byť dieťaťom zákazník element. Upravme náš príklad znova:

xstream.addImplicitCollection (Customer.class, "contactDetailsList");

Teraz, keď je generovaný XML, sú koreňové značky vynechané, čo má za následok XML nižšie:

 John Doe 1986-02-14 04:14: 20.541 UTC 6673543265 0124-2460311 4676543565 0120-223312 

To isté možno dosiahnuť aj pomocou anotácií:

@XStreamImplicit private List contactDetailsList;

7. Prevodníky

XStream používa mapu Prevádzač inštancie, každý s vlastnou stratégiou konverzie. Tieto prevádzajú dodané údaje do konkrétneho formátu v XML a späť.

Okrem použitia predvolených prevádzačov môžeme upravovať predvolené hodnoty alebo registrovať vlastné prevádzače.

7.1. Úprava existujúceho prevádzača

Predpokladajme, že sme neboli spokojní s tým, ako nar boli vygenerované značkypomocou predvolených nastavení. Môžeme upraviť vlastný prevádzač pre Dátum poskytuje XStream (DateConverter):

xstream.registerConverter (nový DateConverter ("dd-MM-rrrr", null));

Vyššie uvedené vyprodukuje výstup v „dd-MM-rrrr”Formát:

 John Doe 14-02-1986 

7.2. Vlastné prevádzače

Môžeme tiež vytvoriť vlastný prevádzač na dosiahnutie rovnakého výstupu ako v predchádzajúcej časti:

public class MyDateConverter implementuje Converter {private SimpleDateFormat formatter = nový SimpleDateFormat ("dd-MM-rrrr"); @Override public boolean canConvert (Class clazz) {return Date.class.isAssignableFrom (clazz); } @Override public void marshal (Object value, HierarchicalStreamWriter writer, MarshallingContext arg2) {Date date = (Date) value; writer.setValue (formatter.format (dátum)); } // ďalšie metódy}

Nakoniec zaregistrujeme naše MyDateConverter trieda uvedená nižšie:

xstream.registerConverter (nový MyDateConverter ());

Môžeme tiež vytvoriť prevádzače, ktoré implementujú SingleValueConverter rozhranie, ktoré je určené na prevod objektu na reťazec.

public class MySingleValueConverter implementuje SingleValueConverter {@Override public boolean canConvert (Class clazz) {return Customer.class.isAssignableFrom (clazz); } @Override public String toString (Object obj) {SimpleDateFormat formatter = new SimpleDateFormat ("dd-MM-rrrr"); Dátum dátum = (((Zákazník) obj) .getDob (); return ((Customer) obj) .getFirstName () + "," + ((Customer) obj) .getLastName () + "," + formatter.format (date); } // ďalšie metódy}

Nakoniec sa zaregistrujeme MySingleValueConverter:

xstream.registerConverter (nový MySingleValueConverter ()); 

Použitím MySingleValueConverter, výstup XML pre a Zákazník je nasledujúci:

John, Doe, 14-02-1986

7.3. Priorita konvertora

Pri registrácii Prevádzač objektov je možné nastaviť aj ich prioritu.

Z javadocs XStream:

Prevodníky je možné zaregistrovať s výslovnou prioritou. Predvolene sú zaregistrované na serveri XStream.PRIORITY_NORMAL. Prevodníky s rovnakou prioritou sa použijú v opačnom poradí, v akom boli zaregistrované. Predvolený prevodník, t. J. Prevodník, ktorý sa použije, ak nie je vhodný iný registrovaný prevodník, je možné zaregistrovať s prioritou XStream.PRIORITY_VERY_LOW. XStream štandardne používa ReflectionConverter ako záložný prevodník.

API poskytuje niekoľko pomenovaných hodnôt priority:

súkromný statický konečný int PRIORITY_NORMAL = 0; private static final int PRIORITY_LOW = -10; private static final int PRIORITY_VERY_LOW = -20; 

8.Vynechané polia

Z nášho generovaného XML môžeme vynechať polia buď pomocou anotácií, alebo programovej konfigurácie. Aby sme mohli pole pomocou anotácie vynechať, jednoducho použijeme znak @XStreamOmitField anotácia k predmetnému poľu:

@XStreamOmitField súkromný reťazec firstName;

Aby sme toto pole programovo vynechali, použijeme nasledujúcu metódu:

xstream.omitField (Customer.class, "meno");

Nech už vyberieme ktorúkoľvek metódu, výstup je rovnaký:

 Srnka 14-02-1986 

9. Polia atribútov

Niekedy by sme mohli chcieť serializovať pole ako atribút prvku skôr ako ako samotný prvok. Predpokladajme, že pridáme a contactType lúka:

private String contactType;

Ak chceme nastaviť contactType ako atribút XML môžeme použiť @XStreamAsAttribute anotácia:

@XStreamAsAttribute private String contactType; 

Rovnaký cieľ môžeme dosiahnuť aj programovo:

xstream.useAttributeFor (ContactDetails.class, "contactType");

Výstup jednej z vyššie uvedených metód je rovnaký:

 6673543265 0124-2460311 

10. Súbežnosť

Model spracovania XStream predstavuje niektoré výzvy. Po nakonfigurovaní inštancie je zabezpečená pomocou vlákien.

Je dôležité si uvedomiť, že spracovanie anotácií upravuje konfiguráciu tesne pred zaradením / zrušením zaradenia. A tak - ak požadujeme, aby bola inštancia konfigurovaná za chodu pomocou anotácií, je zvyčajne dobré použiť samostatný XStream inštancia pre každé vlákno.

11. Záver

V tomto článku sme sa venovali základom používania XStreamu na prevod objektov na XML. Dozvedeli sme sa tiež o prispôsobeniach, ktoré môžeme použiť na zabezpečenie toho, aby výstup XML zodpovedal našim potrebám. Nakoniec sme sa pozreli na problémy s bezpečnosťou vlákien pomocou anotácií.

V nasledujúcom článku v tejto sérii sa dozvieme o konverzii XML späť na objekty Java.

Celý zdrojový kód tohto článku je možné stiahnuť z prepojeného úložiska GitHub.