Public Class JsonConversionHelper

Code Sample

• %REM
  Converts a string of JSON to a Person object. The code is taken from the first deserialization example.
  %REM
  Dim json as String
  Dim helper as New JsonConversionHelper()
  Dim jd as Person
  
  json = |{"firstName":"John","lastName":"Doe","age":42}|
  Set jd = helper.fromJsonString(json, "Person", "deser-10")

Properties Detail

• suppressErrors (Get)

  Public Property Get suppressErrors As Boolean

• suppressErrors (Set)

  Public Property Set suppressErrors As Boolean

Methods Detail

• fromJson

  Public Function fromJson(obj As JsonObject) As Variant
  Main function to deserialize a JSON object to a VoltScript object.
  idx	Argument	Data Type	Attributes	Comments
  1	obj	JsonObject		JSON object to deserialize
  Code Sample
  %REM Converts a VoltScript JsonObject to an instance of a class. A custom constructor, custom converters and configuration to ignore labels may be added before calling fromJson(). %END REM Dim helper as New JsonConversionHelper Call helper.fromJson(jsonObj, "Person", "PersonClass")

• fromJsonString

  Public Function fromJsonString(source As String, className As String, libName As String) As Variant
  Parses JSON string and calls fromJson which creates an array or object.
  idx	Argument	Data Type	Attributes	Comments
  1	source	String		String of JSON to parse
  2	className	String		Class name to create object for
  3	libName	String		Script containing className
  Code Sample
  %REM Converts a string of JSON to an instance of a class. A custom constructor, custom converters and configuration to ignore labels may be added before calling fromJson(). %END REM Dim helper as New JsonConversionHelper Dim js as Person Dim json as String json = |{"firstName":"John","lastName":"Doe","age":42}| Set jd = helper.fromJsonString(json, "Person", "PersonClass")

• getCustomConverter

  Public Function getCustomConverter(labelName As String) As AbstractJsonConverter
  Returns the custom converter for a label, if it exists.
  idx	Argument	Data Type	Attributes	Comments
  1	labelName	String		Label to match against
  Code Sample
  %REM The code is an abbreviated version of code found in JsonConversionHelper.fromJson(). For a given JSON object (child) gets a converter based on the JSON object's label (elemName) and, if the converter exists, calls its deserialize method to convert the JSON object into mainHolder. %END REM Dim converter as AbstractJsonConverter Dim elemName as String elemName = child.label Set converter = Me.getCustomConverter(elemName) If Not converter is Nothing Then converter.deserialize(Me.mainHolder, child) End If

• ignoreLabel

  Public Function ignoreLabel(labelToIgnore As String) As JsonConversionHelper
  Specifies a label to skip when parsing the JSON. The check is case-sensitive, so casing needs to match the casing in the JSON object.
  idx	Argument	Data Type	Attributes	Comments
  1	labelToIgnore	String		Label in JSON being parsed
  Code Sample
  %REM When the helper parses all the labels in a JSON object to convert it from JSON to a VoltScript object, the code will skip the label "ipaddress". %END REM Dim helper as New JsonConversionHelper Call helper.ignoreLabel("ipaddress")

• jsonArrayToObjects

  Public Function jsonArrayToObjects(array As JsonObject, className As String, libName As String) As Variant
  Converts an array to objects create with a constructor that takes no parameters.
  idx	Argument	Data Type	Attributes	Comments
  1	array	JsonObject		Array of JSON objects
  2	className	String		Class name to create object for
  3	libName	String		Script containing className
  Code Sample
  %REM This code is from deser-10.txt sample 4. Converts the JsonObject (obj) to a Variant array of Person objects. %END REM Dim parser as New JsonParser Dim obj as JsonObject Dim helper as New JsonConversionHelper Dim arr as Variant Call parser.loadFromJson(|{"success": true, "data": [{"firstName":"John","lastName":"Doe","age":42},{"firstName":"Jane","lastName":"Doe","age":30}]}|) Set obj = parser.getRootObject().getChild("data") arr = helper.jsonArrayToObjects(obj, "Person", "PersonClass")

• reset

  Public Function reset() As JsonConversionHelper
  Resets the holder object containing the return value. This allows you to re-use the helper.
  Code Sample
  %REM Uses a helper to deserialize JSON to a Person object, then resets it so it can be re-used by subsequent code. The mainHolder property will be re-initialized, but all converters or labels to ignore will still exist in the helper. So subsequent calls will also ignore "gender" label. %END REM Dim json as String Dim helper as New JsonConversionHelper() Dim jd as Person json = |{"firstName":"John","lastName":"Doe","age":42,"gender":"M"}| Set jd = helper.ignoreLabel("gender").fromJsonString(json, "Person", "PersonClass") Call helper.reset()

• shouldIgnoreLabel

  Public Function shouldIgnoreLabel(labelName As String) As Boolean
  Checks whether to skip a label when parsing the JSON
  idx	Argument	Data Type	Attributes	Comments
  1	labelName	String		Label in JSON being parsed
  Code Sample
  %REM The code will print true for whether "gender" should be ignored, but false for "firstName" %END REM Dim json as String Dim helper as New JsonConversionHelper() Dim jd as Person json = |{"firstName":"John","lastName":"Doe","age":42,"gender":"M"}| Set jd = helper.ignoreLabel("gender").fromJsonString(json, "Person", "PersonClass") Print helper.shouldIgnoreLabel("gender") Print helper.shouldIgnoreLabel("firstName")

• toJson

  Public Function toJson(obj As Variant) As JsonObject
  Main functon to serialize a VoltScript object / array to a JSON object
  idx	Argument	Data Type	Attributes	Comments
  1	obj	Variant		VoltScript object or array of VoltScript objects to serialize
  Code Sample
  %REM Creates a person and converts it to a JsonObject %END REM Dim helper as New JsonConversionHelper() Dim jsonObj as JsonObject Dim jd as New Person jd.firstName = "John" jd.lastName = "Doe" jd.age = 42 Call helper.withScalarConverter("firstName").withScalarConverter("lastName").withScalarConverter("age") Set jsonObj = helper.toJson(jd)

• toJsonString

  Public Function toJsonString(obj As Variant, prettify As Boolean) As String
  Main function to serialize a VoltScript object / array to a string
  idx	Argument	Data Type	Attributes	Comments
  1	obj	Variant		VoltScript object or array of VoltScript objects to serialize
  2	prettify	Boolean		Output prettified JSON string or compressed
  Code Sample
  %REM Creates a person and converts it to a string of pretty-printed JSON %END REM Dim helper as New JsonConversionHelper() Dim jd as New Person jd.firstName = "John" jd.lastName = "Doe" jd.age = 42 Call helper.withScalarConverter("firstName").withScalarConverter("lastName").withScalarConverter("age") Print helper.toJsonString(jd, true)

• toObject

  Public Function toObject(source As JsonObject, className As String, libName As String) As JsonConversionHelper
  Passes a JSON object to the helper and tells it what object type to create, defined in which file.
  idx	Argument	Data Type	Attributes	Comments
  1	source	JsonObject		JSON object to deserialize
  2	className	String		Class to create an instance of
  3	libName	String		Script where the class is defined
  Code Sample
  %REM Creates a custom constructor to call a Pet's New method, which takes two parameters - name and type, in that order. This code is found in deser-80 sample. %END REM Dim pet as Pet Dim helper as New JsonConversionHelper Dim petConstructor as New JsonCustomConstructor() Call petConstructor.withParm("name", "").withParam("type", "") Set pet = helper.withCustomCostructor(petConstructor)._ toObject(source, "Pet", "deser-80")._ fromJson(source)

• withArrayConverter

  Public Function withArrayConverter(labelName As String) As JsonConversionHelper
  Adds an array converter to this object
  idx	Argument	Data Type	Attributes	Comments
  1	labelName	String		Label to look for in the JSON object (for deserialization) or VoltScript object (for serialization)
  Code Sample
  %REM The following code is from ser-20.txt sample 1. Converts a Session object to a String, outputting "id" and "title" as strings, and using an arrayConverter to convert the "products" property of the Session (a Variant array) to a JSON array. %END REM Dim sess as New Session Dim json as String Dim helper as New JsonConversionHelper sess.id = "Ad16" sess.title = "Collaborate around Business Applications in Communities" sess.products = Split("Domino,Connections,Volt", ",") Call helper.withScalarConverter("id").withScalarConverter("title").withArrayConverter("products") json = helper.toJsonString(sess, true)

• withCustomConstructor

  Public Function withCustomConstructor(constructor As JsonCustomConstructor) As JsonConversionHelper
  Passes a custom constructor to use to create the object during deserialization
  idx	Argument	Data Type	Attributes	Comments
  1	constructor	JsonCustomConstructor		Custom constructor to use for creating the object
  Code Sample
  %REM The code below calls the Session class's New method passing two parameters, the JSON object's "id" and "title" elements, in that order. The code can be found in the deser-70.txt example. %END REM Dim sess as Session Dim helper as New JsonConversionHelper Dim sessionConstructor as New JsonCustomConstructor Dim json as String json = |{"id":"Ad01","title":"Domino HA"}| Call sessionConstructor.withParam("id", "").withTitle("title", "") Set sess = helper.withCustomConstructor(sessionConstructor).fromJsonString(json, "Session", "deser-70")

• withCustomConverter

  Public Function withCustomConverter(labelName As String, converter As AbstractJsonConverter) As JsonConversionHelper
  Adds a custom converter to this object
  idx	Argument	Data Type	Attributes	Comments
  1	labelName	String		Label to look for in the JSON object (for deserialization) or VoltScript object (for serialization)
  2	converter	AbstractJsonConverter		Custom converter to apply
  Code Sample
  %REM Ensures that when extracting the gender element from a JSON object, the target class's setGender method is called with the literal value "M". This is found in the CustomSetterTest sample, a hard-coded test for validation purposes only. %END REM Dim helper as New JsonConversionHelper Dim genderConverter as New JsonSetterConverter() Call genderConverter.forSetter(setGender).withLiteralParam("M") Call helper.withCustomConverter("gender", genderConverter)

• withObject

  Public Function withObject(object As Variant) As JsonConversionHelper
  Passes an existing object into the helper, so you can merge content from an additional JSON object into it.
  idx	Argument	Data Type	Attributes	Comments
  1	object	Variant		Object to merge properties into
  Code Sample
  %REM Converts a string of JSON to a Person object. The code is taken from the first deserialization example. %REM Dim json as String Dim parser as New JsonParser Dim helper as New JsonConversionHelper() Dim jd as New Person json = |{"firstName":"John","lastName":"Doe","age":42}| Call parser.loadFromJson(json) Call helper.withObject*jd).fromJson(parser.getRootObject)

• withScalarConverter

  Public Function withScalarConverter(labelName As String) As JsonConversionHelper
  Adds a scalar converter to this object
  idx	Argument	Data Type	Attributes	Comments
  1	labelName	String		Label to look for in the JSON object (for deserialization) or VoltScript object (for serialization)
  Code Sample
  %REM Creates a person and converts it to a JsonObject. Converts strings to JSON strings, numerics to JSON numbers. %END REM Dim helper as New JsonConversionHelper() Dim jsonObj as JsonObject Dim jd as New Person jd.firstName = "John" jd.lastName = "Doe" jd.age = 42 Call helper.withScalarConverter("firstName").withScalarConverter("lastName").withScalarConverter("age") Set jsonObj = helper.toJson(jd)

• disableDebug

  Public Sub disableDebug()
  Disables debug printing, switched off by default.
  Code Sample
  %REM Enables debug for the duration of converting a string of JSON to a Person, then disables debug again. The use case for this would be that deserialization is not working, so the developer is trying to trace progress to see where it is failing. %END REM Dim helper as New JsonConversionHelper Call helper.enableDebug() Call helper.fromJsonString(json, "Person", "PersonClass") Call helper.disableDebug()

• Delete

  Public Sub Delete()
  Destructor, outputs (if in debug) which functions have been logged as encountered and erases converters List.

• enableDebug

  Public Sub enableDebug()
  Enables debug printing, switched off by default.
  Code Sample
  %REM Enables debug for the duration of converting a string of JSON to a Person, then disables debug again. The use case for this would be that deserialization is not working, so the developer is trying to trace progress to see where it is failing. %END REM Dim helper as New JsonConversionHelper Call helper.enableDebug() Call helper.fromJsonString(json, "Person", "PersonClass") Call helper.disableDebug()

• New

  Public Sub New()
  Constructor