Hypermedia sorosítás JSON-LD-vel

1. Áttekintés

A JSON-LD egy JSON-alapú RDF formátum a kapcsolt adatok ábrázolására. Lehetővé teszi a meglévő JSON objektumok kibővítését hipermédia képességekkel; más szavakkal, a linkek géppel olvasható módon történő tárolásának képessége.

Ebben az oktatóanyagban megnézünk néhány Jackson-alapú lehetőséget a JSON-LD formátum sorosítására és deszerializálására közvetlenül POJO-kba. Kitérünk a JSON-LD alapfogalmaira is, amelyek lehetővé teszik számunkra a példák megértését.

2. Alapfogalmak

Amikor először látunk egy JSON-LD dokumentumot, észrevesszük, hogy egyes tagnevek a -val kezdődnek @ karakter. Ezek JSON-LD kulcsszavak, és értékeik segítenek megérteni a dokumentum többi részét.

A JSON-LD világában való eligazodáshoz és az oktatóanyag megértéséhez négy kulcsszóval kell tisztában lennünk:

  • @kontextus a JSON objektum leírása, amely kulcsérték-térképet tartalmaz mindarról, ami a dokumentum értelmezéséhez szükséges
  • @vocab egy lehetséges kulcs a @kontextus amely bevezeti az alapértelmezett szókincset a @kontextus a tárgy sokkal rövidebb
  • @id az a kulcsszó, amely a hivatkozásokat vagy erőforrás tulajdonságként azonosítja, amely az erőforráshoz való közvetlen kapcsolatot képviseli, vagy pedig a @típus érték bármely mező hivatkozásként való megjelöléséhez
  • @típus az a kulcsszó, amely az erőforrástípusokat az erőforrás szintjén vagy a @kontextus; például a beágyazott erőforrások típusának meghatározásához

3. Serializálás Java-ban

Mielőtt folytatnánk, meg kell néznünk a korábbi oktatóanyagokat, hogy felfrissítsük a memóriánkat a Jacksonról ObjectMapper, Jackson Annotations és egyedi Jackson Serializers.

Mivel már ismerjük Jackson-t, rájöhetünk, hogy bármely POJO as-ban könnyen sorosíthatunk két egyéni mezőt @id és @típus használni a @JsonProperty annotáció. Azonban, a. írása @kontextus kézzel sok munka lehet és hajlamos a tévedésre is.

Ezért, hogy elkerüljük ezt a hibára hajlamos megközelítést, nézzük meg közelebbről két könyvtárat, amelyekre felhasználhatnánk @kontextus generáció. Sajnos egyikük sem képes a JSON-LD összes funkciójának előállítására, de később megvizsgáljuk hiányosságaikat is.

4. Sorosítás Jackson-Jsonld-szel

A Jackson-Jsonld egy Jackson modul, amely lehetővé teszi a POJO-k feljegyzését a JSON-LD dokumentumok előállításának kényelmes módján.

4.1. Maven-függőségek

Először tegyük hozzá jackson-jsonld mint függőség a pom.xml:

 com.io-informatics.oss jackson-jsonld 0.1.1 

4.2. Példa

Ezután hozzuk létre a POJO példánkat, és jegyezzük fel a következőre: @kontextus generáció:

@JsonldResource @JsonldNamespace (név = "s", uri = "//schema.org/") @JsonldType ("s: Személy") @JsonldLink (rel = "s: tudja", név = "tudja", href = "//example.com/person/2345") public class Person {@JsonldId private String id; @JsonldProperty ("s: név") privát karakterlánc neve; // kivitelező, getters, setters}

Dekonstruáljuk a lépéseket, hogy megértsük mit tettünk:

  • Val vel @JsonldResource a feldolgozásra szánt POJO-t JSON-LD erőforrásként jelöltük meg
  • Ban,-ben @JsonldNamespace rövidítést definiáltunk a használni kívánt szókincs számára
  • A paraméter, amelyet megadtunk @JsonldType lesz az @típus az erőforrás
  • Használtuk a @JsonldLink annotáció linkek hozzáadásához az erőforráshoz. Feldolgozásakor a név paramétert használjuk mezőnévként, és kulcsként hozzáadjuk a @kontextus.href lesz a mező értéke és rel lesz a leképezett értéke a @kontextus
  • A mező, amellyel megjelöltük @JsonldId lesz az @id az erőforrás
  • A paraméter, amelyet megadtunk @JsonldProperty a mező nevéhez leképezett érték lesz a @kontextus

Ezután hozzuk létre a JSON-LD dokumentumot.

Először regisztrálnunk kell a JsonldModule ban,-ben ObjectMapper. Ez a modul egy egyedi elemet tartalmaz Serializer amelyet Jackson a POJO-khoz fog használni @JsonldResource annotáció.

Ezután folytatjuk és használjuk a ObjectMapper a JSON-LD dokumentum előállításához:

ObjectMapper objectMapper = új ObjectMapper (); objectMapper.registerModule (új JsonldModule ()); Személy személy = új Személy ("// pelda.com/szemely/1234", "Példa neve"); Karakterlánc personJsonLd = objectMapper.writeValueAsString (személy);

Ennek eredményeként a personJsonLd a változónak tartalmaznia kell:

{"@type": "s: Személy", "@kontextus": {"s": "//schema.org/", "név": "s: név", "tudja": {"@id" : "s: know", "@type": "@id"}}, "name": "Példa neve", "@id": "//example.com/person/1234", "know": "" //example.com/person/2345 "}

4.3. Megfontolások

Mielőtt ezt a könyvtárat választanánk egy projekthez, fontolóra kell venni a következőket:

  • Használni a @vocab kulcsszó nem lehetséges, ezért vagy a @JsonldNamespace rövidítés biztosítása a mezők nevének feloldásához, vagy minden alkalommal kiírja a teljes nemzetköziesített erőforrás-azonosítót (IRI)
  • A linkeket csak fordítási időben definiálhatjuk, ezért a link futásidejének hozzáadásához tükrözést kell használnunk a paraméter megváltoztatásához az annotációban

5. Serializálás a Hydra-Jsonld céggel

A Hydra-Jsonld a Hydra-Java könyvtár modulja, amelyet elsősorban azért fejlesztettek ki, hogy a tavaszi alkalmazásokhoz kényelmes JSON-LD választ tudjon létrehozni. A Hydra szókincs használatával kifejezőbbé teszi a JSON-LD dokumentumokat.

azonban, a Hydra-Jsonld modul tartalmaz egy Jackson-ot Serializer és néhány feljegyzés, amelyekkel JSON-LD dokumentumokat készíthetünk a tavaszi keretrendszeren kívül.

5.1. Maven-függőségek

Először tegyük hozzá a függőséget hydra-jsonld hoz pom.xml:

 de.escalon.hypermedia hydra-jsonld 0.4.2 

5.2. Példa

Másodszor jegyezzük fel a POJO-t a következőre: @kontextus generáció.

A Hydra-Jsonld automatikusan létrehoz egy alapértelmezett értéket @kontextus anotációk nélkül. Ha elégedettek vagyunk az alapértelmezettel, akkor csak hozzá kell adnunk a @id hogy érvényes JSON-LD dokumentumot kapjon.

Az alapértelmezett szókincs a schema.org szókincs lesz, a @típus a Java osztály név és a POJO nyilvános tulajdonságai mind szerepelnek a létrejövő JSON-LD dokumentumban.

Ebben a példában írjuk felül ezeket az alapértelmezéseket egyéni értékekkel:

@Vocab ("// example.com/vocab/") @Expose ("person") public class Person {private String id; privát karakterlánc neve; // konstruktor @JsonProperty ("@ id") public String getId () {return id; } @Expose ("teljesNév") public String getName () {return name; }}

Ismételjük meg közelebbről a lépéseket:

  • A Jackson-Jsonld példához képest kihagytuk a tudja a POJO-tól a Hydra-Jsonld korlátai miatt a tavaszi kereten kívül
  • A kívánt szókincset a @Vocab annotáció
  • A @Expose felirat az osztályon, más erőforrást állítunk be @típus
  • Ugyanazt használtuk @Expose jelölés egy tulajdonságon, hogy a leképezését egyéni értékre állítsa a @kontextus
  • A @id ingatlanból, a @JsonProperty annotáció Jackson-tól

Ezután konfiguráljuk egy Jackson példányát Modul hogy regisztrálhatunk a ObjectMapper. Hozzáadjuk a JacksonHydraSerializer mint a BeanSerializerModifier így alkalmazható minden sorosított POJO-ra:

SimpleModule getJacksonHydraSerializerModule () {return new SimpleModule () {@Orride public void setupModule (SetupContext context) {super.setupModule (context); context.addBeanSerializerModifier (new BeanSerializerModifier () {@Orride public JsonSerializer modifySerializer (SerializationConfig config, BeanDescription beanDesc, JsonSerializer serializer) {if (serializer BeasSerializerBase)} {serialialer BialSerializerBase} {visszatérés új JacksonHydra; }); }}; }

Akkor regisztráljuk a Modul ban ben ObjectMapper és használja. Be kell állítanunk a ObjectMapper csak a nemnulla értékek érvényes JSON-LD dokumentum előállítása:

ObjectMapper objectMapper = új ObjectMapper (); objectMapper.registerModule (getJacksonHydraSerializerModule ()); objectMapper.setSerializationInclusion (JsonInclude.Include.NON_NULL); Személy személy = új Személy ("// pelda.com/szemely/1234", "Példa neve"); Karakterlánc personJsonLd = objectMapper.writeValueAsString (személy);

Most a personJsonLd a változónak tartalmaznia kell:

{"@kontextus": {"@vocab": "//example.com/vocab/", "name": "fullName"}, "@type": "person", "name": "Example Name", "@id": "//example.com/person/1234"}

5.3. Megfontolások

Bár technikailag lehetséges a Hydra-Jsonld használata a Spring Framework-en kívül, eredetileg a Spring-HATEOAS-szal való használatra tervezték. Ennek eredményeként nem lehet linkeket létrehozni a kommentárokkal, amint azt a Jackson-Jsonld-ben láttuk. Másrészt automatikusan generálódnak egyes tavasz-specifikus osztályokhoz.

Mielőtt ezt a könyvtárat választanánk egy projekthez, fontolóra kell venni a következőket:

  • A tavaszi keretrendszerrel történő használata további funkciókat tesz lehetővé
  • Nincs egyszerű módszer linkek létrehozására, ha nem a tavaszi keretrendszert használjuk
  • Nem tilthatjuk le a @vocab, csak felülírhatjuk

6. Dezerializáció Jsonld-Java és Jackson segítségével

A Jsonld-Java a JSON-LD 1.0 specifikáció és az API Java implementációja, amely sajnos nem a legújabb verzió.

Az 1.1 specifikációs verzió megvalósításához tekintse meg a Titanium JSON-LD könyvtárat.

A JSON-LD dokumentum deserializálásához alakítsuk át egy JSON-LD API szolgáltatással, az úgynevezett tömörítéssel olyan formátumra, amelyet POJO-hoz tudunk leképezni ObjectMapper.

6.1. Maven-függőségek

Először tegyük hozzá a függőséget jsonld-java:

 com.github.jsonld-java jsonld-java 0.13.0 

6.2. Példa

Dolgozzunk ezzel a JSON-LD dokumentummal mint inputunk:

{"@context": {"@vocab": "//schema.org/", "tudja": {"@type": "@id"}}, "@type": "Person", "@id ":" //example.com/person/1234 "," name ":" Példa neve "," know ":" //example.com/person/2345 "}

Tegyük fel, hogy az egyszerűség kedvéért a dokumentum tartalma a Húr nevű változó inputJsonLd.

Először tömörítsük és alakítsuk vissza a-vá Húr:

Objektum jsonObject = JsonUtils.fromString (inputJsonLd); Object compact = JsonLdProcessor.compact (jsonObject, új HashMap (), új JsonLdOptions ()); String compactContent = JsonUtils.toString (kompakt);
  • A JSON-LD objektumot elemezhetjük és megírhatjuk a JsonUtils, amely a Jsonld-Java könyvtár része
  • A kompakt metódus, második paraméterként használhatunk egy üreset Térkép. Így a tömörítési algoritmus egy egyszerű JSON objektumot állít elő, ahol a kulcsok feloldódnak az IRI űrlapjukra

A compactContent A változónak tartalmaznia kell:

{"@id": "//example.com/person/1234", "@type": "//schema.org/Person", "//schema.org/knows": {"@id": " //example.com/person/2345 "}," //schema.org/name ":" Példa neve "}

Másodszor, alakítsuk ki POJO-t Jackson annotációkkal, hogy illeszkedjenek egy ilyen dokumentumszerkezethez:

@JsonIgnoreProperties (ignoreUnknown = true) nyilvános osztály Személy {@JsonProperty ("@ id") privát karakterlánc azonosító; @JsonProperty ("// schema.org/name") privát karakterlánc neve; @JsonProperty ("// schema.org/knows") privát link tudja; // konstruktorok, getterek, beállítók public static class Link {@JsonProperty ("@ id") private String id; // kivitelezők, szerelők, beállítók}}

És végül térképezzük le a JSON-LD-t a POJO-hoz:

ObjectMapper objectMapper = új ObjectMapper (); Személy személy = objectMapper.readValue (compactContent, Person.class);

7. Következtetés

Ebben a cikkben két Jackson-alapú könyvtárat vizsgáltunk meg a POJO JSON-LD dokumentumba való sorosítására, valamint a JSON-LD POJO -vá deserializálásának egyik módjára.

Amint kiemeltük, mindkét szerializációs könyvtárnak vannak hiányosságai, amelyeket figyelembe kell vennünk, mielőtt felhasználnánk őket. Ha több JSON-LD funkciót kell használnunk, mint amennyit ezek a könyvtárak kínálnak, akkor megközelíthetjük a dokumentumunk létrehozását egy JSON-LD kimeneti formátumú RDF könyvtár segítségével.

Szokás szerint a forráskód megtalálható a GitHubon.