Summary

TDeserializer is the base class type for de-serializer objects, which can restore, previously serialized by TSerializer descendants values of various data types from different formats, such as Binary, XML or JSON.

Syntax

TDeserializer = class abstract

Constructors

	Name	Description
	Create

Top

Methods

	Name	Description
	BeginArray	BeginArray method is a low-level method, which allows to de-serialize array like data manually. Every call to BeginArray method should be matched by a call to NG.Serialization.TDeserializer.EndArray method.
	BeginObject(string)	BeginObject method is a low-level method, which allows to de-serialize object like data manually. Every call to BeginObject method should be matched by a call to NG.Serialization.TDeserializer.EndObject method.
	BeginObject	BeginObject method is a low-level method, which allows to de-serialize object like data manually. Every call to BeginObject method should be matched by a call to NG.Serialization.TDeserializer.EndObject method.
	DoBeginArray
	DoBeginObject
	DoEndArray
	DoEndObject
	DoIsNull
	DoNext
	DoRead
	DoSkip
	EndArray	EndArray method should be called to finalize array data de-serialization started by NG.Serialization.TDeserializer.BeginArray method. For more information look NG.Serialization.TDeserializer.BeginArray method description.
	EndObject	EndObject method should be called to finalize object data de-serialization started by NG.Serialization.TDeserializer.BeginObject(string) method. For more information look NG.Serialization.TDeserializer.BeginObject(string) method description.
	HasNext	HasNext method determines, whether the next serialized value is available.
	MemberNotFound
	Prop(string)
	Prop	Prop method should be used to read property name when de-serializing object properties.
	SkipValue	SkipValue method allows to skip data value while de-serializing. Both, simple types, such as Integer or string, and complex types, such as records, objects or arrays can be skipped using SkipValue method.
	StateError
	TryNull	TryNull method performs a check whether the serialized value is `null` value, and, if yes, reads (skips) it.
	Value<T>	Value method allows to de-serialize typed data value. Both, simple types, such as Integer or string, and complex types, such as records, objects or arrays can be de-serialized using Value method.
	Value<T>(T)	Value method allows to de-serialize typed data value. Both, simple types, such as Integer or string, and complex types, such as records, objects or arrays can be de-serialized using Value method. This overload of Value methods implements fill-read mode.

Top

Events

	Name	Description
	OnMemberNotFound	OnMemberNotFound event allows to specify dynamically, whether to raise an exception or skip value silently when de-serialising data contains unknown class or record member.

Top

Remarks

Use specialized de-serializer objects to de-serialize data values from particular medium. Each descendant of TDeserializer base class implements reading from particular medium, such as XML node, JSON document or data-stream. The examples of specialized de-serializers are TBinaryDeserializer and TXmlDeserializer.

TDeserializer introduces common public methods for reading values of almost any Delphi data type, previously serialized by TSerializer descendants. TDeserializer reflects JSON data model closely; and thus, at low level it provides a way for reading single typed values, objects with named properties and arrays with (unnamed) elements.

Values of any type, such as simple types (like Integer or string), as well as complex types (like classes, records or arrays) can be de-serialized using single Value method call. For example, if an object need to be de-serialized, just call Value method passing an object as the argument. New object will be created, and values of its public fields and properties will be read:

Delphi	Copy Code
obj := D.Value<TMyObject>;

Just as TSerializer, TDeserializer class also provides low-level API for formatting object and array data manually. Object like data can be read using NG.Serialization.TDeserializer.BeginObject(string), NG.Serialization.TDeserializer.EndObject and NG.Serialization.TDeserializer.Prop methods, like this:

Delphi	Copy Code
D.BeginObject(objtp); if (objtp <> 'Book') and (objtp <> '') then raise Exception.Create('Unexpected object type'); book := TBook.Create; while D.HasNext do begin if D.Prop = 'Tittle' then book.Tittle := D.Value<string> else if D.Prop = 'Author' then book.Author := D.Value<string> else raise Exception.Create('Unexpected property name'); end; S.EndObject;

Delphi

Copy Code

D.BeginObject(objtp);

if (objtp <> 'Book') and (objtp <> '') then
  raise Exception.Create('Unexpected object type');
book := TBook.Create;

while D.HasNext do
begin
  if D.Prop = 'Tittle' then
    book.Tittle := D.Value<string>
  else if D.Prop = 'Author' then
    book.Author := D.Value<string>
  else
    raise Exception.Create('Unexpected property name');
end;

S.EndObject;

while array or collection data can be read like this:

Delphi	Copy Code
D.BeginArray; while D.HasNext do MyIntList.Add(D.Value<Integer>); D.EndArray;

As shown above, reading object properties requires to use NG.Serialization.TDeserializer.Prop method to read property name, while it should not be used when reading array element. So, the sequence, in which de-serializer methods are called, should be consistent, otherwise invalid state exception will be thrown.

Note:
Some serialization formats, such as XML or JSON, are human readable. Moreover, the content of serialized document can be changed by the user manually. So, its not a good practice to rely on object property or array element count, properties order, ect.