BSON

From Appmethod Topics
Jump to: navigation, search

Go Up to Using the RTL in Multi-Device Applications


BSON (Binary JSON) is an open standard to encode or represent JSON-like documents in a binary format. Appmethod provides a unit, System.JSON.BSON that contains classes and methods to serialize / unserialize BSON.

All BSON types are supported. See System.JSON.BSON.TBsonType and the official site for more information about the different types: BSON Official Site.

BSON Framework

Appmethod includes a new API to work with BSON data, from Seattle version and later.

The new framework includes classes to read and write BSON data, TBsonReader and TBsonWriter respectively.

Use the TBsonWriter to serialize JSON text to BSON. Use the WriteToken method to go through the JSON object, serializing token by token.

Use TBsonReader to read BSON data and unserialize BSON to JSON or other formats.

Writing BSON

The following JSON Object is used in the code snippet provided:

{				
  "colors": [		
    {			
      "name": "red",	
      "hex": "#f00"	
    }			
  ]								
}

To create a BSON document directly:

uses 

System.JSON.BSON,
System.JSON.Writers,
System.JSON.Builders;

procedure BSONWriterSample;
var
  Builder: TJSONObjectBuilder; //To use the built-in JSON builder 
  BytesStream: TBytesStream;  //To create the BSON document as a byte stream
  Writer: TBsonWriter; //A BSON writer
  Bytes: TBytes; //To contain the bytes from the byte stream
begin
  BytesStream := TBytesStream.Create;
  Writer := TBsonWriter.Create(BytesStream);
  Builder := TJSONObjectBuilder.Create(Writer);
  try
    Builder
     .BeginObject
      .BeginArray('colors')
       .BeginObject
        .Add('name','red')
        .Add('hex','#f00')
     .EndAll;

    Bytes := BytesStream.Bytes;
    SetLength(Bytes, BytesStream.Size); //Bytes contains the BSON document.
    Memo1.text := Bytes2String(Bytes); //To see the representation of the BSON document in a TMemo, passing the Bytes var that contains the BSON document.
  finally
    BytesStream.free;
    Writer.free;
    Builder.free;  
  end;
end;

The following BSON document is the result of writing the JSON object provided using a BSON writer, represented in hexadecimal notation:

36-00-00-00-04-63-6F-6C-6F-72-73-00-29-00-00-00-03-30-00-21-00-00-00-02-6E-61-6D-65-00-04-00-00-00-72-65-64-00-02-68-65-78-00-05-00-00-00-23-66-30-30-00-00-00-00

To see an hexadecimal representation of the BSON document, you can use the following function:

function Bytes2String(const ABytes: TBytes): string;
var
  I: Integer;
begin
  Result := '';
  for I := Low(ABytes) to High(ABytes) do
  if I = 0 then
    Result := IntToHex(ABytes[I], 2)
  else
    Result := Result + '-' + IntToHex(ABytes[I], 2);
end;

From JSON to BSON

The following JSON Object is used in the code snippet provided:

{				
  "colors": [		
    {			
      "name": "red",	
      "hex": "#f00"	
    }			
  ]								
}

To serialize a JSON Object to BSON.

The JSON object is copied into a TMemo.

uses 

System.JSON.BSON,
System.JSON.Writers,
System.JSON.Readers,
System.JSON.Builders;

procedure JSONtoBSON;
var
  SR: TStringReader; //A String Reader
  JsonReader: TJsonTextReader; //A JSON text Reader
  BsonWriter: TBsonWriter; // A BSON writer
  Stream: TBytesStream; //To create the BSON document as a byte stream
  Bytes: TBytes; //To contain the bytes from the byte stream
begin
  SR :=  TStringReader.Create(Memo1.Text); //It gets the JSON object as a string from a TMemo.
  JsonReader := TJsonTextReader.Create(SR);
  Stream := TBytesStream.Create;
  BsonWriter := TBsonWriter.Create(Stream);
  try
    BsonWriter.WriteToken(JsonReader); //It gets the JSON object as an argument and analize the object token by token.
    Stream.Position := 0;
    Bytes := Stream.Bytes;
    SetLength(Bytes, Stream.Size);
    Memo2.Text := Bytes2String(Bytes); //It shows the String representation of the BSON document in a TMemo.
  finally
    SR.free;
    JsonReader.free;
    Stream.free;
    BsonWriter.free;	  
  end;
end;

The following BSON document is the result of serializing the JSON Object provided, in hexadecimal notation:

36-00-00-00-04-63-6F-6C-6F-72-73-00-29-00-00-00-03-30-00-21-00-00-00-02-6E-61-6D-65-00-04-00-00-00-72-65-64-00-02-68-65-78-00-05-00-00-00-23-66-30-30-00-00-00-00
Note: See bellow the function definition: function Bytes2String(const ABytes: TBytes): string;.