MongoDB  2.7.0
Public Types | Public Member Functions | Friends | List of all members
mongo::mutablebson::Document Class Reference

Mutable BSON Overview. More...

#include <document.h>

Public Types

enum  InPlaceMode { kInPlaceDisabled = 0, kInPlaceEnabled = 1 }
 

Public Member Functions

 Document ()
 Construct a new empty document. More...
 
 Document (const BSONObj &value, InPlaceMode inPlaceMode=kInPlaceEnabled)
 Construct new document for the given BSONObj. More...
 
void reset ()
 Abandon all internal state associated with this Document, and return to a state semantically equivalent to that yielded by a call to the default constructor. More...
 
void reset (const BSONObj &value, InPlaceMode inPlaceMode=kInPlaceEnabled)
 As the no argument 'reset', but returns to a state semantically equivalent to that yielded by a call to the two argument constructor with the arguments provided here. More...
 
 ~Document ()
 Destroy this document permanently.
 
int compareWith (const Document &other, bool considerFieldName=true) const
 Compare this Document to 'other' with the semantics of BSONObj::woCompare. More...
 
int compareWithBSONObj (const BSONObj &other, bool considerFieldName=true) const
 Compare this Document to 'other' with the semantics of BSONObj::woCompare. More...
 
void writeTo (BSONObjBuilder *builder) const
 Serialize the Elements reachable from the root Element of this Document to the provided builder.
 
BSONObj getObject () const
 Serialize the Elements reachable from the root Element of this Document and return the result as a BSONObj.
 
Element makeElementDouble (const StringData &fieldName, double value)
 Create a new double Element with the given value and field name. More...
 
Element makeElementString (const StringData &fieldName, const StringData &value)
 Create a new string Element with the given value and field name. More...
 
Element makeElementObject (const StringData &fieldName)
 Create a new empty object Element with the given field name. More...
 
Element makeElementObject (const StringData &fieldName, const BSONObj &value)
 Create a new object Element with the given field name. More...
 
Element makeElementArray (const StringData &fieldName)
 Create a new empty array Element with the given field name. More...
 
Element makeElementArray (const StringData &fieldName, const BSONObj &value)
 Create a new array Element with the given field name. More...
 
Element makeElementBinary (const StringData &fieldName, uint32_t len, BinDataType binType, const void *data)
 Create a new binary Element with the given data and field name. More...
 
Element makeElementUndefined (const StringData &fieldName)
 Create a new undefined Element with the given field name. More...
 
Element makeElementNewOID (const StringData &fieldName)
 Create a new OID + Element with the given field name. More...
 
Element makeElementOID (const StringData &fieldName, mongo::OID value)
 Create a new OID Element with the given value and field name. More...
 
Element makeElementBool (const StringData &fieldName, bool value)
 Create a new bool Element with the given value and field name. More...
 
Element makeElementDate (const StringData &fieldName, Date_t value)
 Create a new date Element with the given value and field name. More...
 
Element makeElementNull (const StringData &fieldName)
 Create a new null Element with the given field name. More...
 
Element makeElementRegex (const StringData &fieldName, const StringData &regex, const StringData &flags)
 Create a new regex Element with the given data and field name. More...
 
Element makeElementDBRef (const StringData &fieldName, const StringData &ns, mongo::OID oid)
 Create a new DBRef Element with the given data and field name. More...
 
Element makeElementCode (const StringData &fieldName, const StringData &value)
 Create a new code Element with the given value and field name. More...
 
Element makeElementSymbol (const StringData &fieldName, const StringData &value)
 Create a new symbol Element with the given value and field name. More...
 
Element makeElementCodeWithScope (const StringData &fieldName, const StringData &code, const BSONObj &scope)
 Create a new scoped code Element with the given data and field name. More...
 
Element makeElementInt (const StringData &fieldName, int32_t value)
 Create a new integer Element with the given value and field name. More...
 
Element makeElementTimestamp (const StringData &fieldName, OpTime value)
 Create a new timetamp Element with the given value and field name. More...
 
Element makeElementLong (const StringData &fieldName, int64_t value)
 Create a new long integer Element with the given value and field name. More...
 
Element makeElementMinKey (const StringData &fieldName)
 Create a new min key Element with the given field name. More...
 
Element makeElementMaxKey (const StringData &fieldName)
 Create a new max key Element with the given field name. More...
 
Element makeElement (const BSONElement &elt)
 Construct a new Element with the same name, type, and value as the provided BSONElement. More...
 
Element makeElementWithNewFieldName (const StringData &fieldName, const BSONElement &elt)
 Construct a new Element with the same type and value as the provided BSONElement, but with a new name. More...
 
Element makeElementSafeNum (const StringData &fieldName, SafeNum value)
 Create a new element of the appopriate type to hold the given value, with the given field name.
 
Element makeElement (ConstElement elt)
 Construct a new element with the same name, type, and value as the provided mutable Element. More...
 
Element makeElementWithNewFieldName (const StringData &fieldName, ConstElement elt)
 Construct a new Element with the same type and value as the provided mutable Element, but with a new field name. More...
 
Element root ()
 Returns the root element for this document. More...
 
ConstElement root () const
 Returns the root element for this document. More...
 
Element end ()
 Returns an element that will compare equal to a non-ok element. More...
 
ConstElement end () const
 Returns an element that will compare equal to a non-ok element. More...
 
std::string toString () const
 
void reserveDamageEvents (size_t expectedEvents)
 Ensure that at least 'expectedEvents' damage events can be recorded for in-place mutations without reallocation. More...
 
bool getInPlaceUpdates (DamageVector *damages, const char **source, size_t *size=NULL)
 Request a vector of damage events describing in-place updates to this Document. More...
 
void disableInPlaceUpdates ()
 Drop the queue of in-place update damage events, and do not queue new operations that would otherwise have been in-place. More...
 
InPlaceMode getCurrentInPlaceMode () const
 Returns the current in-place mode for the document. More...
 
bool isInPlaceModeEnabled () const
 A convenience routine, this returns true if the current in-place mode is kInPlaceEnabled, and false otherwise.
 

Friends

class Element
 

Detailed Description

Mutable BSON Overview.

Mutable BSON provides classes to facilitate the manipulation of existing BSON objects or the construction of new BSON objects from scratch in an incremental fashion. The operations (including additions, deletions, renamings, type changes and value modification) that are to be performed do not need to be known ahead of time, and do not need to occur in any particular order. This is in contrast to BSONObjBuilder and BSONArrayBuilder which offer only serialization and cannot revise already serialized data. If you need to build a BSONObj but you know upfront what you need to build then you should use BSONObjBuilder and BSONArrayBuilder directly as they will be faster and less resource intensive.

The classes in this library (Document, Element, and ConstElement) present a tree-like (or DOM like) interface. Elements are logically equivalent to BSONElements: they carry a type, a field name, and a value. Every Element belongs to a Document, which roots the tree, and Elements of proper type (mongo::Object or mongo::Array) may have child Elements of their own. Given an Element, you may navigate to the Element's parent, to its siblings to the left or right of the Element in the tree, and to the leftmost or rightmost children of the Element. Note that some Elements may not offer all of these relationships: An Element that represents a terminal BSON value (like an integer) will not have children (though it may well have siblings). Similarly, an Element that is an 'only child' will not have any left or right siblings. Given a Document, you may begin navigating by obtaining the root Element of the tree by calling Document::root. See the documentation for the Element class for the specific navigation methods that will be available from the root Element.

Elements within the Document may be modified in various ways: the value of the Element may be changed, the Element may be removed, it may be renamed, and if it is eligible for children (i.e. it represents a mongo::Array or mongo::Object) it may have child Elements added to it. Once you have completed building or modifying the Document, you may write it back out to a BSONObjBuilder by calling Document::writeTo. You may also serialize individual Elements within the Document to BSONObjBuilder or BSONArrayBuilder objects by calling Element::writeTo or Element::writeArrayTo.

In addition to the above capabilities, there are algorithms provided in 'algorithm.h' to help with tasks like searching for Elements that match a predicate or for sorting the children of an Object Element.

Example 1: Building up a document from scratch, reworking it, and then serializing it:

namespace mmb = mongo::mutablebson; Create a new document mmb::Document doc; doc contents: '{}'

Get the root of the document. mmb::Element root = doc.root();

Create a new mongo::NumberInt typed Element to represent life, the universe, and everything, then push that Element into the root object, making it a child of root. mmb::Element e0 = doc.makeElementInt("ltuae", 42); root.pushBack(e0); doc contents: '{ ltuae : 42 }'

Create a new empty mongo::Object-typed Element named 'magic', and push it back as a child of the root, making it a sibling of e0. mmb::Element e1 = doc.makeElementObject("magic"); root.pushBack(e1); doc contents: '{ ltuae : 42, magic : {} }'

Create a new mongo::NumberDouble typed Element to represent Pi, and insert it as child of the new object we just created. mmb::Element e3 = doc.makeElementDouble("pi", 3.14); e1.pushBack(e3); doc contents: '{ ltuae : 42, magic : { pi : 3.14 } }'

Create a new mongo::NumberDouble to represent Plancks constant in electrovolt micrometers, and add it as a child of the 'magic' object. mmb::Element e4 = doc.makeElementDouble("hbar", 1.239); e1.pushBack(e4); doc contents: '{ ltuae : 42, magic : { pi : 3.14, hbar : 1.239 } }'

Rename the parent element of 'hbar' to be 'constants'. e4.parent().rename("constants"); doc contents: '{ ltuae : 42, constants : { pi : 3.14, hbar : 1.239 } }'

Rename 'ltuae' to 'answer' by accessing it as the root objects left child. doc.root().leftChild().rename("answer"); doc contents: '{ answer : 42, constants : { pi : 3.14, hbar : 1.239 } }'

Sort the constants by name. mmb::sortChildren(doc.root().rightChild(), mmb::FieldNameLessThan()); doc contents: '{ answer : 42, constants : { hbar : 1.239, pi : 3.14 } }'

     mongo::BSONObjBuilder builder;
     doc.writeTo(&builder);
     mongo::BSONObj result = builder.obj();

result contents: '{ answer : 42, constants : { hbar : 1.239, pi : 3.14 } }'

    While you can use this library to build Documents from scratch, its real purpose is to
    manipulate existing BSONObjs. A BSONObj may be passed to the Document constructor or to
    Document::make[Object|Array]Element, in which case the Document or Element will reflect
    the values contained within the provided BSONObj. Modifications will not alter the
    underlying BSONObj: they are held off to the side within the Document. However, when
    the Document is subsequently written back out to a BSONObjBuilder, the modifications
    applied to the Document will be reflected in the serialized version.

    Example 2: Modifying an existing BSONObj (some error handling removed for length)

     namespace mmb = mongo::mutablebson;

     static const char inJson[] =
         "{"
         "  'whale': { 'alive': true, 'dv': -9.8, 'height': 50, attrs : [ 'big' ] },"
         "  'petunias': { 'alive': true, 'dv': -9.8, 'height': 50 } "
         "}";
     mongo::BSONObj obj = mongo::fromjson(inJson);

Create a new document representing the BSONObj with the above contents. mmb::Document doc(obj);

The whale hits the planet and dies. mmb::Element whale = mmb::findFirstChildNamed(doc.root(), "whale"); Find the 'dv' field in the whale. mmb::Element whale_deltav = mmb::findFirstChildNamed(whale, "dv"); Set the dv field to zero. whale_deltav.setValueDouble(0.0); Find the 'height' field in the whale. mmb::Element whale_height = mmb::findFirstChildNamed(whale, "height"); Set the height field to zero. whale_deltav.setValueDouble(0); Find the 'alive' field, and set it to false. mmb::Element whale_alive = mmb::findFirstChildNamed(whale, "alive"); whale_alive.setValueBool(false);

The petunias survive, update its fields much like we did above. mmb::Element petunias = mmb::findFirstChildNamed(doc.root(), "petunias"); mmb::Element petunias_deltav = mmb::findFirstChildNamed(petunias, "dv"); petunias_deltav.setValueDouble(0.0); mmb::Element petunias_height = mmb::findFirstChildNamed(petunias, "height"); petunias_deltav.setValueDouble(0);

Replace the whale by its wreckage, saving only its attributes: Construct a new mongo::Object element for the ex-whale. mmb::Element ex_whale = doc.makeElementObject("ex-whale"); doc.root().pushBack(ex_whale); Find the attributes of the old 'whale' element. mmb::Element whale_attrs = mmb::findFirstChildNamed(whale, "attrs"); Remove the attributes from the whale (they remain valid, but detached). whale_attrs.remove(); Add the attributes into the ex-whale. ex_whale.pushBack(whale_attrs); Remove the whale object. whale.remove();

Current state of document: "{" " 'petunias': { 'alive': true, 'dv': 0.0, 'height': 50 }," " 'ex-whale': { 'attrs': [ 'big' ] } })" "}";

Both of the above examples are derived from tests in mutable_bson_test.cpp, see the tests Example1 and Example2 if you would like to play with the code.

Additional details on Element and Document are available in their class and member comments.Document is the entry point into the mutable BSON system. It has a fairly simple API. It acts as an owner for the Element resources of the document, provides a pre-constructed designated root Object Element, and acts as a factory for new Elements, which may then be attached to the root or to other Elements by calling the appropriate topology mutation methods in Element.

The default constructor builds an empty Document which you may then extend by creating new Elements and manipulating the tree topology. It is also possible to build a Document that derives its initial values from a BSONObj. The given BSONObj will not be modified, but it also must not be modified elsewhere while Document is using it. Unlike all other calls in this library where a BSONObj is passed in, the one argument Document constructor does not copy the BSONObj's contents, so they must remain valid for the duration of Documents lifetime. Document does hold a copy of the BSONObj itself, so it will up the refcount if the BSONObj internals are counted.

Newly constructed Elements formed by calls to 'makeElement[Type]' methods are not attached to the root of the document. You must explicitly attach them somewhere. If you lose the Element value that is returned to you from a 'makeElement' call before you attach it to the tree then the value will be unreachable. Elements in a document do not outlive the Document.

Document provides a convenience method to serialize all of the Elements in the tree that are reachable from the root element to a BSONObjBuilder. In general you should use this in preference to root().writeTo() if you mean to write the entire Document. Similarly, Document provides wrappers for comparisons that simply delegate to comparison operations on the root Element.

A 'const Document' is very limited: you may only write its contents out or obtain a ConstElement for the root. ConstElement is much like Element, but does not permit mutations. See the class comment for ConstElement for more information.

Constructor & Destructor Documentation

mongo::mutablebson::Document::Document ( )

Construct a new empty document.

mongo::mutablebson::Document::Document ( const BSONObj value,
InPlaceMode  inPlaceMode = kInPlaceEnabled 
)
explicit

Construct new document for the given BSONObj.

The data in 'value' is NOT copied. By default, queueing of in-place modifications against the underlying document is permitted. To disable this behavior, explicitly pass kInPlaceDisabled.

Member Function Documentation

int mongo::mutablebson::Document::compareWith ( const Document other,
bool  considerFieldName = true 
) const
inline

Compare this Document to 'other' with the semantics of BSONObj::woCompare.

int mongo::mutablebson::Document::compareWithBSONObj ( const BSONObj other,
bool  considerFieldName = true 
) const
inline

Compare this Document to 'other' with the semantics of BSONObj::woCompare.

void mongo::mutablebson::Document::disableInPlaceUpdates ( )

Drop the queue of in-place update damage events, and do not queue new operations that would otherwise have been in-place.

Use this if you know that in-place updates will not continue to be possible and do not want to pay the overhead of speculatively queueing them. After calling this method, getInPlaceUpdates will return a non-OK Status. It is not possible to re-enable in-place updates once disabled.

Element mongo::mutablebson::Document::end ( )
inline

Returns an element that will compare equal to a non-ok element.

ConstElement mongo::mutablebson::Document::end ( ) const
inline

Returns an element that will compare equal to a non-ok element.

Document::InPlaceMode mongo::mutablebson::Document::getCurrentInPlaceMode ( ) const

Returns the current in-place mode for the document.

Note that for some documents, like those created without any backing BSONObj, this will always return kForbidden, since in-place updates make no sense for such an object. In other cases, an object which started in kInPlacePermitted mode may transition to kInPlaceForbidden if a topology mutating operation is applied.

bool mongo::mutablebson::Document::getInPlaceUpdates ( DamageVector *  damages,
const char **  source,
size_t *  size = NULL 
)

Request a vector of damage events describing in-place updates to this Document.

If the modifications to this Document were not all able to be achieved in-place, then a non-OK Status is returned, and the provided damage vector will be made empty and *source set equal to NULL. Otherwise, the provided damage vector is populated, and the 'source' argument is set to point to a region from which bytes can be read. The 'source' offsets in the damage vector are to be interpreted as offsets within this region. If the 'size' parameter is non-null and 'source' is set to a non-NULL value, then size will be filled in with the size of the 'source' region to facilitate making an owned copy of the source data, in the event that that is needed.

The lifetime of the source region should be considered to extend only from the return from this call to before the next API call on this Document or any of its member Elements. That is almost certainly overly conservative: some read only calls are undoubtedly fine. But it is very easy to invalidate 'source' by calling any mutating operation, so proceed with due caution.

It is expected, though, that in normal modes of operation obtainin the damage vector is one of the last operations performed on a Document before its destruction, so this is not so great a restriction.

The destination offsets in the damage events are implicitly offsets into the BSONObj used to construct this Document.

Element mongo::mutablebson::Document::makeElement ( const BSONElement elt)

Construct a new Element with the same name, type, and value as the provided BSONElement.

The value is copied.

Element mongo::mutablebson::Document::makeElement ( ConstElement  elt)

Construct a new element with the same name, type, and value as the provided mutable Element.

The data is copied from the given Element. Unlike most methods in this class the provided Element may be from a different Document.

Element mongo::mutablebson::Document::makeElementArray ( const StringData &  fieldName)

Create a new empty array Element with the given field name.

Element mongo::mutablebson::Document::makeElementArray ( const StringData &  fieldName,
const BSONObj value 
)

Create a new array Element with the given field name.

The data in 'value' is copied.

Element mongo::mutablebson::Document::makeElementBinary ( const StringData &  fieldName,
uint32_t  len,
const mongo::BinDataType  binType,
const void *  data 
)

Create a new binary Element with the given data and field name.

Element mongo::mutablebson::Document::makeElementBool ( const StringData &  fieldName,
bool  value 
)

Create a new bool Element with the given value and field name.

Element mongo::mutablebson::Document::makeElementCode ( const StringData &  fieldName,
const StringData &  value 
)

Create a new code Element with the given value and field name.

Element mongo::mutablebson::Document::makeElementCodeWithScope ( const StringData &  fieldName,
const StringData &  code,
const BSONObj scope 
)

Create a new scoped code Element with the given data and field name.

Element mongo::mutablebson::Document::makeElementDate ( const StringData &  fieldName,
Date_t  value 
)

Create a new date Element with the given value and field name.

Element mongo::mutablebson::Document::makeElementDBRef ( const StringData &  fieldName,
const StringData &  ns,
mongo::OID  oid 
)

Create a new DBRef Element with the given data and field name.

Element mongo::mutablebson::Document::makeElementDouble ( const StringData &  fieldName,
double  value 
)

Create a new double Element with the given value and field name.

Element mongo::mutablebson::Document::makeElementInt ( const StringData &  fieldName,
int32_t  value 
)

Create a new integer Element with the given value and field name.

Element mongo::mutablebson::Document::makeElementLong ( const StringData &  fieldName,
int64_t  value 
)

Create a new long integer Element with the given value and field name.

Element mongo::mutablebson::Document::makeElementMaxKey ( const StringData &  fieldName)

Create a new max key Element with the given field name.

Element mongo::mutablebson::Document::makeElementMinKey ( const StringData &  fieldName)

Create a new min key Element with the given field name.

Element mongo::mutablebson::Document::makeElementNewOID ( const StringData &  fieldName)

Create a new OID + Element with the given field name.

Element mongo::mutablebson::Document::makeElementNull ( const StringData &  fieldName)

Create a new null Element with the given field name.

Element mongo::mutablebson::Document::makeElementObject ( const StringData &  fieldName)

Create a new empty object Element with the given field name.

Element mongo::mutablebson::Document::makeElementObject ( const StringData &  fieldName,
const BSONObj value 
)

Create a new object Element with the given field name.

The data in 'value' is copied.

Element mongo::mutablebson::Document::makeElementOID ( const StringData &  fieldName,
mongo::OID  value 
)

Create a new OID Element with the given value and field name.

Element mongo::mutablebson::Document::makeElementRegex ( const StringData &  fieldName,
const StringData &  regex,
const StringData &  flags 
)

Create a new regex Element with the given data and field name.

Element mongo::mutablebson::Document::makeElementString ( const StringData &  fieldName,
const StringData &  value 
)

Create a new string Element with the given value and field name.

Element mongo::mutablebson::Document::makeElementSymbol ( const StringData &  fieldName,
const StringData &  value 
)

Create a new symbol Element with the given value and field name.

Element mongo::mutablebson::Document::makeElementTimestamp ( const StringData &  fieldName,
OpTime  value 
)

Create a new timetamp Element with the given value and field name.

Element mongo::mutablebson::Document::makeElementUndefined ( const StringData &  fieldName)

Create a new undefined Element with the given field name.

Element mongo::mutablebson::Document::makeElementWithNewFieldName ( const StringData &  fieldName,
const BSONElement elt 
)

Construct a new Element with the same type and value as the provided BSONElement, but with a new name.

The value is copied.

Element mongo::mutablebson::Document::makeElementWithNewFieldName ( const StringData &  fieldName,
ConstElement  elt 
)

Construct a new Element with the same type and value as the provided mutable Element, but with a new field name.

The data is copied from the given Element. Unlike most methods in this class the provided Element may be from a different Document.

void mongo::mutablebson::Document::reserveDamageEvents ( size_t  expectedEvents)

Ensure that at least 'expectedEvents' damage events can be recorded for in-place mutations without reallocation.

This call is ignored if damage events are disabled.

void mongo::mutablebson::Document::reset ( )

Abandon all internal state associated with this Document, and return to a state semantically equivalent to that yielded by a call to the default constructor.

All objects associated with the current document state are invalidated (e.g. Elements, BSONElements, BSONObj's values, field names, etc.). This method is useful because it may (though it is not required to) preserve the memory allocation of the internal data structures of Document. If you need to logically create and destroy many Documents in serial, it may be faster to reset.

void mongo::mutablebson::Document::reset ( const BSONObj value,
InPlaceMode  inPlaceMode = kInPlaceEnabled 
)

As the no argument 'reset', but returns to a state semantically equivalent to that yielded by a call to the two argument constructor with the arguments provided here.

As with the other 'reset' call, all associated objects are invalidated.

Element mongo::mutablebson::Document::root ( )
inline

Returns the root element for this document.

ConstElement mongo::mutablebson::Document::root ( ) const
inline

Returns the root element for this document.


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