Creating json and jsonarray values from strings

json and jsonarray variables can be populated by casting from strings. See, for example, how this can be done for string literals using multiline string declaration as follows:

json jsonPerson = /%
	{
		"name": "Jack",
		"surname": "Marques",
		"phoneNumber": "555-6162"
	}
%/;

jsonarray jsonPeople = /%
	[
		{
            "name": "Jack",
            "surname": "Marques",
            "phoneNumber": "555-6162"
        },
        {
            "name": "Bevin",
            "surname": "Sharp",
            "phoneNumber": "555-0123"
        }
    ]
%/;

Note, that no compile time validation is done to validate that the values being converted represents correctly formatted JSON. This means that if any such conversion issues were to arise, it will only be at runtime.

Any conversion errors will result in an error message being logged to the Helium Logging Service:

< {"id":"ca7963c5-4d5d-44e9-ba65-dcbb68127b9f","key":"Runtime Error","value":"[PersonResourceV2:23] {\n            \"name\": \"Jack\",\n            \"surname\": \"Marques\",\n            \"phoneNumber\": \"555-6162\n        } could not be converted to a com.mezzanine.program.web.core.type.JsonType@577db227 value","millis":1536562229362,"appId":"a7c76024-b379-49e4-a3c0-bd2ef30d28ab","appUserId":null}

In addition to the above conversion error, the result of the conversion will be null. This might lead to unexpected null pointer exceptions if not handled appropriately in DSL apps.

Although casting from string values to json and jsonarray might be quick and useful in some specific cases, its uses might be limited. In addition, if the values are constructed "by hand", there is a high probability of undesirable runtime errors.

Another approach for constructing JSON values in a DSL app, is to make use of objects and the existing built-in functions namely jsonGet, jsonPut, jsonRemove, jsonKeys, jsonContains.

See the sections below for details.

Creating json and jsonarray values from objects

json and jsonarray variables can be populated by casting from objects and object collections respectively.

Consider the following model object:

object Person { 
	string name; 
	string surname; 
	date dob; 
	json contactDetails; 
}

Casting to json can be done implicitly as follows:

Person person = getPersonFromDb(...);
json personJson = person;

The above will create the following example json:

{
	"_id": "b9bf8965-087f-47a1-8b9b-ab77a01a494d"
	"name": "John",
	"surname": "Doe",
	"dob": 1738846993000,
	"contactDetails": {
		"phoneNumber": "555-6162",
		"emailAddress": "john.doe@gmail.com"
	}
}

Note that the object id is included under the property with name _id.

Relationships (many to one or one to one) will be included and the value or the related object's internal id will be used.

Similarly a jsonarray value can be created by using an object collection:

Person[] people = getPeopleFromDb();
jsonarray peopleJson = people;

Manipulating jsonarray values

At present, no built-in functions are provided to help with the construction of jsonarray variables. Implicit casting between any primitive or object collection and jsonarray and between collections of json and jsonarray is, however, provided:

// Create parent as emergency contact
json parentEmergencyContact = "{}";
parentEmergencyContact.jsonPut("description", "parent");
parentEmergencyContact.jsonPut("mobileNumber", "27763300000");
 
// Create spouse as emergency contact
json spouseEmergencyContact = "{}";
spouseEmergencyContact.jsonPut("description", "spouse");
spouseEmergencyContact.jsonPut("mobileNumber", "27763300001");
 
// Create a json[] of the above
json[] emergencyContacts;
emergencyContacts.append(parentEmergencyContact);
emergencyContacts.append(spouseEmergencyContact);
 
// Cast it to jsonarray so we can add it to the json object
jsonarray emergencyContactsArray = emergencyContacts;
 
// Add it to the person object
jsonPersonObject.jsonPut("emergencyContacts", emergencyContactsArray);

To retrieve the individual values one can make use of jsonGet and implicit casting to json[]:

// Retrieve the emergency contacts
jsonarray retrievedEmergencyContacts = jsonPersonObject.jsonGet("emergencyContacts");
 
// Cast back to json[]
json[] convertedEmergencyContacts = retrievedEmergencyContacts;
 
// Iterate over or reference as normal DSL collection
foreach(json currentEmergencyContact: convertedEmergencyContacts) {
	.
	.
	.
}
 
json firstEmergencyContact = convertedEmergencyContacts.get(0);

Note that casting from jsonarray to json[] is a relatively expensive operation and if possible, it should be avoided for large arrays.

The example below describes the same concepts as discussed above.

json pet1 = /%
	{
		"name": "Jasmine",
		"type": "Dog"
	}
%/;
    
json pet2 = /%
	{
		"name": "Markus",
		"type": "Mole-rat"
	}
%/;
 
json[] petsArray;
petsArray.append(pet1);
petsArray.append(pet2);
 
// json[] converted to jsonarray
jsonarray petsJsonArray = petsArray;
 
// jsonarray converted json[]
json[] convertedPetsArray = petsJsonArray;

In the above examples the implicit casting between json[] and jsonarray is shown. Casting to primitive arrays is also supported:

int[] numbersPrimitiveArray;
numbersPrimitiveArray.append(1);
numbersPrimitiveArray.append(2);
numbersPrimitiveArray.append(3);
 
// int[] converted to jsonarray
jsonarray numbersJsonArray = numbersPrimitiveArray;
 
// jsonarray converted back to int[]
int[] numbersPrimitiveArray2 = numbersJsonArray;

// string representing a number array in json format converted to jsonarray
jsonarray primeNumbersJsonArray = /%[2, 3, 5, 7, 11, 13, 17, 19, 23, 29]%/;
 
// jsonarray converted to int[]
int[] primeNumbersPrimitiveArray = primeNumbersJsonArray;

JSON Values as Object Attributes

Lets consider a different example where a Person object is created to represent most of the attributes of a person while including a single json attribute to represent the contact details of a person:

@NotTracked
persistent object Person {
    string name;
    string surname;
    date dob;
    json contactDetails;
}

Currently integration between Helium and Journey does not support JSON types. Note the inclusion of the NotTracked annotation above to avoid any possible syncing for this object. This is compulsory for any persistent object that contains a json or jsonarray attribute.

If the NotTracked annotation is not included for persistent objects containing json or jsonarray attributes, a compiler error will generated:

Loading source files...
Compiling the application...
|--------------------------------------------------------------------------------------------------------------------------------------------|
| The module "Web" generated the following errors                                                                                            |
|--------------------------------------------------------------------------------------------------------------------------------------------|
| #     | Message                                                                                                                            |
|--------------------------------------------------------------------------------------------------------------------------------------------|
| 1     | [Person:2] The custom object Person is persistent, thus needs to be marked with @NotTracked if json attribute types are declared.  |
|--------------------------------------------------------------------------------------------------------------------------------------------|

Inspecting the database table created by Helium for the Person object, reveals the contactdetails column represented by the jsonb type in PostgreSQL. Both json and jsonarray types will be represented on PostgreSQL as jsonb.

helium-app-1=# \d person
                                  Table "snapshot_1535373223392_001.person"
     Column     |            Type             |                          Modifiers                           
----------------+-----------------------------+--------------------------------------------------------------
 _id_           | uuid                        | not null
 _tstamp_       | timestamp without time zone | not null
 person         | text                        | 
 _tx_id_        | bigint                      | not null default txid_current()
 _change_type_  | __he_obj_change_type__      | not null default 'create'::__he_obj_change_type__
 _change_seq_   | bigint                      | not null default nextval('__he_sync_change_seq__'::regclass)
 name           | text                        | 
 surname        | text                        | 
 dob            | date                        | 
 contactdetails | jsonb                       | 
Indexes:
    "person_pkey" PRIMARY KEY, btree (_id_)
    "__idx_he_sync_person_txid__" btree (_tx_id_)

Any method of populating attributes in general is also applicable to JSON attributes. This includes the use of database functions.

Helium Journey integration does not currently support objects with json or jsonarray attributes. For this reason, any persistent objects with json or jsonarray attributes need to be annotated with NotTracked.

Failure to do so will result in a compiler error.

Browser not supported