#include <database.h>
Inheritance diagram for databases::Database:
Public Types | |
typedef std::list< Database * > | container_type |
Type of the list of databases. | |
typedef container_type::const_iterator | const_iterator |
Const iterator type. | |
typedef container_type::const_reverse_iterator | const_reverse_iterator |
Const reverse iterator type. | |
typedef std::vector< Field * > | fields_type |
Type of the list of fields. | |
enum | { vtImport = 1, vtExport = 2, vtMinimum = 3, vtMaximum = 4 } |
Versions type used to set and retrieve version numbers. More... | |
enum | { dpInitial = 0x0001, dpCreate = 0x0002, dpUpdate = 0x0004, dpDelete = 0x0008, dpExport = 0x0010, dpImport = dpCreate | dpUpdate | dpDelete } |
Possible permissions. More... | |
enum | { dsRegistered = 0x0001, dsStarted = 0x0002, dsInitial = 0x0004 } |
Possible status bits. More... | |
Public Member Functions | |
Database (modules::Core &core) | |
Constructor. | |
virtual | ~Database () |
Destructor. | |
bool | start () |
"Starts" the database. | |
virtual bool | insert (Record const *record) |
Inserts a record in the database. | |
virtual bool | update_s (Record const *record, Field const *field, char const *value) |
Updates a string value of a record. | |
virtual bool | update_i (Record const *record, Field const *field, int32_t value) |
Updates an integer value of a record. | |
virtual bool | update_ui (Record const *record, Field const *field, uint32_t value) |
Updates an unsigned integer value of a record. | |
virtual bool | update_ut (Record const *record, Field const *field, time_t value) |
Updates a Unix timestamp value of a record. | |
virtual bool | update_ri (Record const *record, Field const *field, Record::identifier_type value) |
Updates a record identifier value of a record. | |
virtual bool | update_multi (Record const *record, unsigned int valcount, va_list args) |
Updates multiples values of a record. | |
virtual bool | update_owned (Field const *field, Record::identifier_type id, Record::identifier_type new_id) |
Updates owned records in the database. | |
virtual bool | delete_ (Record const *record) |
Deletes a record from the database. | |
virtual bool | delete_owned (Field const *field, Record::identifier_type id) |
Deletes owned records from the database. | |
virtual bool | truncate () |
Clears all records from the database. | |
Collection * | coll () |
Returns the collection associated with the database. | |
Collection * | coll (Collection *coll) |
Sets the collection associated with the database. | |
std::string const & | name () const |
Returns the database name. | |
std::string const & | name (std::string const &name) |
Sets the database name. | |
uint16_t | version (int type) const |
Returns version numbers. | |
uint16_t | version (int type, uint16_t ver) |
Sets version numbers. | |
uint16_t | perms () const |
Returns database permissions. | |
uint16_t | perms_add (uint16_t perms) |
Adds database permissions. | |
uint16_t | perms_remove (uint16_t perms) |
Removes database permissions. | |
virtual Field * | field_create (char const *name, uint16_t minver, uint16_t type, size_t size, uint16_t attrs, char const *def, uint16_t tag=0) |
Creates a new field for this database. | |
virtual bool | field_add (Field *field) |
Adds a field to this database. | |
Field * | field_find (char const *name, int restrict=0) |
Finds a field in this database. | |
virtual bool | readable () const |
Returns whether data can potentially be read from the database. | |
virtual bool | writable () const |
Returns whether data can potentially be written to the database. | |
uint16_t | status () const |
Returns database status. | |
Static Public Member Functions | |
static Database * | find (std::string const &name) |
Finds a database by name. | |
static const_iterator | begin () |
Returns a const iterator to the first database in the list. | |
static const_iterator | end () |
Returns a const iterator to the last database in the list. | |
static const_reverse_iterator | rbegin () |
Returns a const reverse iterator to the first database in the list in reverse order. | |
static const_reverse_iterator | rend () |
Returns a const reverse iterator to the last database in the list in reverse order. | |
Static Public Attributes | |
static modules::PSIID const | IID = 0x42d05105 |
Interface identifier. | |
Protected Member Functions | |
virtual void | generate_expfields () |
Generates the list of exported fields. | |
virtual void | generate_impfields () |
Generates the list of imported fields. | |
virtual bool | reg () |
Registers the database. | |
virtual bool | start_real ()=0 |
"Starts" the database, overridable version. | |
Protected Attributes | |
modules::Core * | m_core |
Core module. | |
Collection * | m_coll |
The collection associated to the database. | |
std::string | m_name |
Name of the database. | |
uint16_t | m_impver |
The version number of the imported data. | |
uint16_t | m_expver |
The version number for the exported data. | |
uint16_t | m_minver |
Minimum version required for initial loading. | |
uint16_t | m_maxver |
Maximum version allowed for initial loading. | |
uint16_t | m_perms |
Permissions of the database. | |
fields_type | m_fields |
List of the fields. | |
fields_type | m_expfields |
List of exported fields. | |
fields_type | m_impfields |
List of imported fields. | |
uint16_t | m_status |
Status of the database. |
Basically, what database drivers do is loading and saving records using the functions provided by the Record class and a list of fields that describe the values contained in the record which can then be retrieved without having to know how the record manages its data internally. There is also good error detection provided by the records so that the database driver can correct or discard a record it is loading in case there is bogus data in its values.
So to sum it up, the goal of database drivers is to take care of all the details pertaining to its storage method while complying to a generic interface so that they can be reused by all other modules needing to store data persistently. And since there's no need for the records to know how they're stored, they can use whatever database driver they want without having to write extra code that would be painful to maintain in the long term.
To use a database, you must get an instance of a database from a module through its Module::factory function, then set its name, version information, permissions, add fields and finally call the start() function.
The start_real() function must be overriden in derived classes. The generate_expfields(), reg(), readable() and writable(), field_create(), field_add(), insert(), update_s(), update_i(), update_ui(), update_ut(), update_ri(), delete_(), delete_owned() and truncate() functions may be overriden too.
This interface must be exposed by database modules through the Module::factory() function.
|
|
|
|
|
|
|
Constructor.
|
|
Sets the collection associated with the database. The database will add, update and remove records through this collection. It must remain valid until the database is destructed (the database destructor is guaranteed not to use the collection.)
|
|
Deletes a record from the database. This function is usually called by the Collection::remove_db() function of the associated collection. The default implementation returns false if the dpExport permission is not set or writable() yields false, else it just returns true.
|
|
Deletes owned records from the database, i.e. records whose owner field's value is the given record identifier. The default implementation returns false if the dpExport permission is not set or writable() yields false, else it just returns true.
|
|
Adds a field to this database, which should have been created through a call to the field_create() function. After the field is added to the database, it is owned by it; the database will therefore free it when it is destructed. This function will automatically call the Field::setup() function before it is added to the database. No additional checks are made.
|
|
Creates a new field for this database. The created field can be freed by calling operator delete on it. The default implementation creates a field of the class Field. It is however possible to override this function to create a field of a derived class.
|
|
Finds a field in this database by name.
|
|
Finds a database by name, using the global list of databases that is maintained internally with started databases.
|
|
Generates the list of exported fields (the m_expfields member). The exported fields are fields that match the vtExport version of the database. This is called from the start() function before the database is registered, but only if the dpExport perm is set.
|
|
Generates the list of imported fields (the m_impfields member). The imported fields are fields that match the vtImport version of the database. This may be called by the database driver, if needed, after the version of the imported has been set. It can be called a second time once initial loading has taken place, and in this case, the generated list will be the same as the one generated through generate_expfields(). The start() function calls this function right after it calls generate_expfields() when the dpInitial permission is not set.
|
|
Inserts a record in the database. This function is usually called by the Collection::add_db() function of the associated collection. The default implementation returns false if the dpExport permission is not set or writable() yields false, else it just returns true.
|
|
Sets the database name. The name must only contain characters 0-9A-Za-z_ (no checks are made so you must make sure it is correct.) Setting the name when the dsRegistered flag is set in the database status has no effect.
|
|
Adds database permissions. Note that permissions describe what the database driver is allowed to do, not what it HAS to do (whether or not it does support all features is up to the implementer). Adding permissions when the dsRegistered flag is set in the database status has no effect.
|
|
Removes database permissions. Removing permissions when the dsRegistered flag is set in the database status has no effect.
|
|
Returns whether data can potentially be read from the database by the database driver. The result is totally independant of whether the permissions set for the database allow it to import records or not; it's just meant to be used as an indicator of whether the database can be read. The default implementation always returns true.
|
|
Registers the database. The default implementation adds the database to the list of databases. This is _vital_ for good operation, and you should therefore always call the base version of the function if you inherit it in derived classes.
|
|
"Starts" the database. This function must be called by user modules in their Module::start() function (to make sure the database module has been started). This function ensures properties have been set (for those that _MUST_ be set, at least ;), calls generate_expfields(), calls generate_impfields() if the dpInitial permission is not set, then calls the reg() function to add the database to the databases list (and possibly other lists if it is overriden in derived classes). Finally, the start_real() function is called.
|
|
"Starts" the database. This must be overriden in derived classes. This function must do initial loading if the dpInitial permission is set, and should do so according to the procedure described in the perms_add() function.
|
|
Clears all records from the database. This function is usually called by the Collection::clear_db() function of the associated collection. The default implementation returns false if the dpExport permission is not set or writable() yields false, else it just returns true.
|
|
Updates an integer value of a record. This function is usually called by the Collection::change_i() function of the associated collection. The default implementation returns false if the dpExport permission is not set or writable() yields false, else it just returns true.
|
|
Updates multiples values of a record. This function is usually called by the Collection::change_multi() function of the associated collection. The default implementation returns false if the dpExport permission is not set or writable() yields false, else it just returns true. Note that unlike the other update_ functions, it is up to the implementers to check if the fields are indeed exportable through a call to field_find(name, vtExport);
|
|
Updates owned records in the database, i.e. records whose owner field's value is the given record identifier, to a new value. The default implementation returns false if the dpExport permission is not set or writable() yields false, else it just returns true.
|
|
Updates a record identifier value of a record. This function is usually called by the Collection::change_ri() function of the associated collection. The default implementation returns false if the dpExport permission is not set or writable() yields false, else it just returns true.
|
|
Updates a string value of a record. This function is usually called by the Collection::change_s() function of the associated collection. The default implementation returns false if the dpExport permission is not set or writable() yields false, else it just returns true.
|
|
Updates an unsigned integer value of a record. This function is usually called by the Collection::change_ui() function of the associated collection. The default implementation returns false if the dpExport permission is not set or writable() yields false, else it just returns true.
|
|
Updates a Unix timestamp value of a record. This function is usually called by the Collection::change_ut() function of the associated collection. The default implementation returns false if the dpExport permission is not set or writable() yields false, else it just returns true.
|
|
Sets version numbers for the database. Setting version numbers when the dsRegistered flag is set in the database status has no effect.
|
|
Returns version numbers that have been set for the database. Each database has its own version number that allows to handle the data differently for different versions.
|
|
Returns whether data can potentially be written to the database by the database driver. The result is totally independant of whether the permissions set for the database allow it to export records or not; it's just meant to be used as an indicator of whether the database can be written. The default implementation returns true if the modules::Core::pfReadOnly program flag is not set for the core, false otherwise.
|