Skip to main content

%pkg.isc.json.adaptor

abstract class %pkg.isc.json.adaptor

The following table displays the correspondence between JSON field values and property values that will be implemented by the JSON Adaptor.

The actual conversion between registered object values and JSON values will be done by new datatype methods: JSONToLogical and LogicalToJSON. In addition, a new JSONTYPE parameter will be introduced for the datatype classes which indicates how the data type will be mapped to JSON.

JSON                                            Registered object type
object                                          class referenced by property
array - error if all values are not literals    %ListOfDatatypes
array - error if all values are not objects     %ListOfObjects or relationship
array - error if all values are not literals    %List
string                                          %String, %Char, %Name, %FileCharacterStream, %GlobalCharacterStream
string - must be base64 encoded                 %Binary, %FileBinaryStream, %GlobalBinaryStream
string - ODBC format date                       %Date
string - ODBC format time                       %Time
string - ODBC format date/time                  %DateTime, %TimeStamp
numeric - bounds must match object type         %BigInt, %Currency, %Decimal, %Double, %Float, %Integer, %Numeric, %SmallInt, %TinyInt
boolean                                         %Boolean
Note that the types %xsd package are all subclasses of base % datatypes and will map as the super type.

Method Inventory

Parameters

parameter %JSONDEFAULTMAPPING = 1;
%JSONDEFAULTMAPPING may be set to 0 (default is 1) to suppress creation of the default JSON mapping for the object.
parameter %JSONENABLED = 1;
If this parameter is true then JSON-enabling methods will be generated. Otherwise, the method generators do not produce a runnable method.
parameter %JSONFIELDNAMEASCAMELCASE = 0;
%JSONFIELDNAMEASCAMELCASE auto-generates the %JSONFIELDNAME for properties (if not specified) as camelCase.
parameter %JSONIDFIELD = _id;
%JSONIDFIELD specifies the field name to use for the ID in representations of the object, if enabled by %JSONINCLUDEID
parameter %JSONIGNOREINVALIDFIELD = 0;
The %JSONIGNOREINVALIDFIELD parameter allows the programmer to control handling of unexpected fields in the JSON input. The default (%JSONIGNOREINVALIDFIELD = 0) will treat an unexpected field as an error. If %JSONIGNOREINVALIDFIELD is set = 1, then unexpected fields will be ignored.
parameter %JSONIGNORENULL = 0;
%JSONIGNORENULL allows the programmer to override the default handling of empty strings for string properties. This paramneter applies to only true strings which is determined by XSDTYPE = "string" as well as JSONTYPE="string" By default (%JSONIGNORENULL = 0), empty strings in the JSON input are stored as $c(0) and $c(0) is written to JSON as the string "". A missing field in the JSON input is always stored as "" and "" is always output to JSON according to the %JSONNULL parameter.
If %JSONIGNORENULL is set = 1, then both missing fields in the JSON and empty strings are input as "", and both "" and $c(0) are output as field values of "". The corresponding property parameter overrides this parameter if specified.
parameter %JSONINCLUDEID = 0;
%JSONINCLUDEID allows the ID to be included (output-only) in representations of the object.
parameter %JSONMAPPING;
%JSONMAPPING specifies a class-default JSON mapping to use for object projections of other classes.
parameter %JSONNULL = 0;
If %JSONNULL is true (=1), then unspecified properties are exported as the null value. Otherwise the field corresponding to the property is just skipped during export. The corresponding property parameter overrides this parameter if specified.
parameter %JSONREFERENCE = OBJECT;
%JSONREFERENCE specifies the default value of the %JSONREFERENCE property parameter that specifies how to project references to JSON. %JSONREFERENCE may be specified for any property to override this default value. Possible values of %JSONREFERENCE are "OBJECT", "ID", "OID", "GUID". ="OBJECT" is the default and indicates that the properties of the referenced class are used to represent the referenced object.
="ID" indicates that the id of a persistent or serial class is used to represent the reference.
="OID" indicates that the oid of a persistent or serial class is used to represent the reference. The form of the oid as projected to JSON will be classname,id.
="GUID" indicates the GUID of a persistent class is used to represent the reference.
The corresponding property parameter overrides this parameter if specified.

Methods

method %JSONExport(%mappingName As %String = "") as %Status
Serialize a JSON enabled class as a JSON document and write it to the current device.
mappingName is the name of the mapping to use for the export. The base mapping is represented by "" and is the default. If a mapping name is provided that does not exist, an error is thrown.
classmethod %JSONExportArray(list As %RawString, mappingName As %String = "", behavior As %DynamicObject = "", ByRef array As %DynamicArray, Output errorLog) as %Status
Export the provided list to a JSON array. array can be provided. Entries are appended to the end of the array.
The list can be one of the following:
If the class is NOT persistent:
  • %ListOfObjects: List of objects of the current class to export.
If the class is persistent:
  • %ListOfObjects: List of objects of the current class to export.
  • %List: List of IDs
  • %ListOfDataTypes: List of IDs
  • %DynamicArray: Array of IDs
  • %SQL.StatementResult: ResultSet where the ID column is used to identify records to export.
mappingName is the name of the mapping to get metadata for. The base mapping is represented by "" and is the default. If a mapping name is provided that does not exist, an error is thrown.
behavior has the following structure: 
{
	// Whether to accumulate errors instead of quitting on the first error encountered.
	// Default: true.
	"accumulateErrors": boolean;
}
errorLog contains errors that occurred indexed by the list index on which the error occurred. When accumulateErrors is false, this would have at most one entry.
errorLog(3) = "error status from importing index element 4 (5th element) in the JSON array"
errorLog(7) = "error status from importing index element 7 (8th element) in the JSON array"
method %JSONExportToDynamicObject(Output %export As %DynamicObject, %mappingName As %String = "") as %Status
Serialize a JSON enabled class as a JSON document and return it as JSON.
mappingName is the name of the mapping to use for the export. The base mapping is reprtesened by "" and is the default. If a mapping name is provided that does not exist, an error is thrown.
method %JSONExportToStream(ByRef export As %Stream.Object, %mappingName As %String = "") as %Status
Serialize a JSON enabled class as a JSON document and write it to a stream.
mappingName is the name of the mapping to use for the export. The base mapping is represetned by "" and is the default. If a mapping name is provided that does not exist, an error is thrown.
method %JSONExportToString(ByRef export As %String, %mappingName As %String = "") as %Status
Serialize a JSON enabled class as a JSON document and return it as a string.
mappingName is the name of the mapping to use for the export. The base mapping is represented by "" and is the default. If a mapping name is provided that does not exist, an error is thrown.
method %JSONImport(input, %mappingName As %String = "") as %Status
%JSONImport imports JSON or dynamic object input into this object.
The input argument is either JSON as a string or stream, or a subclass of %DynamicAbstractObject.
mappingName is the name of the mapping to use for the import. The base mapping is represented by "" and is the default. If a mapping name is provided that does not exist, an error is thrown.
classmethod %JSONImportArray(array As %DynamicArray, mappingName As %String = "", behavior As %DynamicObject = "", ByRef list As %ListOfObjects, Output errorLog) as %Status
Import an array of JSON records into a list of objects for this class. list can be provided. If not provided, one is created. Imported elements are added to the end of the list.
mappingName is the name of the mapping to use for the import. The base mapping is represented by "" and is the default.
If a mapping name is provided that does not exist, an error is thrown.
behavior has the following structure: 
{
	// Only valid for persistant records. Ignored if class is not persistent.
	// Default: false.
	"save": boolean;
	// Whether to accumulate errors instead of quitting on the first error encountered.
	// Default: true.
	"accumulateErrors": boolean;
}
errorLog contains errors that occurred indexed by the array index on which the error occurred. When accumulateErrors is false, this would have at most one entry.
errorLog(3) = "error status from importing index element 4 (5th element) in the JSON array"
errorLog(7) = "error status from importing index element 7 (8th element) in the JSON array"
classmethod %JSONMappingInfo(Output mappingInfo As %pkg.isc.json.mappingInfo, %mappingName As %String = "") as %Status
Returns metadata about a provided JSON mapping for the current JSON serializable class.
mappingName is the name of the mapping to get metadata for. The base mapping is represented by "" and is the default.
classmethod %JSONNew(dynamicObject As %DynamicObject, containerOref As %RegisteredObject = "", %mappingName As %String = "") as %RegisteredObject
Get an instance of an JSON enabled class.

You may override this method to do custom processing (such as initializing the object instance) before returning an instance of this class. However, this method should not be called directly from user code.
Arguments:
dynamicObject is the dynamic object with thee values to be assigned to the new object.
containerOref is the containing object instance when called from JSONImport.
mappingName is the name of the mapping to use for the export. The base mapping is represented by "" and is the default. If a mapping name is provided that does not exist, an error is thrown.
classmethod %JSONNewDefault(dynamicObject As %DynamicObject, containerOref As %RegisteredObject = "", %mappingName As %String = "") as %RegisteredObject
Generates default handling for JSONNew implementation. If overriding %JSONNew(), this can be called to retain the generated default handling (similar to calling super for non-generated but inherited methods)

Subclasses

FeedbackOpens in a new tab