streamalism.org

1. סקירה כללית

במדריך זה נלמד כיצד להשתמש בספריית XStream לסידור אובייקטים של Java ל- XML.

2. תכונות

ישנם לא מעט יתרונות מעניינים לשימוש ב- XStream לסידור וניתוק מחדש של XML:

• מוגדר כראוי, זה מייצר מאוד נקי XML
• מספק הזדמנויות משמעותיות עבור התאמה אישית של פלט ה- XML
• תמיכה ל גרפי אובייקט, כולל הפניות מעגליות
• עבור רוב מקרי השימוש, מופע ה- XStream הוא חוט בטוח, לאחר הגדרתו (יש אזהרות בעת שימוש בהערות)
• הודעות ברורות מסופקות במהלך טיפול בחריגים כדי לעזור באבחון בעיות
• החל מגרסת 1.4.7, יש לנו מאפייני אבטחה זמין כדי לאפשר סדרת סדרות מסוגים מסוימים

3. הגדרת פרויקט

על מנת להשתמש ב- XStream בפרויקט שלנו נוסיף את התלות הבאה של Maven:

 com.thoughtworks.xstream xstream 1.4.9 

4. שימוש בסיסי

ה XStream class הוא חזית עבור ה- API. בעת יצירת מופע של XStream, עלינו לטפל גם בבעיות בטיחות חוטים:

XStream xstream = XStream חדש ();

לאחר יצירת מופע ותצורתו, ייתכן שהוא ישותף על פני מספר שרשורים לביצוע / ביטול פרסום, אלא אם כן אתה מאפשר עיבוד הערות.

4.1. נהגים

מספר נהגים נתמכים, כגון DomDriver, StaxDriver, XppDriver, ועוד. מנהלי התקנים אלה מאפיינים ביצועים ומשתמשים שונים.

הנהג XPP3 משמש כברירת מחדל, אך כמובן שנוכל לשנות את מנהל ההתקן בקלות:

XStream xstream = XStream חדש (StaxDriver חדש ()); 

4.2. יצירת XML

נתחיל בהגדרת POJO פשוט עבור - צרכן:

לקוח בכיתה ציבורית {פרטי מחרוזת שם פרטי; שם משפחה פרטי מחרוזת; תאריך תאריך פרטי; // קונסטרוקטור סטנדרטי, סטרים וגטרים}

בואו ניצור כעת ייצוג XML של האובייקט:

לקוח לקוח = לקוח חדש ("ג'ון", "איילה", תאריך חדש ()); מחרוזת dataXml = xstream.toXML (לקוח);

באמצעות הגדרות ברירת המחדל מופקת הפלט הבא:

 ג'ון דו 1986-02-14 03: 46: 16.381 UTC 

מהפלט הזה אנו יכולים לראות בבירור שהתג המכיל משתמש בשם הכיתה המלא צרכן כברירת מחדל.

ישנן סיבות רבות לכך שנחליט שהתנהגות ברירת המחדל אינה מתאימה לצרכינו. לדוגמה, אולי לא יהיה לנו נעים לחשוף את מבנה החבילה של היישום שלנו. כמו כן, ה- XML ​​שנוצר ארוך יותר באופן משמעותי.

5. כינויים

An כינוי הוא שם שאנחנו רוצים להשתמש בו עבור אלמנטים במקום להשתמש בשמות ברירת מחדל.

לדוגמא, אנו יכולים להחליף com.baeldung.pojo.Customer עם צרכן על ידי רישום כינוי ל- צרכן מעמד. אנו יכולים גם להוסיף כינויים לתכונות של מחלקה. על ידי שימוש בכינויים, אנו יכולים להפוך את פלט ה- XML ​​שלנו לקריא יותר ופחות ספציפי ל- Java.

5.1. כינויים בכיתות

כינויים יכולים להירשם באופן פרוגרמטי או באמצעות הערות.

בואו נעיר עכשיו את שלנו צרכן כיתה עם @XStreamAlias:

@XStreamAlias ​​("לקוח")

כעת עלינו להגדיר את המופע שלנו לשימוש בהערה זו:

xstream.processAnnotations (Customer.class);

לחלופין, אם ברצוננו להגדיר כינוי תכנותי, נוכל להשתמש בקוד שלמטה:

xstream.alias ("לקוח", Customer.class);

בין אם משתמשים בכינוי או בתצורה הפרוגרמטית, הפלט עבור a צרכן האובייקט יהיה הרבה יותר נקי:

 ג'ון דו 1986-02-14 03: 46: 16.381 UTC 

5.2. כינויים בשטח

אנו יכולים גם להוסיף כינויים לשדות באמצעות אותה הערה המשמשת לשיעורי aliasing. למשל, אם היינו רוצים את התחום שם פרטי להחליף ב fn בייצוג ה- XML ​​נוכל להשתמש בהערה הבאה:

@XStreamAlias ​​("fn") פרטי מחרוזת שם פרטי;

לחלופין, אנו יכולים להשיג את אותה מטרה באופן פרוגרמטי:

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

ה aliasField השיטה מקבלת שלושה טיעונים: הכינוי שאנחנו רוצים להשתמש בו, המחלקה בה מוגדר המאפיין ושם המאפיין שאנחנו רוצים לכינוי.

בכל שיטה בה משתמשים הפלט זהה:

 ג'ון דו 1986-02-14 03: 46: 16.381 UTC 

5.3. כינויים ברירת מחדל

יש כמה כינויים שנרשמו מראש לשיעורים - הנה כמה מאלה:

כינוי ("צף", Float.class); כינוי ("תאריך", Date.class); כינוי ("לוח שנה גרגוריאני", Calendar.class); כינוי ("url", URL.class); כינוי ("רשימה", List.class); כינוי ("locale", Locale.class); כינוי ("מטבע", Currency.class);

6. אוספים

כעת נוסיף רשימה של ContactDetails בתוך ה צרכן מעמד.

רשימת פרטי contactDetailsList;

עם הגדרות ברירת מחדל לטיפול באיסוף, זו הפלט:

 ג'ון דו 14/02/1986 04: 14: 05.874 UTC 6673543265 0124-2460311 4676543565 0120-223312 

נניח שאנחנו צריכים להשמיט את ה- contactDetailsList תגי הורים, ואנחנו רק רוצים כל אחד ContactDetails אלמנט להיות ילד של צרכן אֵלֵמֶנט. הבה נשנה את הדוגמה שלנו שוב:

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

כעת, כאשר ה- XML ​​נוצר, תגי השורש מושמטים, וכתוצאה מכך ה- XML ​​להלן:

 ג'ון דו 14/02/1986 04: 14: 20.541 UTC 6673543265 0124-2460311 4676543565 0120-223312 

ניתן להשיג את אותו הדבר באמצעות הערות:

@XStream רשימת פרטים פרטית contactDetailsList;

7. ממירים

XStream משתמש במפה של מֵמִיר מקרים שלכל אחד מהם אסטרטגיית המרה משלו. אלה ממירים נתונים שסופקו לפורמט מסוים ב- XML ​​ובחזרה.

בנוסף לשימוש בממירי ברירת המחדל, אנו יכולים לשנות את ברירות המחדל או לרשום ממירים מותאמים אישית.

7.1. שינוי ממיר קיים

נניח שלא היינו מרוצים מהדרך dob נוצרו תגיםבאמצעות הגדרות ברירת המחדל. אנו יכולים לשנות את הממיר המותאם אישית עבור תַאֲרִיך מסופק על ידי XStream (ממיר תאריך):

xstream.registerConverter (DateConverter חדש ("dd-MM-yyyy", null));

האמור לעיל יפיק את התפוקה ב-dd-MM-yyyyפורמט:

 ג'ון דו 14-02-1986 

7.2. ממירים מותאמים אישית

אנו יכולים גם ליצור ממיר מותאם אישית להשגת אותה פלט כמו בסעיף הקודם:

מחלקה ציבורית MyDateConverter מיישם ממיר {פרטי SimpleDateFormat מעצב = SimpleDateFormat חדש ("dd-MM-yyyy"); @Override can boolean publicConvert (clazz class) {return Date.class.isAssignableFrom (clazz); } @Override public void marshal (ערך אובייקט, כותב HierarchicalStreamWriter, MarshallingContext arg2) {תאריך תאריך = (תאריך) ערך; writer.setValue (formatter.format (תאריך)); } // שיטות אחרות}

לבסוף, אנו רושמים את שלנו MyDateConverter כיתה להלן:

xstream.registerConverter (MyDateConverter חדש ());

אנו יכולים גם ליצור ממירים המיישמים את ה- ממיר SingleValueConverter ממשק, שנועד להמיר אובייקט למחרוזת.

מחלקה ציבורית MySingleValueConverter מיישמת SingleValueConverter {@Override can boolean publicConvert (Class clazz) {return Customer.class.isAssignableFrom (clazz); } @Override ציבורי מחרוזת toString (אובייקט אובייקט) {מעצב SimpleDateFormat = חדש SimpleDateFormat ("dd-MM-yyyy"); תאריך תאריך = ((לקוח) obj) .getDob (); return ((Customer) obj) .getFirstName () + "," + ((Customer) obj) .getLastName () + "," + formatter.format (תאריך); } // שיטות אחרות}

לבסוף, אנו נרשמים MySingleValueConverter:

xstream.registerConverter (MySingleValueConverter חדש ()); 

באמצעות MySingleValueConverter, פלט ה- XML ​​עבור a צרכן הוא כדלקמן:

ג'ון, איילה, 14-02-1986

7.3. ממיר עדיפות

בעת ההרשמה מֵמִיר אובייקטים, ניתן גם לקבוע את רמת העדיפות שלהם.

מג'אוודוקס XStream:

ניתן לרשום את הממירים בעדיפות מפורשת. כברירת מחדל הם רשומים ב- XStream.PRIORITY_NORMAL. ממירים בעלי עדיפות זהה ישמשו ברצף ההפוך בו נרשמו. ממיר ברירת המחדל, כלומר הממיר שישמש אם אין ממיר רשום אחר מתאים, ניתן לרשום עם עדיפות XStream.PRIORITY_VERY_LOW. XStream משתמש כברירת מחדל ב- ReflectionConverter כממיר החזרה.

ה- API מספק מספר ערכי עדיפות בשם:

סופי סטטי פרטי int int PRIORITY_NORMAL = 0; סיום פרטי סטטי פרטי PRIORITY_LOW = -10; גמר פרטי סטטי פרטי PRIORITY_VERY_LOW = -20; 

8.השמטת שדות

אנו יכולים להשמיט שדות מה- XML ​​שנוצר באמצעות הערות או תצורה פרוגרמטית. על מנת להשמיט שדה באמצעות הערה, אנו פשוט מיישמים את @XStreamOmitField ביאור לתחום המדובר:

@XStreamOmitField מחרוזת פרטית שם פרטי;

על מנת להשמיט את השדה באופן פרוגרמטי, אנו משתמשים בשיטה הבאה:

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

בכל שיטה שנבחר, הפלט זהה:

 איילה 14-02-1986 

9. שדות תכונה

לפעמים אנו עשויים לרצות לסדר שדה כתכונה של אלמנט ולא כאלמנט עצמו. נניח שנוסיף א סוג המגע שדה:

פרטי מחרוזת contactType;

אם אנחנו רוצים להגדיר סוג המגע כתכונת XML, אנו יכולים להשתמש ב- @XStreamAsAttribute ביאור:

@XStreamAsAttribute פרטי מחרוזת contactType; 

לחלופין, אנו יכולים להשיג את אותה מטרה באופן פרוגרמטי:

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

התפוקה של אחת מהשיטות לעיל זהה:

 6673543265 0124-2460311 

10. מקביליות

מודל העיבוד של XStream מציב כמה אתגרים. לאחר הגדרת המופע, הוא בטוח לשרשור.

חשוב לציין כי עיבוד ביאורים משנה את התצורה ממש לפני ביצוע פעולות / ביטול פרסום. וכך - אם אנו דורשים להגדיר את המופע תוך כדי טיסה באמצעות הערות, זה בדרך כלל רעיון טוב להשתמש בתכונה נפרדת XStream מופע עבור כל שרשור.

11. מסקנה

במאמר זה סקרנו את יסודות השימוש ב- XStream להמרת אובייקטים ל- XML. למדנו גם על התאמות אישיות שבהן אנו יכולים להשתמש כדי להבטיח שפלט ה- XML ​​עונה על הצרכים שלנו. לבסוף, בדקנו בעיות בטיחות חוטים ביאורים.

במאמר הבא בסדרה זו, נלמד על המרת XML לאובייקטים של Java.

ניתן להוריד את קוד המקור השלם למאמר זה ממאגר GitHub המקושר.