Hypermediálna serializácia s JSON-LD

1. Prehľad

JSON-LD je formát RDF založený na JSON na reprezentáciu prepojených údajov. Umožňuje rozšírenie existujúcich objektov JSON o možnosti hypermédií; inými slovami schopnosť obsahovať odkazy strojovo čitateľným spôsobom.

V tomto návode pozrieme sa na niekoľko možností založených na Jacksonovi na serializáciu a deserializáciu formátu JSON-LD priamo do POJO. Preberieme tiež základné koncepty JSON-LD, ktoré nám umožnia porozumieť príkladom.

2. Základné pojmy

Prvýkrát, keď vidíme dokument JSON-LD, všimneme si, že niektoré názvy členov začínajú na @ znak. Toto sú kľúčové slová JSON-LD a ich hodnoty nám pomáhajú porozumieť zvyšku dokumentu.

Aby sme sa zorientovali vo svete JSON-LD a porozumeli tomuto tutoriálu, musíme si uvedomiť štyri kľúčové slová:

  • @kontext je popis objektu JSON, ktorý obsahuje mapu kľúčov a hodnôt všetkého potrebného na interpretáciu dokumentu
  • @vocab je možný kľúč v @kontext , ktorý zavádza predvolený slovník na vytváranie @kontext objekt oveľa kratší
  • @id je kľúčové slovo na identifikáciu odkazov buď ako vlastnosť zdroja, ktorá predstavuje priamy odkaz na samotný zdroj, alebo ako a @typ hodnota na označenie ktoréhokoľvek poľa ako odkazu
  • @typ je kľúčové slovo na identifikáciu typov zdrojov buď na úrovni zdrojov, alebo v @kontext; napríklad definovať typ vložených zdrojov

3. Serializácia v Jave

Než budeme pokračovať, mali by sme sa pozrieť na naše predchádzajúce návody, aby sme si osviežili pamäť na Jacksona ObjectMapper, Jacksonove anotácie a prispôsobené Jackson Serializátory.

Keď už sme Jacksona oboznámení, mohli by sme si uvedomiť, že by sme mohli ľahko serializovať dve vlastné polia v ľubovoľnom POJO ako @id a @typ pomocou @JsonProperty anotácia. Avšak písanie @kontext ručne by mohlo byť veľa práce a tiež náchylné na chyby.

Preto, aby sme sa vyhli tomuto prístupu náchylnému na chyby, pozrime sa bližšie na dve knižnice, ktoré by sme mohli použiť @kontext generácie. Bohužiaľ, ani jeden z nich nie je schopný generovať všetky funkcie JSON-LD, ale na ich nedostatky sa pozrieme tiež neskôr.

4. Serializácia s Jacksonom-Jsonldom

Jackson-Jsonld je modul Jackson, ktorý umožňuje pohodlnú anotáciu POJO generovať dokumenty JSON-LD.

4.1. Maven závislosti

Najprv dodajme jackson-jsonld ako závislosť od pom.xml:

 com.io-informatics.oss jackson-jsonld 0.1.1 

4.2. Príklad

Potom vytvorme náš príklad POJO a anotujme ho @kontext generácia:

@JsonldResource @JsonldNamespace (name = "s", uri = "//schema.org/") @JsonldType ("s: Person") @JsonldLink (rel = "s: vie", name = "vie", href = „//example.com/osoba/2345“) verejná trieda Osoba {@JsonldId súkromné ​​ID reťazca; @JsonldProperty ("s: name") súkromné ​​meno reťazca; // konštruktor, getri, nastavovatelia}

Poďme dekonštruovať kroky, aby sme pochopili, čo sme urobili:

  • S @JsonldResource označili sme POJO na spracovanie ako prostriedok JSON-LD
  • V @JsonldNamespace definovali sme skratku pre slovnú zásobu, ktorú chceme používať
  • Parameter, ktorý sme zadali v @JsonldType sa stane @typ zdroja
  • Použili sme @JsonldLink anotácia na pridanie odkazov na zdroj. Po spracovaní názov parameter sa použije ako názov poľa a tiež sa pridá ako kľúč k @kontext.href bude hodnota poľa a rel bude namapovaná hodnota v @kontext
  • Pole, ktorým sme označili @JsonldId sa stane @id zdroja
  • Parameter, ktorý sme zadali v @JsonldProperty sa stane hodnotou namapovanou na názov poľa v @kontext

Ďalej vygenerujme dokument JSON-LD.

Najskôr by sme mali zaregistrovať JsonldModule v ObjectMapper. Tento modul obsahuje vlastné Serializátor ktoré Jackson použije pre POJO označené značkou @JsonldResource anotácia.

Potom budeme pokračovať a použijeme ObjectMapper vygenerovať dokument JSON-LD:

ObjectMapper objectMapper = nový ObjectMapper (); objectMapper.registerModule (nový JsonldModule ()); Osoba osoba = nová osoba ("// example.com/osoba/1234", "vzorové meno"); Reťazec personJsonLd = objectMapper.writeValueAsString (osoba);

Výsledkom je, že osobaJsonLd premenná by teraz mala obsahovať:

{"@type": "s: Person", "@context": {"s": "//schema.org/", "name": "s: name", "vie": {"@id" : "s: Know", "@type": "@id"}}, "name": "Príklad názvu", "@id": "//example.com/osobna/1234", "vie": " //example.com/osoba/2345 "}

4.3. Úvahy

Pred výberom tejto knižnice pre projekt by sme mali zvážiť nasledovné:

  • Pomocou @vocab kľúčové slovo nie je možné, takže budeme musieť použiť buď @JsonldNamespace poskytnúť skratku na riešenie názvov polí alebo zakaždým vypísať úplný internacionalizovaný identifikátor zdroja (IRI)
  • Odkazy môžeme definovať iba v čase kompilácie, takže aby sme mohli pridať runtime odkazu, potrebovali by sme použiť reflexiu na zmenu tohto parametra v anotácii

5. Serializácia s Hydra-Jsonld

Hydra-Jsonld je modul knižnice Hydra-Java, ktorý je primárne zostavený tak, aby umožňoval pohodlné vytváranie odpovedí JSON-LD pre jarné aplikácie. Používa slovník Hydra na zvýšenie expresivity dokumentov JSON-LD.

Avšak, modul Hydra-Jsonld obsahuje Jackson Serializátor a niektoré anotácie, ktoré môžeme použiť na generovanie dokumentov JSON-LD mimo jarného rámca.

5.1. Maven závislosti

Najskôr pridajme závislosť pre hydra-jsonld do pom.xml:

 de.escalon.hypermedia hydra-jsonld 0.4.2 

5.2. Príklad

Po druhé, poďme anotovať náš POJO pre @kontext generácie.

Hydra-Jsonld automaticky generuje predvolené hodnoty @kontext bez potreby anotácií. Ak sme spokojní s predvolenými nastaveniami, stačí pridať @id získať platný dokument JSON-LD.

Predvoleným slovníkom bude slovník schema.org, @typ Java trieda názov a verejné vlastnosti POJO budú všetky zahrnuté do výsledného dokumentu JSON-LD.

V tomto príklade prepíšeme tieto predvolené hodnoty vlastnými hodnotami:

@Vocab ("// example.com/vocab/") @Expose ("osoba") verejná trieda Osoba {private String id; súkromné ​​meno reťazca; // konštruktor @JsonProperty ("@ id") public String getId () {return id; } @Expose ("fullName") public String getName () {návratové meno; }}

Znova sa pozrime podrobnejšie na príslušné kroky:

  • V porovnaní s príkladom Jacksona-Jsonlda sme vynechali vie poľa z nášho POJO z dôvodu obmedzení Hydra-Jsonld mimo jarného rámca
  • Nastavili sme preferovaný slovník pomocou @Vocab anotácia
  • Použitím @ Vystaviť anotácie k triede, nastavili sme iný zdroj @typ
  • Použili sme to isté @ Vystaviť anotácia vlastnosti, aby sa v mapovaní nastavilo jej mapovanie na vlastnú hodnotu @kontext
  • Za generovanie @id z nehnuteľnosti sme použili @JsonProperty anotácia od Jacksona

Ďalej nakonfigurujme inštanciu Jacksona Modul že sa môžeme zaregistrovať v ObjectMapper. Pridáme JacksonHydraSerializer ako BeanSerializerModifier takže sa dá použiť na všetky POJO, ktoré sa serializujú:

SimpleModule getJacksonHydraSerializerModule () {return new SimpleModule () {@Override public void setupModule (SetupContext context) {super.setupModule (context); context.addBeanSerializerModifier (nový BeanSerializerModifier () {@Override public JsonSerializer modifySerializer (SerializationConfig config, BeanDescription beanDesc, JsonSerializer serializer) {if (serializer instanceof BeanSerializerBase) {return new JacksonHydraer }); }}; }

Potom zaregistrujme Modul v ObjectMapper a využi to. Mali by sme tiež nastaviť ObjectMapper zahrnúť ibanulový hodnoty na vytvorenie platného dokumentu JSON-LD:

ObjectMapper objectMapper = nový ObjectMapper (); objectMapper.registerModule (getJacksonHydraSerializerModule ()); objectMapper.setSerializationInclusion (JsonInclude.Include.NON_NULL); Osoba osoba = nová osoba ("// example.com/osoba/1234", "vzorové meno"); Reťazec personJsonLd = objectMapper.writeValueAsString (osoba);

Teraz osobaJsonLd premenná by mala obsahovať:

{"@context": {"@vocab": "//example.com/vocab/", "name": "fullName"}, "@type": "person", "name": "Príklad názvu", "@id": "//example.com/osoba/1234"}

5.3. Úvahy

Aj keď je technicky možné použiť Hydra-Jsonld mimo Spring Framework, bol pôvodne navrhnutý pre použitie s Spring-HATEOAS. Vo výsledku neexistuje spôsob, ako generovať odkazy s anotáciami, ako sme videli v Jackson-Jsonld. Na druhej strane sa generujú pre niektoré triedy špecifické pre jar automaticky.

Pred výberom tejto knižnice pre projekt by sme mali zvážiť nasledovné:

  • Jeho použitie s jarným rámcom umožní ďalšie funkcie
  • Nie je jednoduchý spôsob generovania odkazov, ak nepoužívame jarný rámec
  • Používanie aplikácie nemôžeme zakázať @vocab, môžeme to iba prepísať

6. Deserializácia pomocou Jsonld-Java a Jackson

Jsonld-Java je implementácia Java špecifikácie JSON-LD 1.0 a API, ktorá bohužiaľ nie je najnovšou verziou.

Implementáciu verzie 1.1 nájdete v knižnici Titanium JSON-LD.

Ak chceme deserializovať dokument JSON-LD, transformujme ho pomocou funkcie JSON-LD API zvanej zhutnenie na formát, ktorý môžeme mapovať na POJO s ObjectMapper.

6.1. Maven závislosti

Najskôr pridajme závislosť pre jsonld-java:

 com.github.jsonld-java jsonld-java 0.13.0 

6.2. Príklad

Poďme pracovať s týmto dokumentom JSON-LD ako našim vstupom:

{"@context": {"@vocab": "//schema.org/", "vie": {"@type": "@id"}}, "@type": "Osoba", "@id" ":" //example.com/osoba/1234 "," name ":" Vzorové meno "," vie ":" //example.com/osoba/2345 "}

Kvôli jednoduchosti predpokladajme, že máme obsah dokumentu v a String premenná volala inputJsonLd.

Najskôr to skomprimujeme a prevedieme späť na a String:

Objekt jsonObject = JsonUtils.fromString (inputJsonLd); Objekt kompaktný = JsonLdProcessor.compact (jsonObject, nový HashMap (), nový JsonLdOptions ()); Reťazec compactContent = JsonUtils.toString (kompaktný);
  • Objekt JSON-LD môžeme analyzovať a zapísať metódami z JsonUtils, ktorá je súčasťou knižnice Jsonld-Java
  • Pri použití kompaktný metóda, ako druhý parameter môžeme použiť prázdny Mapa. Týmto spôsobom vytvorí zhutňovací algoritmus jednoduchý objekt JSON, v ktorom sú kľúče rozlíšené do svojich foriem IRI

The compactContent premenná by mala obsahovať:

{"@id": "//example.com/osoba/1234", "@type": "//schema.org/Person", "//schema.org/knows": {"@id": " //example.com/osoba/2345 "}," //schema.org/name ":" Vzorové meno "}

Po druhé, prispôsobme naše POJO anotáciami Jacksona tak, aby vyhovovali takejto štruktúre dokumentu:

@JsonIgnoreProperties (ignoreUnknown = true) verejná trieda Osoba {@JsonProperty ("@ id") súkromné ​​ID reťazca; @JsonProperty ("// schema.org/name") súkromné ​​meno reťazca; @JsonProperty ("// schema.org/knows") súkromný odkaz vie; // konštruktory, getre, setre verejná statická trieda Odkaz {@JsonProperty ("@ id") súkromné ​​String id; // konštruktory, getre, setre}}

A nakoniec, poďme mapovať JSON-LD na POJO:

ObjectMapper objectMapper = nový ObjectMapper (); Osoba person = objectMapper.readValue (compactContent, Person.class);

7. Záver

V tomto článku sme sa pozreli na dve knižnice založené na Jacksonovi na serializáciu POJO do dokumentu JSON-LD a na jeden spôsob, ako deserializovať JSON-LD na POJO.

Ako sme zdôraznili, obe knižnice na serializáciu majú nedostatky, ktoré by sme mali zvážiť pred ich použitím. Ak potrebujeme použiť viac funkcií JSON-LD, ako môžu tieto knižnice ponúknuť, mohli by sme pristúpiť k vytvoreniu nášho dokumentu prostredníctvom knižnice RDF s výstupným formátom JSON-LD.

Ako obvykle, zdrojový kód nájdete na GitHub.