BSON
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. RAD Studio 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
RAD Studio 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;.