 |
BSON C++ API
2.5.1
uma::bson
|
|
BSON C++ API
2.5.1
uma::bson
|
Abstract base class that represents a BSON Object type. More...
#include <Object.h>
Inheritance diagram for uma::bson::Object: Collaboration diagram for uma::bson::Object:Public Types | |
| 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 | |
| virtual | ~Object () |
| Virtual destructor for sub-classes. | |
| virtual const FieldNames | getFieldNames () const =0 |
| Return a vector of all the element names (top-level only) in this object. | |
| virtual Value & | getValue (const std::string &name)=0 |
| Return the value for the element with the specified name. | |
| 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. | |
| virtual void | setValue (const std::string &name, const Value &value) |
| Set the value for the element with the specified name. | |
| virtual void | toBson (std::ostream &os) const |
| Serialise the data in this object in BSON format to the specified output stream. | |
| virtual void | populate (std::istream &is) |
| Populate the fields in this object from the BSON data stream. Complementary method to toBson. | |
| 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. | |
Additional Inherited Members | |
| Static Public Member Functions inherited from uma::bson::Value | |
| static const std::string & | getTypeName (const Type type) |
| Return a descriptive text about the specified type. | |
| Protected Member Functions inherited from uma::bson::Value | |
| Value () | |
Abstract base class that represents a BSON Object type.
The primary purpose of this indirection is to allow client API to model BSON object instances as regular POD types. By implementing the methods in this abstract interface these classes automatically get support for serialisation to and from BSON.
| typedef std::vector<std::string> uma::bson::Object::FieldNames |
A container for the top-level fields in an object.
| typedef FieldNames::const_iterator uma::bson::Object::FieldsIterator |
Iterator for iterating over the top-level field names in an object.
|
inlinevirtual |
Virtual destructor for sub-classes.
|
pure virtual |
Return a vector of all the element names (top-level only) in this object.
Implemented in uma::bson::Document, and uma::bson::ODMObject< Model >.
|
inlinevirtual |
Return an empty instance of an object implementation that represents the type of data stored in an array type field.
Array type fields are used to represent data stored in container classes in the class. This method is used primarily when de-serialising an object instance from its BSON representation. If the object being de-serialised contains array type data, this method will be used to determine the type of values stored in the array.
Note that container fields that store simple types (literally all types of values except Value::Type::Object) will in general not need any special support or this method to be implemented.
Note that the default implementation just throws an exception. This is done to avoid having to make this method a pure-virtual method. Not all model objects will need to store collections of values, and hence only objects that need to support collections need implement this method.
The calling method implemented in this API will populate the instance returned with the BSON data and save in an uma::bson::Element. The element instance takes ownership of the memory allocated for the instance returned. Implementations must not delete the instance returned.
| name | The name of the array type field. |
|
virtual |
Return the size of the data as per BSON specifications.
Implements uma::bson::Value.
|
inlinevirtual |
Returns the type for this instance as listed in the BSON specifications.
Implements uma::bson::Value.
|
pure virtual |
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.
| name | The name of the BSON element |
| Poco::NotFoundException | If no element with specified name exists. |
Implemented in uma::bson::Document, and uma::bson::ODMObject< Model >.
|
inlinevirtual |
Constant version of getValue method.
|
virtual |
Populate the fields in this object from the BSON data stream. Complementary method to toBson.
| is | The BSON data stream from which this object instance is to be populated. |
| Poco::InvalidArgumentException | If the bson data contains elements that do not match the fields in this class. |
|
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.
| name | |
| value |
| 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 in uma::bson::Document, and uma::bson::ODMObject< Model >.
|
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.
| os | The output stream to serialise the BSON data to. |
Reimplemented in uma::bson::Document.
1.8.3 
