BsonUser Guide
Overview
Bson is an implementation of the BSON specification complete with BSON serialisation and deserialisation.
Note that BSON is an extention of JSON, and JSON can only represent a subset of the types supported by BSON.
Bson was created to support the development of the Alien-Factory MongoDB driver.
Quick Start
1). Create a text file called Example.fan
:
using afBson class Example { Void main() { buf := Buf() documentIn := [ "_id" : ObjectId(), "name" : "Dave", "age" : 42 ]// serialise BSON to a streamBsonWriter(buf.out).writeDocument(documentIn)// deserialise BSOM from a streamdocumentOut := BsonReader(buf.flip.in).readDocument echo(documentOut) } }
2). Run Example.fan
as a Fantom script from the command line:
C:\> fan Example.fan [_id:53503531a8000b8b44000001, name:Dave, age:42]
Usage
The main BsonReader and BsonWriter classes (de)serialise BSON objects to and from Fantom using the following mapping:
- Fantom BSON - --------------------------------- afBson::Binary -> BINARY sys::Bool -> BOOLEAN afBson::Code -> CODE afBson::Code -> CODE_W_SCOPE sys::DateTime -> DATE sys::Float -> DOUBLE sys::Int -> INTEGER_64 sys::List -> ARRAY sys::Map -> DOCUMENT afBson::MaxKey -> MAX_KEY afBson::MinKey -> MIN_KEY null -> NULL afBson::ObjectId -> OBJECT_ID sys::Regex -> REGEX sys::Str -> STRING afBson::Timestamp -> TIMESTAMP
Note that the deprecated BSON constructs UNDEFINED
, DB_POINTER
and SYMBOL
are ignored and have no Fantom representation.
Bson
takes care of all the tricky Endian
ness. All BSON objects (except for Buf
) may be serialised to and from strings using Fantom's standard serialisation techniques.
CAUTION:
INTEGER_32
values will be read as Int values. If you then write its containing document, the storage type will be converted toINTEGER_64
.
This is only of concern if other, non Fantom, drivers have written INTEGER_32
values to the database.
CAUTION: Fantom does not support regex flags. When reading a BSON regex, flags are convered into embedded characted flags. e.g.
/myregex/im
is converted into/(?im)myregex/
. See Java's Pattern class for a list of supported flags (dimsuxU).
Again, this is only of concern if other, non Fantom, drivers have written REGEX
values (with flags) to the database.
The Alien-Factoy BSON library was inspired by fantomongo by Liam Staskawicz.