Hipermedijalna serializacija s JSON-LD
1. Pregled
JSON-LD je RDF format zasnovan na JSON-u za predstavljanje povezanih podataka. Omogućuje proširenje postojećih JSON objekata s hipermedijskim mogućnostima; drugim riječima, sposobnost sadržavanja veza na strojno čitljiv način.
U ovom vodiču, razmotrit ćemo nekoliko opcija temeljenih na Jacksonu za serializaciju i deserializaciju JSON-LD formata izravno u POJO. Također ćemo pokriti osnovne koncepte JSON-LD koji će nam omogućiti razumijevanje primjera.
2. Osnovni pojmovi
Kad prvi put vidimo JSON-LD dokument, primijetimo da neka imena članova počinju s @ lik. To su ključne riječi JSON-LD i njihove vrijednosti pomažu nam da razumijemo ostatak dokumenta.
Da bismo se kretali svijetom JSON-LD i razumjeli ovaj vodič, moramo biti svjesni četiri ključne riječi:
- @kontekst je opis JSON objekta koji sadrži mapu ključ / vrijednost svega potrebnog za interpretaciju dokumenta
- @vocab je mogući ključ u @kontekst koji uvodi zadani rječnik da bi se @kontekst objekt mnogo kraći
- @iskaznica je ključna riječ za identifikaciju veza bilo kao svojstvo resursa koja predstavlja izravnu vezu do samog resursa ili kao @tip vrijednost za označavanje bilo kojeg polja kao veze
- @tip je ključna riječ za prepoznavanje vrsta resursa na razini resursa ili u @kontekst; na primjer, za definiranje vrste ugrađenih resursa
3. Serijalizacija u Javi
Prije nego što nastavimo, trebali bismo pogledati naše prethodne vodiče kako bismo osvježili sjećanje na Jacksona ObjectMapper, Jackson Annotations i custom Jackson Serializers.
Budući da smo već upoznati s Jacksonom, mogli bismo shvatiti da bismo mogli lako serializirati dva prilagođena polja u bilo kojem POJO-u kao @iskaznica i @tip koristiti @JsonProperty bilješka. Međutim, pisanje @kontekst ručno bi moglo biti puno posla i također sklono pogreškama.
Stoga, da bismo izbjegli ovaj pristup podložan pogreškama, pogledajmo pobliže dvije knjižnice za koje bismo mogli koristiti @kontekst generacija. Nažalost, niti jedan od njih nije sposoban generirati sve značajke JSON-LD-a, ali njihove ćemo nedostatke pogledati i kasnije.
4. Serijalizacija s Jackson-Jsonldom
Jackson-Jsonld je Jackson modul koji omogućuje anotiranje POJO-a na prikladan način za generiranje JSON-LD dokumenata.
4.1. Ovisnosti Mavena
Prvo, dodajmo jackson-jsonld kao ovisnost o pom.xml:
com.io-informatika.oss jackson-jsonld 0.1.1
4.2. Primjer
Zatim, kreirajmo naš primjer POJO i označimo ga za @kontekst generacija:
@JsonldResource @JsonldNamespace (name = "s", uri = "//schema.org/") @JsonldType ("s: Person") @JsonldLink (rel = "s: zna", name = "zna", href = "//example.com/person/2345") javna klasa Osoba {@JsonldId private String id; @JsonldProperty ("s: name") ime privatnog niza; // konstruktor, getteri, postavljači}
Dekonstruirajmo korake da bismo razumjeli što smo učinili:
- S @JsonldResource označili smo POJO za obradu kao resurs JSON-LD
- U @JsonldNamespace definirali smo skraćenicu za rječnik koji želimo koristiti
- Parametar koji smo naveli u @JsonldType postat će @tip resursa
- Koristili smo @JsonldLink napomena za dodavanje veza na resurs. Kada se obrađuje, Ime parametar koristit će se kao naziv polja, a također će se dodati kao ključ za @kontekst.href bit će vrijednost polja i rel bit će preslikana vrijednost u @kontekst
- Polje kojim smo označili @JsonldId postat će @iskaznica resursa
- Parametar koji smo naveli u @JsonldProperty postat će vrijednost preslikana na ime polja u @kontekst
Dalje, generirajmo JSON-LD dokument.
Prvo bismo trebali registrirati JsonldModule u ObjectMapper. Ovaj modul sadrži običaj Serijalizator koje će Jackson koristiti za POJO označene s @JsonldResource bilješka.
Zatim ćemo nastaviti i koristiti ObjectMapper za generiranje JSON-LD dokumenta:
ObjectMapper objectMapper = novi ObjectMapper (); objectMapper.registerModule (novi JsonldModule ()); Osoba osoba = nova Osoba ("// example.com/person/1234", "Primjer imena"); Niz personJsonLd = objectMapper.writeValueAsString (osoba);
Kao rezultat, personJsonLd varijabla sada treba sadržavati:
{"@type": "s: Person", "@context": {"s": "//schema.org/", "name": "s: name", "know": {"@id" : "s: zna", "@type": "@id"}}, "name": "Primjer imena", "@id": "//example.com/person/1234", "zna": " //example.com/osoba/2345 "}
4.3. Razmatranja
Prije nego što odaberemo ovu knjižnicu za projekt, trebali bismo razmotriti sljedeće:
- Koristiti @vocab ključna riječ nije moguća, pa ćemo morati upotrijebiti @JsonldNamespace pružiti skraćenicu za rješavanje imena polja ili svaki put ispisati puni Internacionalizirani identifikator resursa (IRI)
- Veze možemo definirati samo u vrijeme prevođenja, pa da bismo dodali vrijeme izvođenja veze, trebamo upotrijebiti refleksiju za promjenu tog parametra u bilješci
5. Serijalizacija s Hydra-Jsonldom
Hydra-Jsonld je modul knjižnice Hydra-Java, koji je prvenstveno izgrađen kako bi omogućio prikladno stvaranje JSON-LD odgovora za proljetne aplikacije. Koristi rječnik Hydra kako bi JSON-LD dokumenti bili izražajniji.
Međutim, modul Hydra-Jsonld sadrži Jacksona Serijalizator i neke napomene koje možemo koristiti za generiranje JSON-LD dokumenata izvan Spring Framework-a.
5.1. Ovisnosti Mavena
Prvo, dodajmo ovisnost za hydra-jsonld prema pom.xml:
de.escalon.hypermedia hydra-jsonld 0.4.2
5.2. Primjer
Drugo, označimo naš POJO za @kontekst generacija.
Hydra-Jsonld automatski generira zadanu postavku @kontekst bez potrebe za bilješkama. Ako smo zadovoljni zadanim postavkama, trebamo dodati samo @iskaznica da biste dobili valjani JSON-LD dokument.
Zadani rječnik bit će rječnik schema.org, @tip Java razred ime i javna svojstva POJO-a bit će uključena u rezultirajući dokument JSON-LD.
U ovom primjeru, poništimo ove zadane vrijednosti s prilagođenim vrijednostima:
@Vocab ("// example.com/vocab/") @Expose ("person") javna klasa Osoba {private String id; privatni naziv niza; // konstruktor @JsonProperty ("@ id") javni String getId () {return id; } @Expose ("fullName") javni niz getName () {return name; }}
Ponovno, pogledajmo bliže korake:
- U usporedbi s primjerom Jackson-Jsonld, izostavili smo zna polje iz našeg POJO-a zbog ograničenja Hydra-Jsonld-a izvan Proljetnog okvira
- Svoj preferirani rječnik postavili smo pomoću @Vocab bilješka
- Korištenjem @Izložiti napomena na predavanju, postavili smo drugačiji resurs @tip
- Koristili smo isto @Izložiti napomena na svojstvu za postavljanje preslikavanja na prilagođenu vrijednost u @kontekst
- Za generiranje @iskaznica s imanja, koristili smo @JsonProperty napomena od Jacksona
Dalje, konfigurirajmo primjerak Jacksona Modul da se možemo registrirati u ObjectMapper. Mi ćemo dodati JacksonHydraSerializer kao BeanSerializerModifier tako da se može primijeniti na sve POJO-ove koji su serializirani:
SimpleModule getJacksonHydraSerializerModule () {vratiti novi SimpleModule () {@Preuzmi javnu prazninu setupModule (kontekst SetupContext) {super.setupModule (kontekst); context.addBeanSerializerModifier (new BeanSerializerModifier () {@Override javni JsonSerializer modifySerializer (SerializationConfig config, BeanDescription beanDesc, JsonSerializer serializer) {if (serializer instanceof BeanSerializerBase) {return new JacksonlizerBaseranSeriaSerializerBaseranSerializerBaseranSerializerBaseranSerializerBaserana BeserializerBaseranserializerBaseranserializerBaseranSerializatorBaseranSerializerBaseran }); }}; }
Onda registrirajmo Modul u ObjectMapper i iskoristite ga. Također bismo trebali postaviti ObjectMapper uključiti samo ne-null vrijednosti za izradu valjanog JSON-LD dokumenta:
ObjectMapper objectMapper = novi ObjectMapper (); objectMapper.registerModule (getJacksonHydraSerializerModule ()); objectMapper.setSerializationInclusion (JsonInclude.Include.NON_NULL); Osoba osoba = nova Osoba ("// example.com/person/1234", "Primjer imena"); Niz personJsonLd = objectMapper.writeValueAsString (osoba);
Sada, personJsonLd varijabla treba sadržavati:
{"@context": {"@vocab": "//example.com/vocab/", "name": "fullName"}, "@type": "person", "name": "Primjer imena", "@id": "//example.com/person/1234"}
5.3. Razmatranja
Iako je tehnički moguće koristiti Hydra-Jsonld izvan Spring Framework-a, izvorno je dizajniran za upotrebu s Spring-HATEOAS-om. Kao rezultat, ne postoji način generiranja veza s napomenama kao što smo vidjeli u Jackson-Jsonldu. S druge strane, automatski se generiraju za neke klase specifične za Proljeće.
Prije nego što odaberemo ovu knjižnicu za projekt, trebali bismo razmotriti sljedeće:
- Korištenje s Spring Frameworkom omogućit će dodatne značajke
- Ne postoji jednostavan način za generiranje veza ako ne koristimo Spring Framework
- Ne možemo onemogućiti upotrebu @vocab, možemo ga samo nadjačati
6. Deserijalizacija s Jsonld-Javom i Jacksonom
Jsonld-Java je Java implementacija JSON-LD 1.0 specifikacije i API-ja, koja nažalost nije najnovija verzija.
Za primjenu verzije specifikacije 1.1 pogledajte biblioteku Titanium JSON-LD.
Da bismo deserializirali JSON-LD dokument, pretvorimo ga s JSON-LD API značajkom, zvanom sabijanje, u format koji možemo mapirati u POJO ObjectMapper.
6.1. Ovisnosti Mavena
Prvo, dodajmo ovisnost za jsonld-java:
com.github.jsonld-java jsonld-java 0.13.0
6.2. Primjer
Radimo s ovim JSON-LD dokumentom kao ulaznim podacima:
{"@context": {"@vocab": "//schema.org/", "zna": {"@type": "@id"}}, "@type": "Osoba", "@id ":" //example.com/person/1234 "," name ":" Primjer naziva "," zna ":" //example.com/person/2345 "}
Radi jednostavnosti, pretpostavimo da sadržaj dokumenta imamo u a Niz varijabla pozvana inputJsonLd.
Prvo ga sažejmo i pretvorimo natrag u Niz:
Objekt jsonObject = JsonUtils.fromString (inputJsonLd); Kompaktni objekt = JsonLdProcessor.compact (jsonObject, nova HashMap (), nova JsonLdOptions ()); Niz compactContent = JsonUtils.toString (kompaktan);
- Možemo raščlaniti i napisati JSON-LD objekt pomoću metoda iz JsonUtils, koji je dio biblioteke Jsonld-Java
- Kada koristite kompaktni metodu, kao drugi parametar možemo koristiti prazno Karta. Na taj će način algoritam zbijanja stvoriti jednostavan JSON objekt gdje su ključevi razvrstani u svoje IRI obrasce
The kompaktni Sadržaj varijabla treba sadržavati:
{"@id": "//example.com/person/1234", "@type": "//schema.org/Person", "//schema.org/knows": {"@id": " //example.com/person/2345 "}," //schema.org/name ":" Primjer imena "}
Drugo, prilagodimo naš POJO s Jacksonovim bilješkama kako bi odgovarao takvoj strukturi dokumenta:
@JsonIgnoreProperties (ignoreUnknown = true) javna klasa Osoba {@JsonProperty ("@ id") private String id; @JsonProperty ("// schema.org/name") ime privatnog niza; @JsonProperty ("// schema.org/knows") private Link zna; // konstruktori, getteri, postavljači javna statička klasa Link {@JsonProperty ("@ id") private String id; // konstruktori, getteri, postavljači}}
I na kraju, preslikajmo JSON-LD u POJO:
ObjectMapper objectMapper = novi ObjectMapper (); Osoba osoba = objectMapper.readValue (compactContent, Person.class);
7. Zaključak
U ovom smo članku pregledali dvije knjižnice utemeljene u Jacksonu za serializaciju POJO-a u JSON-LD dokument i jedan od načina za deserializaciju JSON-LD-a u POJO.
Kao što smo istaknuli, obje knjižnice za serializaciju imaju nedostatke koje bismo trebali uzeti u obzir prije nego što ih upotrijebimo. Ako trebamo koristiti više značajki JSON-LD nego što ih ove knjižnice mogu ponuditi, mogli bismo pristupiti izradi našeg dokumenta putem RDF knjižnice s izlaznim formatom JSON-LD.
Kao i obično, izvorni kod možete pronaći na GitHubu.