Data.DBXJSONReflect.TTypeMarshaller
Delphi
TTypeMarshaller<TSerial: class> = class(TMarshalUnmarshalBase)
C++
template<typename TSerial> class PASCALIMPLEMENTATION TTypeMarshaller__1 : public TMarshalUnmarshalBase
Properties
| Type | Visibility | Source | Unit | Parent |
|---|---|---|---|---|
| class | public | Data.DBXJSONReflect.pas Data.DBXJSONReflect.hpp |
Data.DBXJSONReflect | Data.DBXJSONReflect |
Description
Represents the marshaling parent class.
The DBXJSONReflect unit represents a lightweight framework for object serialization with a concrete focus on JSON objects. It allows the user to convert any user object into a serializable object (such as JSON, XML, and so on), and back.
The conversion into a serializable object is called marshaling. The TJSONMarshal class converts user objects into TJSONValue objects. The reverse process is called unmarshaling. TJSONUnMarshal reverts a TJSONValue back into a user object.
Marshalling is done based on a visitor pattern, implemented by the TTypeMarshaller class. On predetermined situations, events are emitted. The following table contains the list of situations that can occur during marshaling.
| Situation | Event |
|---|---|
|
A new object is encountered. |
|
|
An already visited object is encountered. |
|
|
A new object content was revisited. |
|
|
A new field is encountered. |
|
|
A new field is visited. |
|
|
A string value is encountered. |
|
|
A numeric value is encountered. |
|
|
A nil value is encountered. |
|
|
A Boolean value is encountered. |
|
|
A list value is encountered. |
|
|
A list is finished processing. |
The events are received by a TConverter instance. They are imbricated, depending on the structure of the user object. Based on the events ant their arguments, the TConverter instance builds an equivalent image of the user object. A JSON converter is implemented by TJSONConverter.
The object image built by the converter can be used for persistency, remoting, and so on. That image can be used to reconstitute the original user object, using reverter events driven by an unmarshaler. TJSONUnMarshal uses a JSON image to restore the user object. The unmarshaling is a simpler process that uses RTTI to reconstitute the user object. It is assumed that the user object has a no-argument constructor.
The marshaling process transforms all fields into strings, numbers, and Boolean values. To transform more complex fields, it requires user converters/reverters. Both user converters and reverters can be registered with the marshaler and unmarshaler instance, before any processing.
Converters and reverters can be registered against a type and a field, or for a type. Any field declared of that type is processed by the provided user converter/reverter. A field registered converter/reverter takes precedence over a type converter/reverter.
A field converter can transform a field value into a string, an object, a list of strings, or a list of objects. The contract is that those transformed values will be passed as arguments to the correspondent reverter to reconstitute the field value.
A type converter can transform a value into a string, an object, a list of strings, or a list of objects. These will be passed as arguments to the type reverter that will reconstitute the original type instance.
For example, a TStringList field can be converted into an array of strings by a converter, and a reverter can use the list of strings to create and populate an instance of TStringList. This is the degree of complexity expected by a user-defined converter/reverter.
As RTTI becomes more powerful and more metadata will be stored in library code, the need for user-defined converters will subside.
These are the fields for which there is already a built-in conversion/reversion: integer, string, char, enumeration, float, object, record. For the following types, the field values are ignored and user conversion is expected: set, method, variant, interface, pointer, dynArray, classRef, array.
TTypeMarshaller has object ID-marker support and converter registration support. A specialization of this class usually provides the serialization type.