databases::Database Class Reference

Database interface. More...

#include <database.h>

Inheritance diagram for databases::Database:

modules::Interface List of all members.

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.
Collectioncoll ()
 Returns the collection associated with the database.
Collectioncoll (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 Fieldfield_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.
Fieldfield_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 Databasefind (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::Corem_core
 Core module.
Collectionm_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.

Detailed Description

This interface must be used as a base class by modules providing a database driver (which are often referred to as database modules).

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.


Member Enumeration Documentation

anonymous enum
 

Enumerator:
vtImport  The version number of the imported data.
vtExport  The version number for the exported data.
vtMinimum  The minimum version number.
vtMaximum  The maximum version number.

anonymous enum
 

Enumerator:
dpInitial  Initial loading allowed.
dpCreate  Creation of records after initial loading allowed.
dpUpdate  Update of records allowed.
dpDelete  Deletion of records allowed.
dpExport  Records export allowed.
dpImport  Same as dpCreate | dpUpdate | dpDelete.

anonymous enum
 

Enumerator:
dsRegistered  reg() has been called
dsStarted  start_real() has been called
dsInitial  Initial loading has been done.


Constructor & Destructor Documentation

databases::Database::Database modules::Core core  )  [inline, explicit]
 

Constructor.

Parameters:
[in] core The core module.


Member Function Documentation

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.)

Parameters:
[in] coll The collection.
Returns:
The collection associated with the database.

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.

Parameters:
[in] record The record to delete.
Returns:
true if successful, false otherwise.

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.

Parameters:
[in] field The owner field.
[in] id The record identifier of the owner.
Returns:
true if successful, false otherwise.
See also:
Collection::remove_owned().

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.

Parameters:
[in] field The field to add to the database.
Returns:
true if successful, false otherwise (including if field is NULL).

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.

Parameters:
[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().
Returns:
The new field, or 0 on error.

Field* databases::Database::field_find char const *  name,
int  restrict = 0
 

Finds a field in this database by name.

Parameters:
[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:
  • 0 : no restriction (the default). Any field with this name will be returned.
  • vtImport: limit the search to the imported fields, that may have been generated through a call to generate_impfields(). If this call has not been done by the database driver, then the function always returns 0.
  • vtExport: limit the search to the exported fields, that are generated through a call to generate_expfields(). This call is done when the start() function is called if the dpExport permission is set; until that point, the function always returns 0.
Returns:
true if successful, false otherwise.

static Database* databases::Database::find std::string const &  name  )  [static]
 

Finds a database by name, using the global list of databases that is maintained internally with started databases.

Parameters:
[in] name The name of the database to find.
Returns:
A pointer to the database if it was found, 0 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.

Returns:
true if successful, false otherwise.

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.

Returns:
true if successful, false otherwise.

virtual bool databases::Database::insert Record const *  record  )  [virtual]
 

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.

Parameters:
[in] record The record to insert.
Returns:
true if successful, false otherwise.

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.

Parameters:
[in] name The name.
Returns:
The database name.

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.

Parameters:
[in] perms An or'ed set of the following permissions:
  • dpInitial: The database driver is allowed to add records to the collection when the start() function is called using the current contents of its database. This is called initial loading. Note that it'll be done only if the database versions match the requirements. The dsInitial status is set on the database when initial loading has been done.
  • dpCreate: The database driver is allowed to add records to the collection even after the start() function has been called.
  • dpUpdate: The database driver is allowed to update records that are in the collection.
  • dpDelete: The database driver is allowed to remove records from the collection.
  • dpExport: The database driver is allowed to add, update and remove records in its database. The new version of the database becomes the version set using the vtExport constant. If this perm is set and initial loading isn't done, then the database contents is entirely removed.
Returns:
The database permissions.
See also:
version(int)

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.

Parameters:
[in] perms The permissions to remove, which are the same as those for perms_add().
Returns:
The database permissions.
See also:
perms_add()

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.

Returns:
true if the database is readable, false otherwise.

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.

Returns:
true if successful, false otherwise.

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.

Returns:
true if successful, false otherwise.

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.

Returns:
true if successful, false otherwise.

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.

Returns:
true if successful, false otherwise.

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.

Parameters:
[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.
Returns:
true if successful, false otherwise.

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);

Parameters:
[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.
Returns:
true if successful, false otherwise.

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.

Parameters:
[in] field The owner field.
[in] id The record identifier of the owner.
[in] new_id The new record identifier of the owner.
Returns:
true if successful, false otherwise.

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.

Parameters:
[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.
Returns:
true if successful, false otherwise.

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.

Parameters:
[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.
Returns:
true if successful, false otherwise.

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.

Parameters:
[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.
Returns:
true if successful, false otherwise.

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.

Parameters:
[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.
Returns:
true if successful, false otherwise.

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.

Parameters:
[in] type The type of version to set, which can be either vtExport, vtMinimum or vtMaximum.
[in] ver The version number.
Returns:
The new version number for the given type.
See also:
version(int)

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.

Parameters:
[in] type The type of version to return, which can be one of the following values:
  • vtImport: The version number of imported data. After the initial loading of the data, this version is the same as the vtExport version if the dpExport permission is set. This may be zero if the database didn't exist prior to initial loading. If the dpInitial permission is not set on the database, but dpExport is set, this is always the same as the vtExport version.
  • vtExport: The version number of exported data. This is therefore the version number of the database after the initial loading. This version may be zero if the dpExport permission is not set.
  • vtMinimum: The minimum version number required. If the database has a lower version, initial loading won't be done (the dsInitial status flag is still set in any case though). This means that, if the dpExport permission is set, the contents of the database is removed. This version may be zero only if the dpInitial permission is not set.
  • vtMaximum: The minimum version number required. If the database has a higher version, initial loading won't be done(the dsInitial status flag is still set in any case though). This means that, if the dpExport permission is set, the contents of the database is removed. If the maximum version is zero, then there won't be any check for the maximum version number.
Returns:
The requested version number.

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.

Returns:
true if the database is writable, false otherwise.


The documentation for this class was generated from the following file:
Generated on Sun May 20 21:32:20 2007 for Epona API by  doxygen 1.4.6