Readers and Writers JSON Framework
Go Up to JSON
The readers and writers JSON framework provides classes and method to read and write JSON data to a stream.
- Note: RAD Studio has two frameworks to manage JSON data; you can see further details about the two frameworks in JSON.
With the readers and writers JSON framework, you can do the following:
- Writing JSON: You can use the TJSONObjectBuilder class to create a JSON object. The
TJSONObjectBuilderclass is a wrapper of the TJsonWriter class that provides the logic to serialize JSON data.
- Although you can write JSON objects using the
TJsonWriterclasses, we recommend that you use the
TJSONObjectBuilderclass, since it provides a fluent interface for writing JSON objects.
- See Writing JSON Objects for further details.
- Reading JSON: You can use the TJSONIterator class to iterate through the JSON data. The
TJSONIteratorclass is a wrapper of the TJsonReader class that allows you to read data serialized in JSON format.
- Although you can read JSON data using the
TJsonReaderclasses, we recommend that you use the
TJSONIteratorclass, since it provides additional features to move around the JSON data.
- See Reading JSON Objects for further details.
- Reading and Writing BSON Data: This framework allows you to read and write BSON data with the TBsonReader and TBsonWriter classes.
- See BSON for further details.
Writing JSON Objects
Use the System.JSON.Builders framework to write JSON objects. You need to create an instance of
TJSONObjectBuilder, and call the BeginObject method to start the JSON object. The
TJSONObjectBuilder.BeginObject method returns a TJSONCollectionBuilder.TPairs for method chaining.
The method chaining for writing the JSON includes the following classes:
- TJSONCollectionBuilder.TPairs: Used to add key and value pairs to a JSON object.
- TJSONCollectionBuilder.TElements: Used to add elements to a JSON array.
- TJSONCollectionBuilder.TParentCollection: Used to add key and value pairs to a JSON object, as well as to add elements to a JSON array. The
TParentCollectionclass represents the parent structure; this class is returned in methods such as
EndArray, because the parent could be a JSON object or a JSON array.
You do not need to create instances of the above classes, the required instances are returned during the method chaining as you call the methods.
Adding JSON Objects
BeginObject method to start an object.
Add to add key and value pair to the JSON object.
AddPairs to add several key and value pairs to the JSON object.
You may also call:
AddNullto add a key with
AddUndefinedto add a key with
AddMinKeyto add a key with
AddMaxKeyto add a key with
EndObject method to end the object.
Adding JSON Arrays
BeginArray method to start an array.
Add to add a value to the JSON array.
AddElements to add several values to a JSON array.
You may also call:
AddNullto add a
AddUndefinedto add an
AddMinKeyto add a
AddMaxKeyto add a
EndArray method to end the array.
Ending JSON Objects and Arrays
You can call
EndArray to end objects and arrays respectively, you can also call
EndAll to end the entire structure at once.
Reading JSON Objects
Use the System.JSON.Builders framework to read JSON objects.
Use the Next method to move to the first item of the JSON. Keep calling
Next to move to the following items of the current JSON level.
To move directly to a particular value, object, or array, you can call the
Next method passing the name of the item you want to move to, this item must be in the same JSON level structure as the iterator. If the iterator is in an array, you can call
Next passing the array index as a string to move directly to that array item. Use Index to get the current index of the array you are reading.
Index returns -1 when you are not reading an array.
Use the Rewind method to move the iterator to the beginning of the JSON data.
To find a particular item, use the Find method, and indicate the path of the item you want to find. This method returns
True if the item has been found, and moves the iterator to such item. You can use this method to move through different JSON levels; you must indicate the full path to the item using a dot notation, such as
- Note: The
Findmethods raise an exception if you did not pass a rewind procedure when creating the iterator.
Moving Through JSON Levels
- Entering an Array or Object Structure
- Moving around the JSON using
Nextmoves through the current level of the JSON. To enter an array or an object, call Recurse before moving the iterator to a JSON token with
StartObjecttypes, and call
Recurseagain right after calling
Nextto move to the
StartObjecttoken to enter such array or object.
- Exiting an Array or Object Structure
- When you are ready to exit a structure and move to the parent level, use Return; this method skips the remaining content of the array or object, if any, and moves back to the parent array or object.
- Use Depth to know the depth of the level where the iterator currently is.
Reading JSON Items
- Reading Keys
- Use Key to read the name of the current item.
Keyindicates the name of the item that the iterator is reading at that moment, whether it is the name of an object, the name of an array, the index of the array, or the name of the key in the case of key/value pairs.
- Reading Values
- To read a value, you need to know its Type, since you need to use the appropriate property according to the type. For example, to access the value of an item with String type, you need to use the AsString property.
- See the value properties table for further details about what properties to use according to the Type of value you are reading.
- JSON Objects Framework