Readers and Writers JSON Framework

From RAD Studio
Jump to: navigation, search

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 TJSONObjectBuilder class is a wrapper of the TJsonWriter class that provides the logic to serialize JSON data.
Although you can write JSON objects using the TJSONObjectBuilder or TJsonWriter classes, we recommend that you use the TJSONObjectBuilder class, 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 TJSONIterator class 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 TJSONIterator or TJsonReader classes, we recommend that you use the TJSONIterator class, 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:

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

Use the BeginObject method to start an object.

Call Add to add key and value pair to the JSON object.

Call AddPairs to add several key and value pairs to the JSON object.

You may also call:

  • AddNull to add a key with null value.
  • AddUndefined to add a key with undefined value.
  • AddMinKey to add a key with MinKey value.
  • AddMaxKey to add a key with MaxKey value.

Call the EndObject method to end the object.

Adding JSON Arrays

Use the BeginArray method to start an array.

Call Add to add a value to the JSON array.

Call AddElements to add several values to a JSON array.

You may also call:

  • AddNull to add a null value.
  • AddUndefined to add an undefined value.
  • AddMinKey to add a MinKey value.
  • AddMaxKey to add a MaxKey value.

Call the EndArray method to end the array.

Ending JSON Objects and Arrays

You can call EndObject and 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.

You need to create an instance of TJSONIterator indicating the JSON reader that contains the JSON data.

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 'entities.urls[0].indices[1]'.

Note: The Rewind and Find methods 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 Next moves 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 StartArray or StartObject types, and call Recurse again right after calling Next to move to the StartArray or StartObject token 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. Key indicates 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.

See Also

Code Samples

Retrieved from "https://docwiki.embarcadero.com/RADStudio/Tokyo/e/index.php?title=Readers_and_Writers_JSON_Framework&oldid=258782"