System.JSON v Delphi XE6

1.10.2014 0:43:14 #

Pokud náhodou někdo hledá rozumnou dokumentaci k JSON implementaci v Delphi XE6 nebo XE7, tak spláče nad výdělkem. Nicméně knihovna doznala velkých rozšíření a rád bych jich pár představil:

Základní princip vychází z dědění vlastností od nejjednoduššího typu TJSONAncestor, který je maximálně obecný (a většina jeho metod je abstraktních), přes TJSONValue (základní jednotka, se kterou lze pracovat) dále pak konkrétní typy (TJSONNull, TJSONTrue, TJSONFalse, TJSONString a TJSONNumber) po implementaci objektů TJSONObject a polí TJSONArray.

TJSONAncestor obsahuje pro vývojáře především metody společné všem dalším objektům, kterými jsou:
* funkce Null (tj. prázdný obsah reprezentovaný objektem TJSONNull)
* příznak Owned (jen pro zápis, čte se pomocí GetOwned a určuje, zda se objekt uvolní společně s nadřazeným objektem, přičemž výchozí stav je True)
* metoda Clone, která vytvoří kopii objektu s kompletní strukturou
* vlastnost Value, která vrací textovou reprezentaci hodnoty (dle typu)
* vlastnost EstimatedByteSize, která vrací odhadovaný počet bytů pro zápis, přičemž skutečný počet nebude větší
* metoda ToBytes, která objekt zapíše do pole bytů maximální velikosti dle EstimatedByteSize

TJSONValue rozšiřuje TJSONAncestor o generické metody TryGetValue<T> a GetValue<T>, přičemž se liší především tím, že GetValue vrací hodnotu nebo vyvolá výjimku, kdežto TryGetValue vrací hodnotu referencí a dále vrací příznak, zda byla hodnota vrácena. Obě metody mohou mít jako první parametr uvedenou cestu kombinací identifikátorů a indexů oddělených tečkou, např. "id", "osoby.vedouci[1]", "[4]" apod.
* textový identifikátor značí položku objektu ("id")
* index v hranatých závorkách značí položku pole ([4])
* pokud se odkazujete na prvek pole objektu, není nutné vkládat tečku (tj. "vedouci[1]" = "vedouci.[1]")
* hodnota se automaticky transformuje na odpovídající datový typ, pokud je to možné, tj. např. číslo lze vrátit jako string nebo "2" jako integer, "2014-09-30T12:00:00Z" jako TDateTime apod.
Příklad: Id := AJsonValue.GetValue<Integer>('[4].id');

TJSONTrue a TJSONFalse reprezentují logické hodnoty True a False. V JSON se zapisují jako "true" a "false" (bez uvozovek).
Vytvoření logické hodnoty se provede pouhým voláním konstruktoru třídy.

TJSONNull reprezentuje prázdnou hodnotu.

TJSONString reprezentuje obecný řetězec znaků. Rozšiřuje TJSONValue o následující:
* metoda třídy Hex(Digit) vrací '0' až 'F' pro hodnotu 0 až 15 (pro naše účely není podstatná)
* konstruktor Create vyrobí prázdný řetězec (pozor, nelze jej dále měnit!)
* konstruktor Create(Value: string) vyrobí JSON implementaci předané hodnoty
* metoda AddChar(Ch: WideChar) přidá znak na konec aktuální hodnoty
Metoda ToString vrací textovou hodnotu v dvojitých uvozovkách, přičemž případné uvozovky uvnitř textu jsou zvojeny.
Metoda ToBytes zajistí korektní reprezentaci znaků Unicode.

TJSONNumber reprezentuje obecné číslo. Rozšiřuje TJSONString o následující:
* konstruktor Create(Double|Integer|Int64)
* funkce ToString vrací nelokalizovanou reprezentaci čísla pro JSON
* funkce Value vrací lokalizovanou textovou reprezentaci čísla
* funkce AsInt, AsInt64 a AsDouble vrací odpovídající číselnou hodnotu

TJSONObject reprezentuje objekt JSON, který obsahuje pojmenované libovolné hodnoty včetně objektů a polí. Jeho zápis v JSON je ve složených závorkách a vypadá zhruba takto: {"id":1,"name":"John Black","children":["Marry","Peter"]} a rozšiřuje TJSONValue o následující:
* přetížená metoda třídy ParseJSONValue, která analyzuje předaná data (řetězec, pole bytů) a vytvoří instanci TJSONValue (nebo vrátí nil, pokud někde nastala chyba)
* konstruktor Create, který vytvoří prázdný objekt
* konstruktor Create(Pair), který vytvoří objekt s jednou párovou hodnotu (viz. dále)
* funkce GetValue(Name), který vrací první hodnotu TJSONValue odpovídající zadanému jménu
* přetížená metoda AddPair, která přidá nebo vytvoří a přidá párovou značku a vrací instanci objektu, aby bylo možné volání řetězit
* metoda RemovePair(Name) odstraní první nalezenou párovou hodnotu daného jména
* metoda SetPairs nahradí párové značky předaným seznamem (uvolnění objektu seznamu z paměti je dále v režii TJSONObject) - pozor, nahrazené párové hodnoty nejsou uvolněny!
* vlastnost Count vrací počet párů objektu
* indexovaná vlastnost Pair vrací párovou hodnotu dle pořadí
* vlastnost Values[Name] vrací hodnotu dle názvu (nebo nil, pokud neexistuje)
Párová hodnota je reprezentována objektem TJSONPair, který obsahuje hodnoty JsonString (textový název hodnoty) a JsonValue (objekt TJSONValue).
Třídu TJSONObject lze použít v konstrukci for-in, přičemž řídící objekt je typu TJSONPair.

TJSONArray reprezentuje pole libovolných hodnot, tj. včetně objektů a polí. Pole se v JSON zapisují hranatými závorkami, např. [2,3,5,7,11,13,17,19] a rozšiřuje TJSONValue o následující:
* přetížený konstruktor Create s možností definovat až dva prvky TJSONValue nebo string
* vlastnost Count vrací počet prvků pole
* indexovaná vlastnost Item[Index] vrací prvek dle pořadového čísla
* funkce Remove(Index) odebere zvolený prvek z pole a vrátí jej (tj. volající metoda jej musí uvolnit!)
* metoda AddElement přidá do pole jeden prvek TJSONValue
* přetížená metoda Add vytvoří objekty JSON a přidá je do pole z typů string, Integer, Double, Boolean nebo přidá TJSONArray a TJSONObject, přičemž vrací instanci na sebe sama, aby bylo možné volání řetězit
* metoda SetElements nahradí všechny prvky polen předaným seznamem (uvolnění objektu seznamu z paměti je dále v režii TJSONArray) - pozor, nahrazené objekty nejsou uvolněny!
Hodnoty pole jsou vždy následovníci třídy TJSONValue.
Třídu TJSONArray lze použít v konstrukci for-in, přičemž řídící objekt je typu TJSONValue.

No a to je v zásadě vše, co je k použití jednotky System.JSON potřeba znát. Dále je nutné pamatovat na to, že se objekty JSON uvolňují přes objekt nejvyšší úrovně, pokud tedy nezměníte parametr Owned.

Igor Gottwald