streamalism.org

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

JSON-LD הוא פורמט RDF מבוסס JSON לייצוג נתונים מקושרים. זה מאפשר להרחיב אובייקטים JSON קיימים עם יכולות hypermedia; במילים אחרות, היכולת להכיל קישורים באופן קריא למכונה.

במדריך זה, אנו נסתכל על כמה אפשרויות מבוססות ג'קסון לסידור ולערוק מחדש של פורמט JSON-LD ישירות ל- POJOs. אנו נסקור גם את המושגים הבסיסיים של JSON-LD שיאפשרו לנו להבין את הדוגמאות.

2. מושגי יסוד

בפעם הראשונה שאנחנו רואים מסמך JSON-LD, אנו שמים לב שכמה שמות חברים מתחילים עם ה- @ אופי. אלה מילות מפתח של JSON-LD, והערכים שלהם עוזרים לנו להבין את שאר המסמך.

כדי לנווט בעולם JSON-LD ולהבין הדרכה זו, עלינו להיות מודעים לארבע מילות מפתח:

• @הֶקשֵׁר הוא התיאור של אובייקט JSON המכיל מפת ערך מפתח של כל הדרוש לפרשנות המסמך
• @vocab הוא מפתח אפשרי ב @הֶקשֵׁר המציג אוצר מילים ברירת מחדל להכנת @הֶקשֵׁר חפץ קצר בהרבה
• @תְעוּדַת זֶהוּת היא מילת המפתח לזיהוי קישורים כמאפיין משאבים לייצוג הקישור הישיר למשאב עצמו או כ- @סוּג ערך לסימון שדה כלשהו כקישור
• @סוּג היא מילת המפתח לזיהוי סוגי משאבים ברמת המשאב או ב @הֶקשֵׁר; למשל, להגדרת סוג המשאבים המוטבעים

3. סידור ב- Java

לפני שנמשיך, עלינו להסתכל בהדרכות הקודמות שלנו כדי לרענן את זיכרוננו בג'קסון ObjectMapper, הערות ג'קסון, וג'קסון סריאליזרים בהתאמה אישית.

מכיוון שכבר הכרנו את ג'קסון, נוכל להבין שנוכל לסדר בקלות שני שדות מותאמים אישית בכל POJO @תְעוּדַת זֶהוּת ו @סוּג משתמש ב @JsonProperty ביאור. למרות זאת, כותב את @הֶקשֵׁר ביד יכול להיות הרבה עבודה וגם נוטה לטעויות.

לכן, כדי להימנע מגישה נוטה לשגיאה זו, בואו נסתכל מקרוב על שתי ספריות בהן נוכל להשתמש @הֶקשֵׁר דוֹר. למרבה הצער, אף אחד מהם אינו מסוגל ליצור את כל התכונות של JSON-LD, אך נבחן את החסרונות שלהם גם בהמשך.

4. סדרת סדר עם ג'קסון ג'סונלד

ג'קסון ג'ונסלד הוא מודול ג'קסון המאפשר הערה של POJOs בצורה נוחה ליצירת מסמכי JSON-LD.

4.1. תלות Maven

ראשית, בואו נוסיף ג'קסון ג'סונלד כתלות ב- pom.xml:

 com.io-informatics.oss jackson-jsonld 0.1.1 

4.2. דוגמא

לאחר מכן, בואו ליצור את הדוגמה שלנו POJO ונציין זאת עבור @הֶקשֵׁר דוֹר:

@JsonldResource @JsonldNamespace (name = "s", uri = "//schema.org/") @JsonldType ("s: Person") @JsonldLink (rel = "s: יודע", name = "יודע", href = "//example.com/person/2345") אדם בכיתה ציבורית {@JsonldId מזהה מחרוזת פרטי; @JsonldProperty ("s: name") שם פרטי מחרוזת; // קונסטרוקטור, גטרס, סטרים}

בואו לפרק את השלבים להבנת מה עשינו:

• עם @JsonldResource סימנו את POJO לעיבוד כמשאב JSON-LD
• בתוך ה @JsonldNamespace הגדרנו קצרנות לאוצר המילים בו אנו רוצים להשתמש
• הפרמטר שציינו בו @JsonldType יהפוך ל @סוּג של המשאב
• השתמשנו ב- @JsonldLink ביאור להוספת קישורים למשאב. בעת עיבודו, ה- שֵׁם הפרמטר ישמש כשם שדה ויתווסף כמפתח ל- @הֶקשֵׁר.href יהיה ערך השדה ו rel יהיה הערך הממופה ב- @הֶקשֵׁר
• השדה שסימנו איתו @JsonldId יהפוך ל @תְעוּדַת זֶהוּת של המשאב
• הפרמטר שציינו בו @JsonldProperty יהפוך לערך הממופה לשם השדה ב- @הֶקשֵׁר

לאחר מכן, בואו ניצור את מסמך JSON-LD.

ראשית, עלינו לרשום את JsonldModule בתוך ה ObjectMapper. מודול זה מכיל מותאם אישית Serializer שג'קסון ישתמש בהם עבור POJO המסומנים ב- @JsonldResource ביאור.

לאחר מכן, נמשיך ונשתמש ב- ObjectMapper להפקת מסמך JSON-LD:

ObjectMapper objectMapper = ObjectMapper חדש (); objectMapper.registerModule (חדש JsonldModule ()); אדם אדם = אדם חדש ("// example.com/person/1234", "שם לדוגמא"); מחרוזת personJsonLd = objectMapper.writeValueAsString (אדם);

כתוצאה מכך, personJsonLd המשתנה אמור לכלול כעת:

{"@type": "s: Person", "@context": {"s": "//schema.org/", "name": "s: name", "יודע": {"@id" : "s: יודע", "@type": "@id"}}, "name": "שם לדוגמא", "@id": "//example.com/person/1234", "יודע": " //example.com/person/2345 "}

4.3. שיקולים

לפני שנבחר בספריה זו לפרויקט, עלינו לשקול את הדברים הבאים:

• משתמש ב @vocab מילת המפתח אינה אפשרית, לכן נצטרך להשתמש ב- @JsonldNamespace לספק תמצית לפיתרון שמות שדות או לכתוב את מזהה המשאבים הבינלאומי המלא (IRI) בכל פעם
• אנו יכולים להגדיר קישורים רק בזמן הקומפילציה, ולכן על מנת להוסיף זמן ריצה של קישור, נצטרך להשתמש בבבואה כדי לשנות את הפרמטר ההוא בהערה.

5. סידור עם הידרה ג'סונלד

Hydra-Jsonld הוא מודול של ספריית Hydra-Java, שנבנה בעיקר כדי לאפשר יצירת תגובה נוחה של JSON-LD ליישומי Spring. היא משתמשת באוצר המילים של הידרה כדי להפוך את מסמכי JSON-LD לאקספרסיביים יותר.

למרות זאת, מודול ההידרה-ג'סונלד מכיל ג'קסון Serializer וכמה הערות שנוכל להשתמש בהן כדי ליצור מסמכי JSON-LD מחוץ למסגרת האביב.

5.1. תלות Maven

ראשית, בואו נוסיף את התלות עבור הידרה-ג'סונלד אל ה pom.xml:

 de.escalon.hypermedia hydra-jsonld 0.4.2 

5.2. דוגמא

שנית, בואו נרשום את ה- POJO שלנו עבור @הֶקשֵׁר דוֹר.

Hydra-Jsonld מייצר אוטומטית ברירת מחדל @הֶקשֵׁר ללא צורך בהערות. אם אנו מרוצים מהברירות המחדל, עלינו רק להוסיף את ה- @תְעוּדַת זֶהוּת כדי לקבל מסמך JSON-LD תקף.

אוצר המילים המוגדר כברירת מחדל יהיה אוצר המילים schema.org, ה- @סוּג הג'אווה מעמד שם, והמאפיינים הציבוריים של POJO ייכללו כולם במסמך JSON-LD שהתקבל.

בדוגמה זו, בואו נעקוף את ברירות המחדל הללו עם ערכים מותאמים אישית:

@Vocab ("// example.com/vocab/") @Expose ("אדם") אדם בכיתה ציבורית {מזהה מחרוזת פרטי; שם מחרוזת פרטי; // constructor @JsonProperty ("@ id") מחרוזת ציבורית getId () {id מזהה; } @Expose ("fullName") ציבורי מחרוזת getName () {return name; }}

שוב, בואו נסתכל מקרוב על הצעדים המעורבים:

• בהשוואה לדוגמא של ג'קסון ג'סונלד, השארנו את ה- יודע שדה מ- POJO שלנו בגלל המגבלות של Hydra-Jsonld מחוץ למסגרת האביב
• קבענו את אוצר המילים המועדף עלינו עם @Vocab ביאור
• באמצעות @לַחשׂוֹף ביאור על הכיתה, הגדרנו משאב אחר @סוּג
• השתמשנו באותה מידה @לַחשׂוֹף ביאור על נכס כדי להגדיר את המיפוי שלו לערך מותאם אישית ב- @הֶקשֵׁר
• ליצירת ה- @תְעוּדַת זֶהוּת מנכס, השתמשנו ב @JsonProperty ביאור מג'קסון

לאחר מכן, בואו להגדיר מופע של ג'קסון מודול שנוכל להירשם ב ObjectMapper. נוסיף את JacksonHydraSerializer כ BeanSerializerModifier אז זה יכול להיות מיושם על כל POJOs כי הם בסידרה:

SimpleModule getJacksonHydraSerializerModule () {להחזיר SimpleModule חדש () {@Override public void setupModule (SetupContext context) {super.setupModule (context); context.addBeanSerializerModifier (חדש BeanSerializerModifier () {@Override ציבורי JsonSerializer modifySerializer (SerializationConfig config, BeanDescription beanDesc, JsonSerializer serializer) {if (serializer instance of BeanSerializerBase) {להחזיר serializerBase; }); }}; }

אז נרשום את ה- מודול ב ObjectMapper ולהשתמש בו. אנחנו צריכים גם להגדיר את ObjectMapper לכלול רק שאינם-ריק ערכים להפקת מסמך JSON-LD תקף:

ObjectMapper objectMapper = ObjectMapper חדש (); objectMapper.registerModule (getJacksonHydraSerializerModule ()); objectMapper.setSerializationInclusion (JsonInclude.Include.NON_NULL); אדם אדם = אדם חדש ("// example.com/person/1234", "שם לדוגמא"); מחרוזת personJsonLd = objectMapper.writeValueAsString (אדם);

עכשיו ה personJsonLd המשתנה צריך להכיל:

{"@context": {"@vocab": "//example.com/vocab/", "name": "fullName"}, "@type": "person", "name": "שם לדוגמא", "@id": "//example.com/person/1234"}

5.3. שיקולים

למרות שניתן מבחינה טכנית להשתמש ב- Hydra-Jsonld מחוץ למסגרת האביב, הוא תוכנן במקור לשימוש עם Spring-HATEOAS. כתוצאה מכך, אין דרך ליצור קישורים עם הערות כפי שראינו בג'קסון ג'סונלד. מצד שני, הם נוצרים עבור כמה שיעורים ספציפיים לאביב באופן אוטומטי.

לפני שנבחר בספריה זו לפרויקט, עלינו לשקול את הדברים הבאים:

• השימוש בו עם Spring Framework יאפשר תכונות נוספות
• אין דרך קלה ליצור קישורים אם איננו משתמשים במסגרת האביב
• איננו יכולים להשבית את השימוש ב- @vocab, אנחנו יכולים רק לעקוף את זה

6. התפטרות עם Jsonld-Java וג'קסון

Jsonld-Java הוא יישום ה- Java של המפרט ו- API של JSON-LD 1.0, שלמרבה הצער אינו הגרסה האחרונה.

ליישום של גרסת המפרט 1.1, עיין בספריית Titanium JSON-LD.

כדי לבטל את הערעור של מסמך JSON-LD, בואו להפוך אותו בעזרת תכונת API של JSON-LD, הנקראת דחיסה, לפורמט שנוכל למפות ל- POJO באמצעותו ObjectMapper.

6.1. תלות Maven

ראשית, בואו נוסיף את התלות עבור jsonld-java:

 com.github.jsonld-java jsonld-java 0.13.0 

6.2. דוגמא

בואו נעבוד עם מסמך JSON-LD זה כקלט שלנו:

{"@context": {"@vocab": "//schema.org/", "יודע": {"@type": "@id"}}, "@type": "אדם", "@id ":" //example.com/person/1234 "," name ":" שם לדוגמא "," יודע ":" //example.com/person/2345 "}

למען הפשטות, נניח שיש לנו את תוכן המסמך ב חוּט משתנה שנקרא קלט JsonLd.

ראשית, בואו נדחס אותו ונמיר אותו בחזרה ל- חוּט:

אובייקט jsonObject = JsonUtils.fromString (inputJsonLd); אובייקט קומפקטי = JsonLdProcessor.compact (jsonObject, HashMap חדש (), JsonLdOptions חדש ()); מחרוזת compactContent = JsonUtils.toString (קומפקטי);

• אנו יכולים לנתח ולכתוב את האובייקט JSON-LD בשיטות מה- JsonUtils, שהוא חלק מספריית Jsonld-Java
• בעת השימוש ב- קוֹמפָּקטִי שיטה, כפרמטר שני אנו יכולים להשתמש ריק מַפָּה. בדרך זו, אלגוריתם הדחיסה ייצר אובייקט JSON פשוט בו נפתרים המפתחות לצורות ה- IRI שלהם

ה קומפקטי תוכן המשתנה צריך להכיל:

{"@id": "//example.com/person/1234", "@type": "//schema.org/Person", "//schema.org/knows": {"@id": " //example.com/person/2345 "}," //schema.org/name ":" שם לדוגמא "}

שנית, בואו נתאים את ה- POJO שלנו להערות ג'קסון כך שיתאימו למבנה מסמך כזה:

@JsonIgnoreProperties (ignoreUnknown = true) אדם בכיתה ציבורית {@JsonProperty ("@ id") מזהה מחרוזת פרטי; @JsonProperty ("// schema.org/name") שם מחרוזת פרטי; @JsonProperty ("// schema.org/knows") קישור פרטי יודע; // בונים, גטרים, קובעים מחלקה סטטית ציבורית קישור {@JsonProperty ("@ id") פרטי מזהה מחרוזת; // בונים, גטרים, סטרים}}

ולסיום, בואו נמפה את ה- JSON-LD ל- POJO:

ObjectMapper objectMapper = ObjectMapper חדש (); אדם אדם = objectMapper.readValue (compactContent, Person.class);

7. מסקנה

במאמר זה, בדקנו שתי ספריות מבוססות ג'קסון לצורך סדרת POJO למסמך JSON-LD, ודרך אחת לנטרל מחדש את JSON-LD ל- POJO.

כפי שהדגשנו, בשתי ספריות הסדרה יש חסרונות שעלינו לקחת בחשבון לפני השימוש בהן. אם נצטרך להשתמש בתכונות רבות יותר של JSON-LD מכפי שספריות אלו יכולות להציע, נוכל לגשת ליצירת המסמך שלנו באמצעות ספריית RDF עם פורמט פלט JSON-LD.

כרגיל, ניתן למצוא את קוד המקור ב- GitHub.