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.