#include <database.h>
Inheritance diagram for databases::Database:
Public Types | |
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... | |
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. | |
Public Member Functions | |
Database (modules::Core &core) | |
Constructor. | |
virtual | ~Database () |
Destructor. | |
bool | start () |
"Starts" the database. | |
virtual bool | insert (Record *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 modules::Interface * | supports (modules::PSIID sid) |
Determines whether the database module supports an optional feature. | |
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. | |
static modules::PSIID const | sIDGen = 0x469def8f |
Does the database module support automatic identifier generation? | |
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(), supports(), readable(), 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.
anonymous enum |
anonymous enum |
anonymous enum |
dsRegistered | reg() has been called |
dsStarted | start_real() has been called |
dsInitial | Initial loading has been done. |
databases::Database::Database | ( | modules::Core & | core | ) | [inline, explicit] |
static Database* databases::Database::find | ( | std::string const & | name | ) | [static] |
bool databases::Database::start | ( | ) |
"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.
virtual bool databases::Database::insert | ( | Record * | record | ) | [virtual] |
Inserts a record in the database. This function is usually called by the Collection::add_db() function of the associated collection.
If the Database::supports(Database::sIDGen) function returns true, and the submitted record identifier is zero, the collection expects the record identifier to be set by this function. Otherwise, the collection will have set the record identifier at this point.
The default implementation returns false if the dpExport permission is not set or writable() yields false, else it just returns true.
[in] | record | The record to insert. |
virtual bool databases::Database::update_s | ( | Record const * | record, | |
Field const * | field, | |||
char const * | value | |||
) | [virtual] |
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.
[in] | record | The record to update. |
[in] | field | The record's field to update. |
[in] | value | The new value of the field of the record. |
virtual bool databases::Database::update_i | ( | Record const * | record, | |
Field const * | field, | |||
int32_t | value | |||
) | [virtual] |
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.
[in] | record | The record to update. |
[in] | field | The record's field to update. |
[in] | value | The new value of the field of the record. |
virtual bool databases::Database::update_ui | ( | Record const * | record, | |
Field const * | field, | |||
uint32_t | value | |||
) | [virtual] |
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.
[in] | record | The record to update. |
[in] | field | The record's field to update. |
[in] | value | The new value of the field of the record. |
virtual bool databases::Database::update_ut | ( | Record const * | record, | |
Field const * | field, | |||
time_t | value | |||
) | [virtual] |
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.
[in] | record | The record to update. |
[in] | field | The record's field to update. |
[in] | value | The new value of the field of the record. |
virtual bool databases::Database::update_ri | ( | Record const * | record, | |
Field const * | field, | |||
Record::identifier_type | value | |||
) | [virtual] |
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.
[in] | record | The record to update. |
[in] | field | The record's field to update. |
[in] | value | The new value of the field of the record. |
virtual bool databases::Database::update_multi | ( | Record const * | record, | |
unsigned int | valcount, | |||
va_list | args | |||
) | [virtual] |
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);
[in] | record | The record to update. |
[in] | valcount | The number of values that are being changed at once. There must be one Field pointer and one value of the corresponding field type (char * for Field::ftString, int32_t for Field::ftInteger, uint32_t for Field::ftUnsigned, time_t for Field::ftUnixTime and Record::identifier_type for Field::ftIdentifier) arguments for each. |
[in] | args | The arguments. |
virtual bool databases::Database::update_owned | ( | Field const * | field, | |
Record::identifier_type | id, | |||
Record::identifier_type | new_id | |||
) | [virtual] |
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.
[in] | field | The owner field. |
[in] | id | The record identifier of the owner. |
[in] | new_id | The new record identifier of the owner. |
virtual bool databases::Database::delete_ | ( | Record const * | record | ) | [virtual] |
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.
[in] | record | The record to delete. |
virtual bool databases::Database::delete_owned | ( | Field const * | field, | |
Record::identifier_type | id | |||
) | [virtual] |
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.
[in] | field | The owner field. |
[in] | id | The record identifier of the owner. |
virtual bool databases::Database::truncate | ( | ) | [virtual] |
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.
Collection* databases::Database::coll | ( | Collection * | coll | ) |
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.)
[in] | coll | The collection. |
std::string const& databases::Database::name | ( | std::string const & | name | ) |
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.
[in] | name | The name. |
uint16_t databases::Database::version | ( | int | type | ) | const |
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.
[in] | type | The type of version to return, which can be one of the following values:
|
uint16_t databases::Database::version | ( | int | type, | |
uint16_t | ver | |||
) |
Sets version numbers for the database.
Setting version numbers when the dsRegistered flag is set in the database status has no effect.
[in] | type | The type of version to set, which can be either vtExport, vtMinimum or vtMaximum. |
[in] | ver | The version number. |
uint16_t databases::Database::perms_add | ( | uint16_t | perms | ) |
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.
[in] | perms | An or'ed set of the following permissions:
|
uint16_t databases::Database::perms_remove | ( | uint16_t | perms | ) |
Removes database permissions.
Removing permissions when the dsRegistered flag is set in the database status has no effect.
[in] | perms | The permissions to remove, which are the same as those for perms_add(). |
virtual modules::Interface* databases::Database::supports | ( | modules::PSIID | sid | ) | [inline, virtual] |
Determines whether the database module supports an optional feature.
The default implementation always returns 0.
[in] | feature | The feature to test for availability, which may be one of the following:
|
Reimplemented from modules::Interface.
virtual Field* databases::Database::field_create | ( | char const * | name, | |
uint16_t | minver, | |||
uint16_t | type, | |||
size_t | size, | |||
uint16_t | attrs, | |||
char const * | def, | |||
uint16_t | tag = 0 | |||
) | [virtual] |
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.
[in] | name | The name of the field, which will be set on the newly created field through a call to Field::name(). |
[in] | minver | The minimum version number, which will be set on the newly created field through a call to Field::version(vtMinimum, minver). |
[in] | type | The type of the field, which will be set on the newly created field through a call to Field::type(). |
[in] | size | The size of the field, which will be set on the newly created field through a call to Field::size(). |
[in] | attrs | The attributes of the field, which will be set on the newly created field through a call to Field::attrs_add(). |
[in] | def | The default value of the field, which will be set on the newly created field through a call to Field::default_value(). |
[in] | tag | The tag of the field, which will be set on the newly created field through a call to Field::tag(). |
virtual bool databases::Database::field_add | ( | Field * | field | ) | [virtual] |
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.
[in] | field | The field to add to the database. |
Field* databases::Database::field_find | ( | char const * | name, | |
int | restrict = 0 | |||
) |
Finds a field in this database by name.
[in] | name | The name of the field to look for. |
[in] | restrict | The restriction to apply when looking for a field. This can be one of the following value:
|
virtual bool databases::Database::readable | ( | ) | const [inline, virtual] |
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.
virtual bool databases::Database::writable | ( | ) | const [virtual] |
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.
virtual void databases::Database::generate_expfields | ( | ) | [protected, virtual] |
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.
virtual void databases::Database::generate_impfields | ( | ) | [protected, virtual] |
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.
virtual bool databases::Database::reg | ( | ) | [protected, virtual] |
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.
virtual bool databases::Database::start_real | ( | ) | [protected, pure virtual] |
"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.