Synopse Open Source

For instance, we would like to serialize a dynamic array of the following record:

  TFV = packed record
    Major, Minor, Release, Build: integer;
    Main, Detailed: string;
  end;
  TFVs = array of TFV;

With the default serialization, such a dynamic array will be serialized as a Base64 encoded binary buffer. This won't be easy to understand from an AJAX client, for instance.

In order to add a custom serialization for this kind of record, we need to implement the two needed callbacks. Our expected format will be a JSON array of all fields, i.e.:

 [1,2001,3001,4001,"1","1001"]

We may have used another layout, e.g. using JSONEncode() function and a JSON object layout, or any other valid JSON content.

Here comes the writer:

class procedure TCollTstDynArray.FVWriter(const aWriter: TTextWriter; const aValue);
var V: TFV absolute aValue;
begin
  aWriter.Add('[%,%,%,%,"%","%"]',
    [V.Major,V.Minor,V.Release,V.Build,V.Main,V.Detailed],twJSONEscape);
end;

This event will write one entry of the dynamic array, without the last ',' (which will be appended by TTextWriter.AddDynArrayJSON).
In this method, twJSONEscape is used to escape the supplied string content as a valid JSON string (with double quotes and proper UTF-8 encoding).

Of course, the Writer is easier to code than the Reader itself:

class function TCollTstDynArray.FVReader(P: PUTF8Char; var aValue;
  out aValid: Boolean): PUTF8Char;
var V: TFV absolute aValue;
begin // '[1,2001,3001,4001,"1","1001"],[2,2002,3002,4002,"2","1002"],...'
  aValid := false;
  result := nil;
  if (P=nil) or (P^<>'[') then
    exit;
  inc(P);
  V.Major := GetNextItemCardinal(P);
  V.Minor := GetNextItemCardinal(P);
  V.Release := GetNextItemCardinal(P);
  V.Build := GetNextItemCardinal(P);
  V.Main := UTF8ToString(GetJSONField(P,P));
  V.Detailed := UTF8ToString(GetJSONField(P,P));
  if P=nil then
    exit;
  aValid := true;
  result := P; // ',' or ']' for last item of array
end;

The reader method shall return a pointer to the next separator of the JSON input buffer just after this item (either ',' or ']').

The registration process itself is as simple as:

  TTextWriter.RegisterCustomJSONSerializer(TypeInfo(TFVs),
    TCollTstDynArray.FVReader,TCollTstDynArray.FVWriter);

Then, from the user code point of view, this dynamic array handling won't change: once registered, the JSON serializers are used everywhere in the framework, as soon as this type is registered globally.

Here is a Writer method using a JSON object layout:

class procedure TCollTstDynArray.FVWriter2(const aWriter: TTextWriter; const aValue);
var V: TFV absolute aValue;
begin
  aWriter.AddJSONEscape(['Major',V.Major,'Minor',V.Minor,'Release',V.Release,
    'Build',V.Build,'Main',V.Main,'Detailed',V.Detailed]);
end;

This will create some JSON content as such:

 {"Major":1,"Minor":2001,"Release":3001,"Build":4001,"Main":"1","Detailed":"1001"}

Then the corresponding Reader callback could be written as:

class function TCollTstDynArray.FVReader2(P: PUTF8Char; var aValue;
  out aValid: Boolean): PUTF8Char;
var V: TFV absolute aValue;
    Values: TPUtf8CharDynArray;
begin
  aValid := false;
  P := JSONDecode(P,['Major','Minor','Release','Build','Main','Detailed'],Values);
  if P=nil then
    exit;
  V.Major := GetInteger(Values[0]);
  V.Minor := GetInteger(Values[1]);
  V.Release := GetInteger(Values[2]);
  V.Build := GetInteger(Values[3]);
  V.Main := UTF8DecodeToString(Values[4],StrLen(Values[4]));
  V.Detailed := UTF8DecodeToString(Values[5],StrLen(Values[5]));
  aValid := true;
  result := P; // ',' or ']' for last item of array
end;

Most of the JSON decoding process is performed within the JSONDecode() function, which will let Values[] point to null-terminated un-escaped content within the P^ buffer. In fact, such process will do only one memory allocation (for Values[]), and will therefore be very fast.

You can define now your custom JSON serializers, starting for the above code as reference.

This JSON serialization will indeed be used in our main ORM to support dynamic arrays as enhanced properties (stored as BLOB), and in the interface-based SOA architecture of the framework, for content transmission.

Feedback and comments are welcome in our forum, just as usual.