Discuss this help topic in SecureBlackbox Forum

Getting started

Classes for handling data in JSON format

JSON is a very simple text format that allows to maintain hierarchical data of different types. This format provides two complex types - object and array, and four simple types - boolean, number, string and null. Complex types can contain elements of simple of complex types.

SecureBlackbox provides the following classes to work with JSON entities:

• TElJsonEntity - the base abstract class; provides Clone() method which can be used to duplicate objects of all the descendant classes.
• TElJsonValue - allows to handle all the simple value types, including null.
• TElJsonArray - allows to handle an ordered collection of elements (array); elements can be of different types, including other arrays and objects.
• TElJsonObject - allows to handle a named collection of elements (object); elements can be of different types, including other objects and arrays. Each element has its own unique name (in this object).

Writing data in JSON format

it is possible to write instances of TElJsonObject and TElJsonArray classes to a text string, to a byte array or to a stream. Also, data can be written with formatting or without formatting. Formatting is very useful for debugging purposes when written data is analyzed by humans. Non-formatted text can be used if the size of the resulting data is important and there is no need to analyze the written data manually.

So, to write an instance of TElJsonObject and TElJsonArray classes to text with formatting, call Write() method, available in TElJSonEntity class:
C#

// with formatting
string data = file.Write(' ', 4);

// without formatting
string data = file.Write();

In the first example, the "data" string will contain the formatted text shown below (the second parameter specifies the character to be used to create hierarchy levels, the third parameter specifies the number of the characters to add on each level):

{
    "createdDate": "2015-11-06T10:20:00.950Z",
    "fileSize": 527272,
    "id": "0BxskCGtTdJauTGFTZ2dKZTE1Szg",
    "labels":
	  {
		"restricted": false,
		"starred": false,
		"trashed": false,
		"viewed": true
	  },
    "name": "test-small.bin",
    "owners":
	  [
		{
		    "displayName": "John Dow",
		    "reference": null
		}
	  ],
    "parents":
	  [
		"0ABskCGtTdJauUk9PVA"
	  ]
}

The same data written without formatting looks like the following (line breaks are inserted for comfortable view):

{"createdDate":"2015-11-06T10:20:00.950Z",
"fileSize":527272,
"id":"0BxskCGtTdJauTGFTZ2dKZTE1Szg",
"labels":{"restricted":false,"starred":false,"trashed":false,"viewed":true},
"name":"test-small.bin",
"owners":[{"displayName":"John Dow","reference":null}],
"parents":["0ABskCGtTdJauUk9PVA"]}

As you can see, formatted text is much more comfortable for human eyes but non-formatted (flat) text has a smaller size.

Also, there are other Write() functions available which allow to write data to a byte array or to a stream, either with formatting or without it.

Reading data in JSON format

In order to read data from JSON format, there are several static / shared / class Read() methods available in the TElJSonEntity class. Those functions allow to read data from a text string and from a byte array. The functions return the root element of the read data. This element must be of a complex type, i.e. an object (TElJsonObject) or an array (TElJsonArray). SecureBlackbox supports UTF-8, UTF-16LE and UTF-16BE encodings and handles them automatically to convert binary data to text. All whitespaces and line breaks are ignored.

If no object or array can be found in the buffer, an EElJsonError exception is raised.

If the expected data description allows both root types in the incoming data, you should read it as the following:
C#

var root = TElJSonEntity.Read(data);
if (root is TElJsonObject)
{
    // analyze the root object
    ...
}
else
{
    // analyze the root array
    ...
}

If only one type of the root element expected in the incoming data, it can be read as the following:
C#

// if the root must be an object
TElJsonObject root = TElJSonEntity.Read(data) as TElJsonObject;

// if the root must be an array
TElJsonArray root = TElJSonEntity.Read(data) as TElJsonArray;

How To articles about basic JSON questions

Discuss this help topic in SecureBlackbox Forum