HSMOD.REST.SerializationProxy

abstract class HSMOD.REST.SerializationProxy extends %Library.RegisteredObject

Common base class for serializing persistent classes for the purposes of REST-enabled application modules. If the class and all its contents are registered only (not persistent), then this machinery is unnecessary. If the properties of the proxy are datatypes, non-swizzlable registered classes and/or other serialization proxy classes, then we can generate methods for serializing and de-serializing. Currently does not handle serial objects.

Suppose we have a persistent class and we want to send and receive JSON representations of that class. The serialization class acts as an intermediary and has methods to generate itself from the persistent class, as well as to create or find-and-update the existing persistent object using the values in a proxy object. If the class has an IdKey, it is used to find and open existing objects; otherwise the proxy class must have a designated property for storing the internal ID (identified via a class parameter). The serialization class is then what's used generate the JSON, and vice versa.

The proxy deals with only an explicit subset of the properties; we do not automatically generate properties for the proxy.

The proxy object has no built-in machinery for serializing or de-serializing itself to/from JSON. The assumption is that the modules will use the HS.JSON module's read/write methods for that.

Each such class needs to be specifically extended from HSMOD.REST.SerializationProxy, typically by simply specifying properties. Properties in the serialization class must have the same name as a property in the associated class, and will be associated automatically. The extension would typically be in a "Foo.Auxil" package of an application or module.

Method Inventory

• CreateFromObject()
• PopulateFromObject()
• ProduceObjectFromContent()

Parameters

parameter IDPROPERTY;

default is left empty to support classes with custom IdKeys. In most cases the serialization class will have a custom property called IdValue or similar, which should be specified here. @API.Parameter

parameter PARTNERCLASS;

the name of the class that the current serialization proxy class represents @API.Parameter

parameter UNIQUEINDEXNAME;

the name of the unique index to use to locate an existing target object in ProduceObjectFromContent if unspecified, and if IDPROPERTY is not overridden, the partner class's IDKEY index will be used instead.

Methods

classmethod CreateFromObject(pSourceObject As %Persistent, Output pNewObject As HSMOD.REST.SerializationProxy) as %Status

given a persistent object of the proper class, create a new serialization proxy object and return it @API.Method

method PopulateFromObject(pSourceObject As %Persistent) as %Status

Implementation for instantiating and populating the serialization class from the original persistent object. Default behavior is to loop through the properties of the serialization class and match them to identically-named properties in the partner class. For the %Id(), we use whatever's identified by the IDPROPERTY parameter. If this base implementation is insufficient, it can be overridden with custom (non-generated) code. @API.Method

method ProduceObjectFromContent(Output pTargetObject As %Persistent) as %Status

if the current serialization object represents an existing (saved) object, this method instantiates the existing "real" object, copies property values, and returns it (without saving). If it represents new data, this method creates a new instance of the "real" class, populates it, and returns (without saving). @API.Method