• Created by user-5d3f2, last updated on Aug 24, 2022 3 minute read

XPRIM_JsonObject and XPRIM_JsonArray is an in-memory representation of JSON objects and JSON arrays. They store their child elements in a tree-like structure in memory, to support random access of elements by member name and array index. XPRIM_JsonObject and XPRIM_JsonArray have a common superclass, XPRIM_JsonElement.

As XPRIM_JsonObject/XPRIM_JsonArray are both readable and modifiable (with random access support), they are useful when you need to create an abstract, in-memory, representation of your JSON data, that you need to pass around, to another routine or any third-party library routines.

Note however that if you just need to construct a JSON string (that is, a string representation of a JSON data), you should use XPRIM_JsonWriter instead as XPRIM_JsonWriter is specifically designed to construct a JSON string, so it does that very efficiently, with a minimum memory footprint. Similarly, if you just need to parse a JSON string and read its values, you'd be better off using XPRIM_RandomAccessJsonReader or XPRIM_JsonReader. XPRIM_JsonWriter and XPRIM_JsonReader will be discussed in the next section.

Here is how you create an XPRIM_JsonObject and an XPRIM_JsonArray:

Define_Com Class(#XPRIM_JsonObject) Name(#RootObject)
Define_Com Class(#XPRIM_JsonArray) Name(#JsonArray)

You can then populate your JSON object or JSON array with values.

JSON data has 6 value types:

  • Null
  • String
  • Number
  • Boolean
  • Object
  • Array

Both XPRIM_JsonObject and XPRIM_JsonArray have the following methods that each correspond to the type of value it inserts to the object or array:

  • InsertNull
  • InsertString
  • InsertNumber
  • InsertBoolean
  • InsertElement (insert any kind of JSON element, including JSON array and object)

Note however that the XPRIM_JsonObject's Insert methods would have a Key parameter that specifies the property name of the value to be inserted, whereas the XPRIM_JsonArray's Insert methods wouldn't have a Key parameter as it would just append the value to the end of the array.

Examples:

* Insert a string "John" as the "name" property of a JSON object
#RootObject.InsertString Key('name') String('John')

* Insert a number 9 into a JSON array
#JsonArray.InsertNumber Number(9)

* Insert a NULL value as the "allergies" property of a JSON object
#RootObject.InsertNull Key('allergies')

The following example show how to create an object/array as a property of another object:

* Define an XPRIM_JsonObject reference
Define_Com Class(#XPRIM_JsonObject) Name(#ChildObject)

* Insert the street & suburb of the address into #ChildObject
#ChildObject.InsertString Key('street') String('122 Arthur St')
#ChildObject.InsertString Key('suburb') String('North Sydney')

* Insert #ChildObject into #RootObject as a member with name "address"
#RootObject.InsertElement Key('address') Element(#ChildObject)

If you want to convert your XPRIM_JsonObject (or XPRIM_JsonArray) into a string (for example for debugging purpose), call the SerializeAsString method.

Define_Com Class(#PRIM_DC.UnicodeString) Name(#MyJsonString)

* Convert JSON to a string
#MyJsonString := #RootObject.SerializeAsString

You can also serialize your JSON object (or array) into a file, using the SerializeToFile method.

#RootObject.SerializeToFile Path('/home/TestJson.txt')

You can also parse a JSON string and construct an XPRIM_JsonObject or XPRIM_JsonArray from the JSON string, using the ParseString and ParseFile methods.

* Define an ErrorInfo object to hold the error details
Define_Com Class(#XPRIM_ErrorInfo) Name(#ErrorInfo)

* Call the 'Parse' method
#RootObject.ParseString String(#JsonString) ErrorInfo(#ErrorInfo)

* Get the error message if parsing failed
If (*Not #ErrorInfo.OK)
    #ErrorMessage := #ErrorInfo.ErrorMessage
EndIf

You can access the values of an object or an array using one of the Get… accessor methods:

  • GetString
  • GetBoolean
  • GetNumber
  • GetObject
  • GetArray

For example, if you have a JSON string like this, stored in a variable called '#String':

{

    "name":
    {

        "given": "John",

        "surname": "Smith"

    },

    "age": 45,

    "contactNo":

    [

        { area: "02", no: "9378 2867", type: "landline" },

        { no: "0468 732 371", type: "mobile" }

    ]

}

To parse this JSON string and read its values:

Define_Com Class(#XPRIM_JsonObject) Name(#RootObject) Define_Com Class(#XPRIM_ErrorInfo) Name(#ErrorInfo)

* Parse JSON string
#RootObject.ParseString String(#String) ErrorInfo(#ErrorInfo)

* First check that the JSON string was parsed OK
If (#ErrorInfo.OK)
    * Get the values
    #GivenName := #RootItem.GetObject('name').GetString('given')
    #Surname := #RootItem.GetObject('name').GetString('surname')
    #Age := #RootItem.GetNumber('age')
Endif

You can use the ItemCount property to tell how many item an array (or object) contains.

Define_Com Class(#XPRIM_JsonArray) Name(#ContactNumbers)

* Get the contactNo value (which is an array), ...

* ... and assign to #ContactNumbers
#ContactNumbers.Refer To(#RootItem.GetArray('contactNo')

* Get the array length using the 'ItemCount' property
#ContactCount := #ContactNumbers.ItemCount

To iterate through elements in a JSON array, you can use the FOR-EACH-IN construct:

* Use the contactNo array from the previous example
FOR EACH(#Number) IN(#ContactNumbers)
   #COM_SELF.ProcessContactNumber Number(#Number)
ENDFOR

You can check the type of a JSON element (XPRIM_JsonElement) by reading its Type property, which will return one of the following values:

  • NULL
  • STRING
  • NUMBER
  • BOOLEAN
  • OBJECT
  • ARRAY

If you just want to check if a JSON element is of a certain type, you can use one of the Is… method:

  • IsNull
  • IsString
  • IsNumber
  • IsBoolean
  • IsObject
  • IsArray

Next: Using XPRIM_JsonWriter to Construct JSON Strings

  • No labels