A class that represents a BSON Object. More...

#include <Document.h>

Inheritance diagram for uma::bson::Document:

Collaboration diagram for uma::bson::Document:

Public Types
typedef std::vector< Element > ::const_iterator	ConstantIterator
	Constant iterator for iterating over the elements in document.

Public Types inherited from uma::bson::Object
typedef std::vector< std::string >	FieldNames
	A container for the top-level fields in an object.

typedef FieldNames::const_iterator	FieldsIterator
	Iterator for iterating over the top-level field names in an object.

Public Types inherited from uma::bson::Value
enum	Type { Eoo = 0, Double = 1, String = 2, Object = 3, Array = 4, BinData = 5, Undefined = 6, OID = 7, Boolean = 8, Date = 9, Null = 10, RegEx = 11, DbRef = 12, Code = 13, Symbol = 14, CodeWScope = 15, Integer = 16, Timestamp = 17, Long = 18 }

Public Member Functions
	Document (const ObjectId &oid=ObjectId())
	Default constructor for creating new documents.

bool	isEmpty () const
	Check to see if the document has any elements.

ConstantIterator	begin () const
	Return a constant iterator to the first element in the container that stores the elements in this document.

ConstantIterator	end () const
	Returns a constant iterator to the end of the container that stores the elements in this document.

const FieldNames	getFieldNames () const
	Return a vector of all the element names (top-level only) in this object.

bool	hasElement (const std::string &name) const
	Check to see if a element/field with specified name exists. Note that the check is non-recursive, and hence the name specified must be simple and not dot separated.

template<typename DataType >
Element &	create (const std::string &name)
	Create an empty element of specified type and return a reference to the newly created element.

const Element &	get (const std::string &name) const
	Return the element with the specified name as a constant reference.

Element &	get (const std::string &name)
	Return the element with the specified name as a reference.

Element &	operator[] (const std::string &name)
	Retrieve the element with specified name.

const Element &	operator[] (const std::string &name) const
	Alias for get( const std::string& ).

Value &	getValue (const std::string &name)
	Return the value for the element with the specified name.

bool	hasNestedElement (const std::string &name) const
	Check to see if a element/field with specified name exists in embedded objects/arrays in the document. The nested field name specified must use the dot notation supported by MongoDB.

const Element &	getNestedElement (const std::string &name) const
	Return the nested element from the BSON document.

Document &	set (const Element &value, const int32_t index=-1)
	Add the specified element to this document.

Document &	operator<< (const Element &value)
	Alias for set( uma::bson::Element&, int32_t ).

template<typename DataType >
Document &	set (const std::string &name, const DataType &value, const int32_t index=-1)
	Adds a new element with the specified name and value to this document.

void	setValue (const std::string &name, const Value &value)
	Set the value for the element with the specified name.

const ObjectId &	getObjectId ()
	Return the object identity field for this document.

Document &	setObjectId (const ObjectId &oid=ObjectId())
	Set the `_id` field that holds the object identity for the document.

Element	remove (const std::string &name)
	Remove the element with the specified name from this document.

size_t	size () const
	Return the total number of top-level elements in the document.

void	toBson (std::ostream &os) const
	Serialise the data in this object in BSON format to the specified output stream.

void	toJson (std::ostream &os, bool prettyPrint=false) const
	Generate a JSON representation of the data in the document.

Document	clone () const
	Clone the contents of this document.

bool	isEquivalentTo (const Document &doc) const
	Compare two documents for equivalence.

int32_t	getSize () const
	The size is bytes of the BSON representation of the document.

template<>
Document &	set (const std::string &name, const double &value, const int32_t index)
	Specialisation of the `set` method for double value.

template<>
Document &	set (const std::string &name, const std::string &value, const int32_t index)
	Specialisation of the `set` method for a string value.

template<>
Document &	set (const std::string &name, const bool &value, const int32_t index)
	Specialisation of the `set` method for a boolean value.

template<>
Document &	set (const std::string &name, const int32_t &value, const int32_t index)
	Specialisation of the `set` method for an integer value.

template<>
Document &	set (const std::string &name, const int64_t &value, const int32_t index)
	Specialisation of the `set` method for a long value.

Public Member Functions inherited from uma::bson::Object
virtual	~Object ()
	Virtual destructor for sub-classes.

virtual const Value &	getValue (const std::string &name) const
	Constant version of getValue method.

virtual Object *	getObjectForArray (const std::string &)
	Return an empty instance of an object implementation that represents the type of data stored in an array type field.

int32_t	getSize () const
	Return the size of the data as per BSON specifications.

Value::Type	getType () const
	Returns the type for this instance as listed in the BSON specifications.

Public Member Functions inherited from uma::bson::Value
virtual	~Value ()
	Virtual DTOR for sub-classes.

const std::string &	getTypeName () const
	Returns a standard textual value for this type.

Static Public Member Functions
static Document	emptyDocument ()
	Create an empty document without a default assigned OBJECT_ID field.

static Document	fromFile (const std::string &filePath)
	Create a new document instance with the contents of the BSON file at specified path.

static Document	fromBytes (const char *bytes, const int32_t length)
	Create a new document instance with the contents of the `char` array. Can be used to create document instances from MongoDB C/C++ driver functions.

static Document	fromStream (std::istream &is)
	Create a new document instance with the contents read from the specified stream. Usually used to read the BSON data over a network.

static Document	fromJson (std::istream &is)
	Create a new document instance with the JSON data from the specified stream.

Static Public Attributes
static const std::string	OBJECT_ID
	The special ObjectId element/field name as used by MongoDB.

Additional Inherited Members
Protected Member Functions inherited from uma::bson::Value
	Value ()

Detailed Description

A class that represents a BSON Object.

Documents may be top level objects, or sub-objects of a document. All the data in this class is contained in a shared pointer, hence this class may be passed by value without significant overhead. This also makes it easier to work with embedded documents that are retrieved as element values. To properly clone/copy an array use the clone method.

Copyright: Copyright © 2012, Sans Pareil Technologies, Inc.

Date: Created 2012/09/06 18:59

Author: Rakesh

Version

Id:: Document.h 203 2013-02-15 12:23:15Z spt

Member Typedef Documentation

typedef std::vector<Element>::const_iterator uma::bson::Document::ConstantIterator

Constant iterator for iterating over the elements in document.

Constructor & Destructor Documentation

uma::bson::Document::Document ( const ObjectId & oid = ObjectId() )

inline

Default constructor for creating new documents.

Use to create an new document that will be populated by subsequent invocations of the * set method. The constructor adds a new ObjectId field with the special element name OBJECT_ID.

Parameters

oid	The object id to use for the new document, or a default constructed object id.

Member Function Documentation

ConstantIterator uma::bson::Document::begin ( ) const

inline

Return a constant iterator to the first element in the container that stores the elements in this document.

Since: 2.0

Returns: The iterator to the first entry in container.

Document uma::bson::Document::clone ( ) const

Clone the contents of this document.

This is the recommended way to copy a document. The default copy constructor and assignment operator return document instances that share the internal data. This method returns a document instance with the equivalent but different instances of the internal data.

Warning: This method has not been optimised. The current implementation serialises the document to a BSON stream, and then de-serialises the BSON stream into a new document instance.

Since: 1.3

Returns: A document instance with all the internal data duplicated.

template<typename DataType >

Element& uma::bson::Document::create ( const std::string & name )

inline

Create an empty element of specified type and return a reference to the newly created element.

Use this method to create an element of a specific data type and then populate the value for the newly created element. This will avoid a copy-construction of the value instance when setting an element value.

Warning: Note that if an element exists with the specified name, a reference to the existing element is returned, regardless of the data type held in that element.

Template Parameters

DataType The type of value to be stored in the element.

Since: Version 2.4

Parameters

name	The name of the element to retrieve.

Returns: The element with the specified name

Exceptions

Poco::NotFoundException If no element with specified name exists.

static Document uma::bson::Document::emptyDocument ( )

inlinestatic

Create an empty document without a default assigned OBJECT_ID field.

Returns: The new empty document.

ConstantIterator uma::bson::Document::end ( ) const

inline

Returns a constant iterator to the end of the container that stores the elements in this document.

Since: 2.0

Returns: The iterator to the end of the container.

static Document uma::bson::Document::fromBytes	(	const char *	bytes,
		const int32_t	length
	)

static

Create a new document instance with the contents of the char array. Can be used to create document instances from MongoDB C/C++ driver functions.

Parameters

bytes	The char array containing the BSON data
length	The total length of the char array

Returns: The document object representing the BSON data.

static Document uma::bson::Document::fromFile ( const std::string & filePath )

static

Create a new document instance with the contents of the BSON file at specified path.

Parameters

filePath The fully qualified name of the file to read.

Returns: The document object representing the BSON data.

static Document uma::bson::Document::fromJson ( std::istream & is )

static

Create a new document instance with the JSON data from the specified stream.

Parameters

is	The input stream to read the JSON data from

Returns: The document object representing the BSON data.

static Document uma::bson::Document::fromStream ( std::istream & is )

static

Create a new document instance with the contents read from the specified stream. Usually used to read the BSON data over a network.

Parameters

is	The input stream to read the BSON data from

Returns: The document object representing the BSON data.

const Element& uma::bson::Document::get ( const std::string & name ) const

inline

Return the element with the specified name as a constant reference.

Parameters

name	The name of the element to retrieve.

Returns: The element with the specified name

Exceptions

Poco::NotFoundException If no element with specified name exists.

Element& uma::bson::Document::get ( const std::string & name )

inline

Return the element with the specified name as a reference.

Parameters

name	The name of the element to retrieve.

Returns: The element with the specified name

Exceptions

Poco::NotFoundException If no element with specified name exists.

const FieldNames uma::bson::Document::getFieldNames ( ) const

inlinevirtual

Return a vector of all the element names (top-level only) in this object.

Returns: The vector of element names.

Implements uma::bson::Object.

const Element& uma::bson::Document::getNestedElement ( const std::string & name ) const

inline

Return the nested element from the BSON document.

The element name should be specified using the dot notation supported by MongoDB. Note that array type sub-objects will be traversed by the index number element name.

Parameters

name	The fully qualified (eg. field1.field2.3.field3) name of the embedded element

Returns: The requested embedded element.

Exceptions

Poco::NotFoundException	If the specified nested element is not found.
Poco::Exception	Other Exceptions may be thrown if the name does not properly follow the document structure. For instance if a nested element is an array, and the subsequent element name specified is not of type numeric, and exception will be thrown.

const ObjectId& uma::bson::Document::getObjectId ( )

inline

Return the object identity field for this document.

Warning: A new object identity will be generated and assigned to this document if one does not yet exist.

Returns: The object id for this document.

int32_t uma::bson::Document::getSize ( ) const

inlinevirtual

The size is bytes of the BSON representation of the document.

Returns: The size of the bson data array

Implements uma::bson::Value.

Value& uma::bson::Document::getValue ( const std::string & name )

inlinevirtual

Return the value for the element with the specified name.

This method is primarily intended to provide rudimentary ODM (object-document mapping) capabilities in the API. Model objects that extend this class and store fields as Value types may be serialised to BSON seamlessly. See unit test suite for a simple custom model object that is serialised to BSON.

Since: Version 2.2

Parameters

name	The name of the BSON element

Returns: The value for the element.

Exceptions

Poco::NotFoundException If no element with specified name exists.

Implements uma::bson::Object.

bool uma::bson::Document::hasElement ( const std::string & name ) const

inline

Check to see if a element/field with specified name exists. Note that the check is non-recursive, and hence the name specified must be simple and not dot separated.

Parameters

name	The name of the element/field to check for existence

Returns: Returns true if an element exists.

bool uma::bson::Document::hasNestedElement ( const std::string & name ) const

inline

Check to see if a element/field with specified name exists in embedded objects/arrays in the document. The nested field name specified must use the dot notation supported by MongoDB.

Parameters

name	The name of the element/field to check for existence

Returns: Returns true if an element exists.

Exceptions

Poco::Exception Exceptions may be thrown if the name specified does not properly follow the document structure. For instance if a nested element is an array, and the subsequent element name specified is not of type numeric, and exception will be thrown.

bool uma::bson::Document::isEmpty ( ) const

inline

Check to see if the document has any elements.

Returns: Return true is there are no elements.

bool uma::bson::Document::isEquivalentTo ( const Document & doc ) const

Compare two documents for equivalence.

Documents are considered equivalent if they have the same elements even though the ordering of elements is different. The == operator performs the true equality check, which this method performs equivalence check.

Warning: This method performs a true deep comparison and may be quite heavy weight depending upon the data in the documents being compared.

Since: 2.1

Parameters

doc	The document to compare for equivalence.

Returns: Return true if the specified document is equivalent to this instance.

Document& uma::bson::Document::operator<< ( const Element & value )

inline

Alias for set( uma::bson::Element&, int32_t ).

Element& uma::bson::Document::operator[] ( const std::string & name )

Retrieve the element with specified name.

Similar to a std::map if no element with the specified name exists, a new element with the specified name is added to the document. The element will be assigned a value type undefined.

Since: Version 2.2

Parameters

name	The name of the element to retrieve.

Returns: The element with the specified name

const Element& uma::bson::Document::operator[] ( const std::string & name ) const

inline

Alias for get( const std::string& ).

Element uma::bson::Document::remove ( const std::string & name )

inline

Remove the element with the specified name from this document.

Warning: Note that only top-level elements may be removed using this method. Nested elements are not processed.

Parameters

name	The name of the element to remove.

Returns: A copy of the element that was removed.

Exceptions

Poco::NotFoundException If an element with specified name does not exist in this document.

Document& uma::bson::Document::set	(	const Element &	value,
		const int32_t	index = `-1`
	)

inline

Add the specified element to this document.

Replaces any existing element which has the same name as the specified element.

Warning: If the name of the element is _id, it will be inserted at index 0 regardless of the value of index specified.

Parameters

value	The new element to add to this document.
index	The optional index at which the new element is to be inserted. This may be used to provide clients control over the order of the elements in this document.

Returns: This instance for method chaining.

template<typename DataType >

Document& uma::bson::Document::set	(	const std::string &	name,
		const DataType &	value,
		const int32_t	index = `-1`
	)

inline

Adds a new element with the specified name and value to this document.

If an element already exists with the specified name, it is replaced. The optional index parameter may be used to control the ordering of the elements in this document.

Template Parameters

DataType The type of value to be stored in the element.

Parameters

name	The name of the element to be added.
value	The value for the new element.
index	The optional index at which to insert the element.

Returns: This instance for method chaining

template<>

Document& uma::bson::Document::set	(	const std::string &	name,
		const double &	value,
		const int32_t	index
	)

inline

Specialisation of the set method for double value.

Parameters

name	The name of the element
value	The double value for the element
index	The optional index to insert the element at.

Returns: This instance for method chaining.

template<>

Document& uma::bson::Document::set	(	const std::string &	name,
		const std::string &	value,
		const int32_t	index
	)

inline

Specialisation of the set method for a string value.

Parameters

name	The name of the element
value	The string value for the element
index	The optional index to insert the element at.

Returns: This instance for method chaining.

template<>

Document& uma::bson::Document::set	(	const std::string &	name,
		const bool &	value,
		const int32_t	index
	)

inline

Specialisation of the set method for a boolean value.

Parameters

name	The name of the element
value	The boolean value for the element
index	The optional index to insert the element at.

Returns: This instance for method chaining.

template<>

Document& uma::bson::Document::set	(	const std::string &	name,
		const int32_t &	value,
		const int32_t	index
	)

inline

Specialisation of the set method for an integer value.

Parameters

name	The name of the element
value	The integer value for the element
index	The optional index to insert the element at.

Returns: This instance for method chaining.

template<>

Document& uma::bson::Document::set	(	const std::string &	name,
		const int64_t &	value,
		const int32_t	index
	)

inline

Specialisation of the set method for a long value.

Parameters

name	The name of the element
value	The long value for the element
index	The optional index to insert the element at.

Returns: This instance for method chaining.

Document& uma::bson::Document::setObjectId ( const ObjectId & oid = ObjectId() )

inline

Set the _id field that holds the object identity for the document.

Parameters

oid	The object id for the document.

Returns: This instance for method chaining

void uma::bson::Document::setValue	(	const std::string &	name,
		const Value &	value
	)

virtual

Set the value for the element with the specified name.

This method is also used to provide rudimentary ODM capabilities in the API. Model objects that extend this class and store fields as Value types may be deserialised from BSON through this method. See unit test suite for a simple custom model object that is de-serialised from BSON.

Note that from Version 2.3 onwards a default implementation is provided. The default implementation handles setting the value for all the simple types. In particular Value::Type::Object, Value::Type::Array and consequently Value::Type::CodeWScope are not handled and may throw an exception. Despite this clients may still not need to provide an implementation of this method even if they store other object and array fields. The BSON deserialiser implemented in this API retrieves a reference to the current object/array from the destination instance and populates those. Hence if the only code using this method is from the internal BSON deserialiser, there will be no need to provide additional implementation for setting object/array fields.

Since: Version 2.2

Parameters

name
value

Exceptions

Poco::InvalidArgumentException	Will be thrown if the specified value type does not match the existing value type. May also be throw since this method invokes getValue( const std::string& ) at the beginning to fetch the current instance that is to be modified.
Poco::NotImplementedException	If the value specified is a complex type such as `Value::Type::Object` or `Value::Type::Array`.

Reimplemented from uma::bson::Object.

size_t uma::bson::Document::size ( ) const

inline

Return the total number of top-level elements in the document.

Returns: The number of top-level elements.

void uma::bson::Document::toBson ( std::ostream & os ) const

virtual

Serialise the data in this object in BSON format to the specified output stream.

The default implementation uses uma::bson::io::ObjectWriter to serialise the fields returned by getFieldNames to the stream.

Parameters

os	The output stream to serialise the BSON data to.

Reimplemented from uma::bson::Object.

void uma::bson::Document::toJson	(	std::ostream &	os,
		bool	prettyPrint = `false`
	)		const

Generate a JSON representation of the data in the document.

Note that the JSON generated is based closely upon the BSON specification and is not in a "natural" JSON format. The format was chosen to make it easy to re-parse the JSON back into a document.

Parameters

os	The output stream to serialise the JSON data to.
prettyPrint	Indicate whether the output should contain indentation and line breaks for readability.

Member Data Documentation

const std::string uma::bson::Document::OBJECT_ID

static

The special ObjectId element/field name as used by MongoDB.

The documentation for this class was generated from the following file:

/Users/rakesh/projects/opensource/mongoviewer/bson/src/api/uma/bson/Document.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation