%JSON.Adaptor

Class %JSON.Adaptor [ Abstract, PropertyClass = %JSON.PropertyParameters, System = 3 ]

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.

Parameters

%JSONENABLED

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.

%JSONIGNOREINVALIDFIELD

Parameter %JSONIGNOREINVALIDFIELD As BOOLEAN = 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.

%JSONNULL

Parameter %JSONNULL As BOOLEAN = 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.

%JSONIGNORENULL

Parameter %JSONIGNORENULL As BOOLEAN = 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.

%JSONREFERENCE

Parameter %JSONREFERENCE As STRING [ Constraint = "OBJECT,ID,OID,GUID", Flags = ENUM ] = "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

%JSONImport

Method %JSONImport(input, %mappingName As %String = "") As %Status [ ServerOnly = 1 ]

%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.

%JSONNew

ClassMethod %JSONNew(dynamicObject As %DynamicObject, containerOref As %RegisteredObject = "") As %RegisteredObject [ CodeMode = generator, GenerateAfter = %JSONGenerate, ServerOnly = 1 ]

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.

%JSONExport

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.

%JSONExportToStream

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 represented by "" and is the default.

%JSONExportToString

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.

%JSONX

Method %JSONX() [ Abstract, Internal, ServerOnly = 1 ]

Dummy method which exists to force GenerateAfter code to take affect for %JSONGenerate. The GenerateAfter will not have affect unless the after method is laterin collating sequence. All this is necessary to force geenrator methods to be run after member methods are created. This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.

%JSONGenerate

ClassMethod %JSONGenerate() [ CodeMode = generator, GenerateAfter = %JSONX, Internal, ServerOnly = 1 ]

%JSONGenerate is an internal method that controls the generation of the other methods in %JSON.Adaptor. If %JSONGenerate is overridden, then JSON meta data and the other generator methods of %JSON.Adaptor will not be created.

%JSONImportInternal

Method %JSONImportInternal() As %Status [ CodeMode = generator, GenerateAfter = %JSONGenerate, Internal, ServerOnly = 1 ]

%JSONImportInternal is internal method used by %JSONImport

%JSONExportInternal

Method %JSONExportInternal() As %Status [ CodeMode = generator, GenerateAfter = %JSONGenerate, Internal, ServerOnly = 1 ]

%JSONExportInternal is internal method used by %JSONExport

%JSONExportToStringInternal

Method %JSONExportToStringInternal() As %Status [ CodeMode = generator, GenerateAfter = %JSONGenerate, Internal, ServerOnly = 1 ]

%JSONExportToStringInternal is internal method used by %JSONExport