Javas JSON API sasniedz kandidāta statusu: dublētas atslēgas kļūst par kļūdu

OpenJDK priekšlikums JEP 540 jūlijā sasniedza kandidāta statusu. Tas Javai pievieno moduli jdk.incubator.json, ar kuru JSON dokumentu var nolasīt un uzrakstīt bez ārējas bibliotēkas. Autori ir Naoto Sato, Pols Sandozs, Džastins Lu un Stjuarts Markss. Dokumentu recenzējis Alekss Baklijs. Priekšlikuma lapa pēdējoreiz atjaunota 28. jūlijā.

Līdz šim pat vienas vērtības izvilkšanai no REST atbildes Javas projektam vajadzēja pievienot Jackson, Gson vai Jakarta JSON Processing. Pamatojumā rakstīts, ka Python vai Go tas pats darbs prasa pāris rindas un Javas kodam jābūt tikpat īsam.

Kā API izskatās darbā

Piemērs priekšlikumā aprēķina vidējo prognozēto temperatūru no ASV Nacionālā meteoroloģijas dienesta REST atbildes. Pēc Json.parse(body) koks tiek pārstaigāts ar get("properties").get("periods"), masīvs pārvērsts par sarakstu ar asList() un temperatūras savāktas ar asInt(). Kopā četras rindas.

Izvadei ir divas metodes. toString() saliek visu vienā rindā bez atstarpēm, bet Json.toDisplayString(json, 2) dod salasāmu formu, kur otrais arguments ir atkāpes lielums. Abu rezultātu var atkal padot Json.parse un iegūt ekvivalentu koku.

Sešas apakšsaskarnes, septiņas konvertācijas

API centrā ir aizzīmogota saskarne JsonValue. Tai atbilst sešas apakšsaskarnes pēc JSON tipiem: JsonString, JsonNumber, JsonBoolean, JsonNull, JsonObject un JsonArray. Aizzīmogojums dod praktisku ieguvumu: switch pār JsonValue ar tipu šabloniem neprasa default zaru.

Pārejai uz Java tipiem ir septiņas metodes: asString, asInt, asLong, asDouble, asBoolean, asMap un asList. Nepareizs tips met JsonValueException. Kļūdas ziņojumā ir ceļš no dokumenta saknes līdz problēmvietai un pozīcija tekstā. Ja koda gabals no pavedienu izmetes mēģina tid nolasīt kā boolean, ziņojumā parādās Path: "{threadDump{threadContainers[0{threads[0{tid" ar norādi uz 13. rindu.

Trūkstošu atslēgu apstrādei ir tryGet, kas atgriež Optional. JSON null vērtību noķer tryValue, kas JsonNull gadījumā atdod tukšu Optional. Metodes asBigDecimal nav. Priekšlikums to pamato ar to, ka lietotājs pats var uzrakstīt new BigDecimal(jn.toString()) un katra papildu metode API būtu vēl viens lēmums, kas uzspiests visiem.

Skaitļu apstrādē ir vairākas robežas, ko der zināt. asDouble() noapaļo: Json.parse("3.141592653589793238462643383279").asDouble() dod 3.141592653589793, bet 1.8E309 met JsonValueException kā ārpus diapazona. asInt() pieņem 123.0 un 234.56E2, jo abi apzīmē veselu skaitli, tomēr atmet 345.6 un 2147483648. Bezgalība un NaN JSON sintaksē neeksistē, tāpēc tās nekad netiek atgrieztas. Negatīvā nulle gan var.

Stingrs lasītājs

Parsēšana pieņem tikai RFC 8259 sintaksi. Beigu komati, komentāri un JSON5 paplašinājumi met JsonParseException. Priekšlikums iesaka tos noņemt pirms parsēšanas ar parastu replaceAll izsaukumu.

Stingrākais lēmums attiecas uz dublētiem lauku nosaukumiem vienā objektā. RFC 8259 saka tikai to, ka nosaukumiem objektā “SHOULD be unique”, tāpēc bibliotēkas gadiem uzvedas dažādi. JEP 540 tos aizliedz bez izņēmumiem un kļūdā parāda, kurš nosaukums atkārtojas. Pamatojumā minēta 2013. gada ECMAScript sarakstes diskusija, kurā stingrāku prasību atmeta bažās par jau esošiem dokumentiem, kā arī RFC 9413 par robustu protokolu uzturēšanu.

Mūsu mērķis nav izveidot API, kas aizstātu iesakņojušās ārējās JSON bibliotēkas. (JEP 540, sadaļa Non-Goals)

Kas API nebūs

• Datu saistīšanas. Objektu pārvēršana uz JSON un atpakaļ paliek Jackson un Jakarta ziņā. Priekšlikums norāda, ka arī šīs bibliotēkas datu saistīšanu tur atsevišķos moduļos.
• Straumēšanas. Notikumu plūsma sarežģī pat vienkāršu datu izvilkšanu, tāpēc to atmeta.
• Failu vai tīkla savienojumu lasīšanas. Dokumentam jāietilpst atmiņā kā String vai char masīvam, jo modelis ir koks.
• Parsēšanas iestatījumu. Konfigurācijas variantu nav vispār.

Divpadsmit gadi no pirmā mēģinājuma

JEP 540 aizstāj JEP 198 ar nosaukumu Light-Weight JSON API, ko Maiks Duigū iesniedza 2014. gada 9. jūnijā. Tas paredzēja notikumu plūsmas, koku skatus, transformētāja API un atbalstu Java ME kompaktprofiliem. Priekšlikums nenonāca nevienā laidienā un 23. jūlijā tika slēgts ar piezīmi, ka to aizstāj JEP 540.

Kandidāta statuss vēl nav apstiprinājums. JDK 28 lapā 27. jūlijā kā mērķim piedāvāti trīs citi priekšlikumi: 401 Value Objects, 535 Shenandoah ģenerāciju režīms pēc noklusējuma un 539 Strict Field Initialization. JEP 540 tajā sarakstā nav. JDK 28 vispārējais laidiens plānots 2027. gada martā.

Inkubatora modulis pēc noklusējuma nav pieejams. Kompilēšanai un palaišanai to jāpieprasa ar --add-modules jdk.incubator.json. API drīkst mainīties starp laidieniem. Testēšanā OpenJDK plāno izmantot publisko JSON Parsing Test Suite ar tā robežgadījumu ievadiem.

Tajā pašā nedēļā kandidāta statusu saņēma arī JEP 541, kas piedāvā novecojušu atzīmēt macOS/x64 portu. Kā rakstīja InfoQ, abi priekšlikumi no drafta stadijas pacēlās vienā dienā.

Priekšlikumā minēts arī, kur JSON noderētu pašam JDK. Drošības iestatījumu failā masīvu pašlaik jāraksta ar numurētām rindām: security.provider.1=SUN, security.provider.2=SunRsaSign un tā tālāk. Ar JSON tā vietā būtu "providers": [ "SUN", "SunRsaSign", "SunEC" ].

Avoti

• JEP 540: Simple JSON API (Incubator), openjdk.org
• JEP 198: Light-Weight JSON API, openjdk.org
• JDK 28, openjdk.org
• Java News Roundup: Simple JSON API, JEPs for JDK 28, InfoQ
• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format, IETF