JSON Objects Framework
Go Up to JSON
RAD Studio provides the System.JSON unit, that contains classes and methods to store, parse, and generate data in JSON format.
- Note: This page is for the JSON objects framework. To see the other JSON framework that RAD Studio offers, see Readers and Writers JSON Framework.
The JSON objects framework supports all JSON types: TJSONObject, TJSONArray, TJSONNumber, TJSONString, TJSONTrue, TJSONFalse, TJSONNull -- all descendants of TJSONValue.
JSON objects can be instantiated and incrementally constructed, or a byte stream can be parsed into one.
In the code snippet below, an object with a "Hello": "World"
pair is created:
var
LJSONObject: TJSONObject;
begin
LJSONObject:= TJSONObject.Create;
LJSONObject.AddPair(TJSONPair.Create(TJSONString.Create('Hello'),
TJSONString.Create('World')));
The static class function ParseJSONValue or the function Parse can be used to parse the byte stream into the equivalent JSON value instance.
class function ParseJSONValue(const Data: TBytes; const Offset: Integer): TJSONValue; overload; static;
For instance, given:
const
GJSONString =
'{' +
' "name": {'+
' "A JSON Object": {' +
' "id": "1"' +
' },' +
' "Another JSON Object": {' +
' "id": "2"' +
' }' +
' },' +
' "totalobjects": "2"' +
'}';
you can transform the JSON string representation into a JSON with one of the following code snippets.
- Using ParseJSONValue:
procedure ConsumeJsonString; var LJSONObject: TJSONObject; begin LJSONObject := nil; try { convert String to JSON } LJSONObject := TJSONObject.ParseJSONValue(TEncoding.UTF8.GetBytes(GJSONString), 0) as TJSONObject; { output the JSON to console as String } Writeln(LJSONObject.ToString); finally LJSONObject.Free; end;
- Using Parse:
procedure ConsumeJsonBytes; var LJSONObject: TJSONObject; begin LJSONObject := nil; try LJSONObject := TJsonObject.Create; { convert String to JSON } LJSONObject.Parse(BytesOf(GJSONString), 0); { output the JSON to console as String } Writeln(LJSONObject.ToString); finally LJSONObject.Free; end; end;
Both snippets would produce at the console:
{"name":{"A JSON Object":{"id":"1"},"Another JSON Object":{"id":"2"}},"totalobjects":"2"}
Lifecycle
In JSON, the parent object owns any of the values it contains, unless the Owned property is set to False. In this case, the destruction of a JSON object skips each member that has the flag set to False. This feature allows the combination of various objects into bigger objects while retaining ownership. By default, the property is True, meaning all contained instances are owned by their parent.
Cloning
All JSON types can be cloned. The cloning operation is a deep clone. The cloned object will own all of the JSON instances.
Server methods accept all JSON types as input, output, or return parameters, but they do not own any of them. The JSON instances are freed after the server method executes. One can read the JSON objects and react to the content, but if further storage is required, then the object must be cloned.