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.