pod afBson

A BSON specification implementation

Classes

Binary

(BSON Type) - Wraps binary data and its subType.

BsonReader

Wraps an InStream to read BSON objects.

BsonWriter

Wraps an OutStream to write BSON objects.

Code

(BSON Type) - Wraps a JavaScript function and default variable values.

MaxKey

(BSON Type) - MaxKey is greater than any other value of any type.

MinKey

(BSON Type) - MinKey is less than any other value of any type.

ObjectId

(BSON Type) - A globally unique identifier for MongoDB objects.

Timestamp

(BSON Type) - Timestamps are used internally by MongoDB's replication.

Enums

BsonType

A list of BSON types.

Overview

Bson is an implementation of the BSON specification complete with BSON serialisation and deserialisation.

Bson was created to support the development of the Alien-Factory MongoDB driver.

Install

Install Bson with the Fantom Repository Manager ( fanr ):

C:\> fanr install -r http://repo.status302.com/fanr/ afBson

To use in a Fantom project, add a dependency to build.fan:

depends = ["sys 1.0", ..., "afBson 1.0+"]

Documentation

Full API & fandocs are available on the Status302 repository.

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 stream
    BsonWriter(buf.out).writeDocument(documentIn)

    // deserialise BSOM from a stream
    documentOut := 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:

BSON                Fantom
---------------------------------
ARRAY        ->    sys::List
BINARY       -> afBson::Binary
BOOLEAN      ->    sys::Bool
CODE         -> afBson::Code
CODE_W_SCOPE -> afBson::Code
DATE         ->    sys::DateTime
DOCUMENT     ->    sys::Map
DOUBLE       ->    sys::Float
INTEGER_64   ->    sys::Int
MAX_KEY      -> afBson::MaxKey
MIN_KEY      -> afBson::MinKey
NULL         ->         null
OBJECT_ID    -> afBson::ObjectId
REGEX        ->    sys::Regex
STRING       ->    sys::Str
TIMESTAMP    -> afBson::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 Endianness. All BSON objects (except for Buf and Regex) may also 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 to INTEGER_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.

Release Notes

v1.0.0

  • New: Initial release.
  • New: BsonWriter caches nested document sizes for increased performance.
  • Bug: Worked around the dodgy DateTime.fromJava() quirks.

v0.0.2

  • New: Preview release.