DB API

Core Types

class object_recognition_core::db::ObjectDb

The main class that interact with the db A collection is similar to the term used in CouchDB. It could be a schema/table in SQL Each inheriting class must have an extra static class with the following signature: static object_recognition_core::db::ObjectDbParameters default_parameters() The databases that this interface handles are very generic: they store documents that are only defined by a JSON string and several binary blobs. That’s it. All relationships between documents therefore have to happen in the JSON. This paradigm is common to non-relational databases (CouchDB, MongoDB) An object is defined by a unique id and a revision number (not all databases support this version number)

Public Functions

ObjectDb()

Default constructor Make your children classes have the default parameter: ObjectDbParameters(default_parameters())

~ObjectDb()

const ObjectDbParameters & parameters()

Get the parameters of the database

Return
an ObjectDbParameters object as stored internally

ObjectDbParametersRaw default_raw_parameters()

Return
the raw parameters as a JSON object

void set_parameters(ObjectDbParameters & parameters)

Set the parameters of a database: this can only be done from the ObjectDBParameters This is also where internals can be set. The parameter is not const as it can be modified to show what was actually used.

Parameters
  • parameters -

    the parameters to impose to the database

void insert_object(const or_json::mObject & fields, DocumentId & document_id, RevisionId & revision_id)

Insert a document in the database

Parameters
  • fields -

    the JSON description of the document to insert

  • document_id -

    the returned id of the document that was inserted

  • revision_id -

    the revision number of the inserted object (some DB provide it)

void persist_fields(const DocumentId & document_id, const or_json::mObject & fields, RevisionId & revision_id)

When a document already belongs to a database, its fields can be updated through this function

Parameters
  • document_id -

    the id (unique identifier) of the document to update

  • fields -

    the new JSON description of the object to upload

  • revision_id -

    the resulting new revision of the object

void load_fields(const DocumentId & document_id, or_json::mObject & fields)

Load the JSON fields of an object from the database

Parameters
  • document_id -

    the id (unique identifier) of the document to update

  • fields -

    the returned fields as a JSON object

void Delete(const ObjectId & id)

Delete a document of a given id in the database

Parameters
  • id -

    the id of the document to delete

void QueryView(const View & view, int limit_rows, int start_offset, int & total_rows, int & offset, std::vector< Document > & view_elements)

Execute a given View on the database to find some documents

Parameters
  • view -

    a view object defining a query

  • limit_rows -

    a maximum number of queries to return (0 for infinite)

  • start_offset -

    the offset at which to return the found documents

  • total_rows -

    the total number of elements found

  • offset -

    the offset at which the results start_offset

  • view_elements -

    a vector of the found elements

void QueryGeneric(const std::vector< std::string > & queries, int limit_rows, int start_offset, int & total_rows, int & offset, std::vector< Document > & view_elements)

A generic function to make any query on the database

Parameters
  • queries -

    a set of queries to perform. The strings can mean anything to the database and are therefore specific to a type of database

  • limit_rows -

    a maximum number of queries to return (0 for infinite)

  • start_offset -

    the offset at which to return the found documents

  • total_rows -

    the total number of elements found

  • offset -

    the offset at which the results start_offset

  • view_elements -

    a vector of the found elements

void set_attachment_stream(const DocumentId & document_id, const AttachmentName & attachment_name, const MimeType & mime_type, const std::istream & stream, RevisionId & revision_id)

Given a Document, set a binary blobs

Parameters
  • document_id -

    the id (unique identifier) of the document to update

  • attachment_name -

    the name/key of the binary blob to add

  • mime_type -

    the MIME type of the binary blob to add

  • stream -

    the binary blob itself

  • revision_id -

    the new revision id of the object after insertion/update

void get_attachment_stream(const DocumentId & document_id, const RevisionId & revision_id, const AttachmentName & attachment_name, const MimeType & mime_type, std::ostream & stream)

Given a Document, get one of its binary blobs

Parameters
  • document_id -

    the id (unique identifier) of the document to update

  • revision_id -

    the revision id of the object

  • attachment_name -

    the name/key of the binary blob to add

  • mime_type -

    the MIME type of the binary blob to add

  • stream -

    the binary blob itself

std::string Status()

Return
a string that defines the status of the database

std::string Status(const CollectionName & collection)

Return
a string that defines the status of the database for a given collection

void CreateCollection(const CollectionName & collection)

Create a new collection in the database

Parameters
  • collection -

    the name of the collection to create

void DeleteCollection(const CollectionName & collection)

Delete a new collection in the database

Parameters
  • collection -

    the name of the collection to delete

DbType type()

The type of the DB : e.g. ‘CouchDB’ ...

Return
one of the enum defining the possible types

class object_recognition_core::db::ObjectDbParameters

A class that stores the common parameters for the object DB If it is not from a type provided by object_recognition_core, it is of type NONCORE

Public Type

ObjectDbType enum

Values:

  • EMPTY -
  • COUCHDB -
  • FILESYSTEM -
  • NONCORE -
Public Functions

ObjectDbParameters()

ObjectDbParameters(const std::string & type)

Default constructor for certain types

Parameters
  • type -

    Default type

ObjectDbParameters(ObjectDbType type)

Default constructor for certain types

Parameters
  • type -

    Default type

ObjectDbParameters(const ObjectDbParametersRaw & params)

Parameters
  • params -

    A map between some db parameters and their value

ObjectDbType type()

template < typename T >
void set_parameter(const std::string & key, const T & value)

void set_parameter(const std::string & key, const or_json::mValue & value)

void set_type(const std::string & type)

void set_type(const ObjectDbType & type)

or_json::mValue at(const std::string & key)

const or_json::mObject & raw()

boost::shared_ptr< ObjectDb > generateDb()

Public Static Functions

ObjectDbType StringToType(const std::string & type)

std::string TypeToString(const ObjectDbParameters::ObjectDbType & type)

class object_recognition_core::db::Document

A Document holds fields (in the CouchDB sense) which are strings that are queryable, and attachments (that are un-queryable binary blobs)

Public Functions

Document()

~Document()

bool operator==(const Document & document)

void set_db(const ObjectDbPtr & db)

Update the db that this document should be associated with.

Parameters
  • db -

void set_document_id(const DocumentId & document_id)

Update the document_id that this document should be associated with.

Parameters
  • document_id -

void load_fields()

Fill the fields of the object

void Persist()

Persist your object to a given DB

void SetIdRev(const std::string & id, const std::string & rev)

Set the id and the revision number

const std::string & id()

const std::string & rev()

template < typename T >
void get_attachment_and_cache(const AttachmentName & attachment_name, T & value)

Extract a specific attachment from a document in the DB

Parameters
  • attachment_name -

  • value -

void get_attachment_stream(const AttachmentName & attachment_name, std::ostream & stream, MimeType mime_type = MIME_TYPE_DEFAULT)

Extract the stream of a specific attachment for a Document from the DB

Parameters
  • attachment_name -

    the name of the attachment

  • stream -

    the string of data to write to

  • mime_type -

    the MIME type as stored in the DB

void get_attachment_stream_and_cache(const AttachmentName & attachment_name, std::ostream & stream, MimeType mime_type = MIME_TYPE_DEFAULT)

Extract the stream of a specific attachment for a Document from the DB

Parameters
  • attachment_name -

    the name of the attachment

  • stream -

    the string of data to write to

  • mime_type -

    the MIME type as stored in the DB

Implementing your own DB type

If you want to create your own DB type, look at the examples from the core like CouchDb or filesystem. You just have to inherit from ObjectDb.