databases::Collection Class Reference

Database records collection class. More...

#include <collection.h>

Inheritance diagram for databases::Collection:

databases::ArrayCollection databases::NameCollection List of all members.

Public Types

typedef id_hashlist::iterator iterator
 Normal iterator type.
typedef id_hashlist::const_iterator const_iterator
 Const iterator type.
typedef id_hashlist::reverse_iterator reverse_iterator
 Reverse iterator.
typedef id_hashlist::const_reverse_iterator const_reverse_iterator
 Const reverse iterator.
enum  {
  ceUnknown = 1, ceID = 2, ceList = 3, ceDatabase = 4,
  ceCustom = 128
}
 Error constants. More...
enum  {
  csChanges = 0x0001, csInitial = 0x0002, csImport = 0x0004, csCreation = 0x0008,
  csUpdate = 0x0010, csDeletion = 0x0020
}
 Possible status flags. More...

Public Member Functions

 Collection ()
 Constructor.
virtual ~Collection ()
 Destructor.
virtual bool begin_initial ()
 Begins initial import.
virtual bool end_initial ()
 Ends initial import.
virtual bool begin_import (uint16_t type)
 Begins import.
virtual bool end_import (uint16_t type)
 Ends import.
virtual bool update_new ()
 Asks the collection to update new fields.
virtual Recordcreate (Record::identifier_type id=0) const =0
 Creates a new record suitable for this collection.
virtual bool add (Record *record, int *err=0)
 Adds a record to the collection.
bool change_s (Record *record, Field const *field, char const *value)
 Changes a string value of a record.
bool change_i (Record *record, Field const *field, int32_t value)
 Changes an integer value of a record.
bool change_ui (Record *record, Field const *field, uint32_t value)
 Changes an unsigned integer value of a record.
bool change_ut (Record *record, Field const *field, time_t value)
 Changes a Unix timestamp value of a record.
bool change_ri (Record *record, Field const *field, Record::identifier_type value)
 Changes a record identifier value of a record.
bool change_multi (Record *record, unsigned int valcount,...)
 Changes a multiple values of a record.
bool change_owned (Field const *field, Record::identifier_type id, Record::identifier_type new_id)
 Changes owned records.
virtual bool remove (Record *record, int *err=0)
 Removes a record from the collection.
virtual bool remove_owned (Collection const *coll, Record const *record, int *err=0)
 Removes owned records from the collection.
virtual bool clear (int *err=0)
 Clears the collection.
Recordfind (Record::identifier_type id)
 Finds a record in the collection.
Record const * find (Record::identifier_type id) const
 Const version of find.
void set_owned (Collection &coll)
 Sets an owned collection.
void unset_owned (Collection &coll)
 Unsets an owned collection.
iterator begin ()
 Returns an iterator for the beginning of the collection.
iterator end ()
 Returns an iterator to the end of the collection.
const_iterator begin () const
 Returns a const iterator for the beginning of the collection.
const_iterator end () const
 Returns a const iterator to the end of the collection.
reverse_iterator rbegin ()
 Returns a reverse iterator to the beginning of the collection.
reverse_iterator rend ()
 Returns a reverse iterator to the end of the collection.
const_reverse_iterator rbegin () const
 Returns a const reverse iterator to the beginning of the collection.
const_reverse_iterator rend () const
 Returns a const reverse iterator to the end of the collection.
bool empty () const
 Determines whether the collection is empty.
id_hashlist::size_type size () const
 Returns the number of records in the collection.
virtual size_t memory_usage () const
 Returns the memory usage of the collection.
Databasedb ()
 Returns the database associated to the collection (if any).
Databasedb (Database *db)
 Sets the database associated to the collection.
bool readable () const
 Returns whether the collection is readable.
bool writable () const
 Returns whether the collection is writable.
virtual Field const * owner_field (Collection const *coll) const
 Returns the owner field corresponding to a owner collection.
uint16_t status () const
 Returns the collection status.
uint16_t status_add (uint16_t flags)
 Adds flags to the status of the collection.
uint16_t status_remove (uint16_t flags)
 Removes flags from the status of the collection.
Record::identifier_type last_id () const
 Returns the last assigned unique identifier of the collection.

Static Public Attributes

static Record::identifier_type
const 
external_id = 0x80000000
 The first ID number usable by database-submitted records.

Protected Types

typedef containers::HashList<
Record *, Record::identifier_type,
id_hashsize
id_hashlist
 Type of the ID hash list.
typedef std::list< Collection * > owned_list
 Type of the owned collections list.

Protected Member Functions

virtual bool add_list (Record *record)
 Adds the record to the list(s).
virtual bool add_db (Record *record)
 Adds the record to the database.
virtual bool remove_owned_db (Collection const *coll, Record const *record, int *err=0)
 Removes owned records from the database.
virtual bool remove_owned_list (Collection const *coll, Record const *record, int *err=0)
 Removes owned records from the lists.
virtual void remove_list (Record *record)
 Removes the record from the list(s).
virtual bool remove_db (Record *record)
 Removes the record from the database.
virtual bool clear_owned (Collection const *coll, int *err=0)
 Clears all owned records from the collection.
virtual void clear_list ()
 Removes all records from the list(s).
virtual bool clear_db ()
 Removes all records from the database.

Protected Attributes

id_hashlist m_members
 The collection members, searchable by ID.
Databasem_db
 The database associated with the collection.
uint16_t m_status
 The collection status.
Record::identifier_type m_last_id
 The last assigned identifier.
owned_list m_owned
 The owned collections.

Static Protected Attributes

static uint32_t const id_hashsize = ID_HASH_SIZE
 Size of the ID hash list.

Detailed Description

This is the class for database records collections, which keeps a list of all records in a database, and allows new records to be created, added or deleted.

Adding a record to a collection will insert it in the database if it wasn't done already. Removing a record from a collection will erase it from the database if it was in it. Please note that the collection may still be used without having an associated database; that allows you to have collections that optionally get stored in a database.

The create() must be overriden in derived classes, the add(), add_list(), add_db(), remove(), remove_list(), remove_db(), clear(), clear_list(), clear_db(), begin_initial(), end_initial(), begin_import(), end_import() and memory_usage() functions may be overriden too.


Member Enumeration Documentation

anonymous enum
 

Enumerator:
ceUnknown  Unknown error.
ceID  No more IDs available (if that happens... everything can happen).
ceList  List insertion/deletion error.
ceDatabase  Database error.
ceCustom  Custom errors start with this numbers (for overriders).

anonymous enum
 

Enumerator:
csChanges  There are changes in the collection (since the flag was last cleared).
csInitial  Initial import in progress.
csImport  Import in progress.
csCreation  Creation of records in progress (with csImport set).
csUpdate  Update of records in progress (with csImport set).
csDeletion  Deletion of records in progress (with csImport set).


Constructor & Destructor Documentation

virtual databases::Collection::~Collection  )  [virtual]
 

Removes the Record::dbsMember status flag from each record in the collection, then calls operator delete on them.


Member Function Documentation

virtual bool databases::Collection::add Record record,
int *  err = 0
[virtual]
 

Adds a record to the collection. No copy of the record is made, and so it must remain valid until it is removed from the collection. The unique identifier of the record is set by this function if it's not been set already.

The Record::dbsMember and Record::dbsInsert flags will be added to the record status, and the csChanges flag to the collection status.

Parameters:
[in] record The record to add.
[in] err If non-NULL and the function returns false, this variable will contain the error number (which can be ceUnknown, ceID, ceList, ceDatabase or other numbers defined by derived classes).
Returns:
true if the record has been added to the list, false otherwise.

Reimplemented in databases::ArrayCollection.

virtual bool databases::Collection::add_db Record record  )  [protected, virtual]
 

Adds the record to the database. This is called by the add() function, and only when Record::dbsInsert is not set for the record.

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

virtual bool databases::Collection::add_list Record record  )  [protected, virtual]
 

Adds the record to the list(s). This is called by the add() function, and only when Record::dbsMember is not set for the record.

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

Reimplemented in databases::NameCollection, and databases::ArrayCollection.

virtual bool databases::Collection::begin_import uint16_t  type  )  [inline, virtual]
 

Begins import. This function must be called by database modules before they begin to add, update or remove records after the initial import took place.

Parameters:
[in] type The type of import that will take place, which must be one of the following:
  • csCreation: creation of records
  • csUpdate: update of records
  • csDeletion deletion of records
The default implementation just sets the csImport and type flags to the collection status and returns true.

Returns:
true if import should continue, false otherwise.

virtual bool databases::Collection::begin_initial  )  [inline, virtual]
 

Begins initial import. This function must be called by database modules before they begin to create and add records during the initial import phase, even if there are no records to import.

db().version(Database::vtImport) must already return the correct version for the database being loaded.

The default implementation just sets the csInitial flag to the collection status and returns true.

Returns:
true if initial loading should continue, false otherwise.

bool databases::Collection::change_i Record record,
Field const *  field,
int32_t  value
 

Changes an integer value of a record. This will call Database::update_i() provided that there is a database set to the collection, that the record has already been added to the collection, that the record is not being updated by a database module and that the field is listed as exportable by the database module. If these conditions are not met, the function just returns true.

Parameters:
[in] record The record that changes.
[in] field The record's field that changes.
[in] value The new value of for the field of the record.
Returns:
true if the preconditions are not met or the database has been updated successfully, false otherwise.

bool databases::Collection::change_multi Record record,
unsigned int  valcount,
  ...
 

Changes a multiple values of a record. This will call Database::update_multi() provided that there is a database set to the collection, that the record has already been added to the collection and that the record is not being updated by a database module. If these conditions are not met, the function just returns true.

Parameters:
[in] record The record that changes.
[in] valcount The number of values that need to be changed.
[in] ... For each value that needs to be changed, a Field pointer and a value of the given 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).
Returns:
true if the preconditions are not met or the database has been updated successfully, false otherwise.

bool databases::Collection::change_owned Field const *  field,
Record::identifier_type  id,
Record::identifier_type  new_id
 

Changes record identifiers values of all records in the collection whose current value match a given ID. This will call Database::update_owned() provided that there is a database set to the collection and that the field is listed as exportable by the database module. If these conditions are not met, the function 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 the preconditions are not met or the database has been updated successfully, false otherwise.

bool databases::Collection::change_ri Record record,
Field const *  field,
Record::identifier_type  value
 

Changes a record identifier value of a record. This will call Database::update_ri() provided that there is a database set to the collection, that the record has already been added to the collection, that the record is not being updated by a database module and that the field is listed as exportable by the database module. If these conditions are not met, the function just returns true.

Parameters:
[in] record The record that changes.
[in] field The record's field that changes.
[in] value The new value of for the field of the record.
Returns:
true if the preconditions are not met or the database has been updated successfully, false otherwise.

bool databases::Collection::change_s Record record,
Field const *  field,
char const *  value
 

Changes a string value of a record. This will call Database::update_s() provided that there is a database set to the collection, that the record has already been added to the collection, that the record is not being updated by a database module and that the field is listed as exportable by the database module. If these conditions are not met, the function just returns true.

Parameters:
[in] record The record that changes.
[in] field The record's field that changes.
[in] value The new value of for the field of the record.
Returns:
true if the preconditions are not met or the database has been updated successfully, false otherwise.

bool databases::Collection::change_ui Record record,
Field const *  field,
uint32_t  value
 

Changes an unsigned integer value of a record. This will call Database::update_ui() provided that there is a database set to the collection, that the record has already been added to the collection, that the record is not being updated by a database module and that the field is listed as exportable by the database module. If these conditions are not met, the function just returns true.

Parameters:
[in] record The record that changes.
[in] field The record's field that changes.
[in] value The new value of for the field of the record.
Returns:
true if the preconditions are not met or the database has been updated successfully, false otherwise.

bool databases::Collection::change_ut Record record,
Field const *  field,
time_t  value
 

Changes a Unix timestamp value of a record. This will call Database::update_ut() provided that there is a database set to the collection, that the record has already been added to the collection, that the record is not being updated by a database module and that the field is listed as exportable by the database module. If these conditions are not met, the function just returns true.

Parameters:
[in] record The record that changes.
[in] field The record's field that changes.
[in] value The new value of for the field of the record.
Returns:
true if the preconditions are not met or the database has been updated successfully, false otherwise.

virtual bool databases::Collection::clear int *  err = 0  )  [virtual]
 

Clears the collection. The function will call operator delete on each record in the collection.

Parameters:
[in] err If non-NULL and the function returns false, this variable will contain the error number (which can be ceUnknown, ceList, ceDatabase or other numbers defined by derived classes).
Returns:
true if successful, false otherwise.

virtual bool databases::Collection::clear_db  )  [protected, virtual]
 

Removes all records from the database. This is called by the clear() function.

Returns:
true if successful, false otherwise.

virtual void databases::Collection::clear_list  )  [protected, virtual]
 

Removes all records from the list(s). This is called by the clear() function.

This function can't fail to do its job!

Reimplemented in databases::NameCollection, and databases::ArrayCollection.

virtual bool databases::Collection::clear_owned Collection const *  coll,
int *  err = 0
[protected, virtual]
 

Clears all owned records from the collection. This function is called by the clear() function when the owner collection is being cleared.

The default implementation just calls clear().

Parameters:
[in] coll The owner collection.
[in] err If non-NULL and the function returns false, this variable will contain the error number (which can be ceUnknown, ceList, ceDatabase or other numbers defined by derived classes).
Returns:
true if successful, false otherwise.

virtual Record* databases::Collection::create Record::identifier_type  id = 0  )  const [pure virtual]
 

Creates a new record suitable for this collection.

Parameters:
[in] id The identifier of the new record. Use the value 0 if you want the identifier to be computed automatically when the record is added to the collection.
Returns:
A newly-allocated record, or 0 if the record couldn't be created. This record should be freed using operator delete when it is no longer needed.

Database* databases::Collection::db Database db  )  [inline]
 

Sets the database associated to the collection. The collection will then insert, update and delete records through it when the corresponding functions are called.

Parameters:
[in] db The database. This may be NULL if you don't want to store the collection records in a database.
Returns:
The database associated with the collection.

virtual bool databases::Collection::end_import uint16_t  type  )  [inline, virtual]
 

Ends import. This function must be called by database modules after they finish to add new records after the initial import took place, and must have been preceded by a call to end_import().

Parameters:
[in] type The type of import that took place, which must be one of the following:
  • csCreation: creation of records
  • csUpdate: update of records
  • csDeletion deletion of records
The default implementation just removes the csImport flag from the collection status and returns true.

Returns:
true if successful, false otherwise.

virtual bool databases::Collection::end_initial  )  [inline, virtual]
 

Ends initial import. This function must be called by database modules after they finish to create and add records during the initial import phase, and must have been preceded by a call to begin_initial().

db().version(Database::vtImport) must still return the correct version for the database that has been loaded until this call is done.

The default implementation just removes the csInitial flag from the collection status and returns true.

Returns:
true if successful, false otherwise.

Record* databases::Collection::find Record::identifier_type  id  ) 
 

Finds a record in the collection.

Parameters:
[in] id The unique identifier of the record to find.
Returns:
A pointer to the found record, or 0 if it was not found.

virtual size_t databases::Collection::memory_usage  )  const [virtual]
 

Returns the memory usage of the collection. The Record::memory_usage() function of each record in the collection is called to form the final result.

Returns:
The memory usage of the collection, in bytes.

Reimplemented in databases::NameCollection, and databases::ArrayCollection.

virtual Field const* databases::Collection::owner_field Collection const *  coll  )  const [inline, virtual]
 

Returns the owner field of the records of this collection corresponding to the given owner collection.

The default implementation returns 0, and this must be changed if this collection is owned by another collection.

Parameters:
[in] coll The owner collection.
Returns:
A pointer to the owner field, or 0 if there is no owner field for this collection (which theorically NEVER happens when the Collection::remove_owned_db() function calls this method.)
See also:
remove_owned().

bool databases::Collection::readable  )  const
 

Returns whether the collection is readable. This just returns db()->readable(), unless no database has been set, in which case it always returns true.

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

virtual bool databases::Collection::remove Record record,
int *  err = 0
[virtual]
 

Removes a record from the collection. The record will be freed by the function with operator delete if the removal is successful.

The csChanges flag will be added to the collection status.

Parameters:
[in] record The record to remove.
[in] err If non-NULL and the function returns false, this variable will contain the error number (which can be ceUnknown, ceList, ceDatabase or other numbers defined by derived classes).
Returns:
true if the record has been removed from the list, false otherwise.

virtual bool databases::Collection::remove_db Record record  )  [protected, virtual]
 

Removes the record from the database. This is called by the remove() function, and only when Record::dbsInsert is set for the record.

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

virtual void databases::Collection::remove_list Record record  )  [protected, virtual]
 

Removes the record from the list(s). This is called by the remove() function, and only when Record::dbsMember is set for the record.

This function can't fail to do its job!

Parameters:
[in] record The record to add.

Reimplemented in databases::NameCollection, and databases::ArrayCollection.

virtual bool databases::Collection::remove_owned Collection const *  coll,
Record const *  record,
int *  err = 0
[virtual]
 

Removes owned records from the collection. This function is called by the remove() function when a record of the owner collection is being removed.

The default implementation calls remove_owned_db(), then if it is successful, calls remove_owned_list() and returns its return value.

Parameters:
[in] coll The owner collection.
[in] record The record of the owner collection being removed.
[in] err If non-NULL and the function returns false, this variable will contain the error number (which can be ceUnknown, ceList, ceDatabase or other numbers defined by derived classes).
Returns:
true if successful, false otherwise.

virtual bool databases::Collection::remove_owned_db Collection const *  coll,
Record const *  record,
int *  err = 0
[protected, virtual]
 

Removes owned records from the database. This function is called by the remove_owner() function.

The default implementation calls owner_field() to know which field corresponds to the owner collection, then calls db()->delete_owned() to remove records owned by the deleted record.

Parameters:
[in] coll The owner collection.
[in] record The record of the owner collection being removed.
[in] err If non-NULL and the function returns false, this variable will contain the error number (which can be ceUnknown, ceList, ceDatabase or other numbers defined by derived classes).
Returns:
true if successful, false otherwise.

virtual bool databases::Collection::remove_owned_list Collection const *  coll,
Record const *  record,
int *  err = 0
[protected, virtual]
 

Removes owned records from the lists. This function is called by the remove_owned() function.

The default implementation calls remove() on each record of the collection that are determined to be owned by the deleted record through a call to Record::owned() (the Record::dbsInsert flag is removed from the record status before the remove() function is called).

Parameters:
[in] coll The owner collection.
[in] record The record of the owner collection being removed.
[in] err If non-NULL and the function returns false, this variable will contain the error number (which can be ceUnknown, ceList, ceDatabase or other numbers defined by derived classes).
Returns:
true if successful, false otherwise.

void databases::Collection::set_owned Collection coll  )  [inline]
 

Sets an owned collection, i.e. a collection whose remove_owned() and clear_owned() functions shall be called respectively when a record is removed from this collection and when this collection is cleared.

Parameters:
[in] coll The owned collection. No copy is done and so it must remain valid until either unset_owned is called or this collection is destroyed.

uint16_t databases::Collection::status_add uint16_t  flags  )  [inline]
 

Adds flags to the status of the collection.

Parameters:
[in] flags The flags to add.
Returns:
The new collection status.

uint16_t databases::Collection::status_remove uint16_t  flags  )  [inline]
 

Removes flags from the status of the collection.

Parameters:
[in] flags The flags to remove.
Returns:
The new collection status.

void databases::Collection::unset_owned Collection coll  )  [inline]
 

Unsets an owned collection, that has been previously set through set_owned().

Parameters:
[in] coll The collection.

virtual bool databases::Collection::update_new  )  [inline, virtual]
 

Asks the collection to update any new fields that would need to be. This is called by the Database interface after it is ready to take updates for new fields, if the Database::dpExport permission is set and Database::writable() yields true.

The default implementation just returns true.

Returns:
true if successful, false otherwise.

bool databases::Collection::writable  )  const
 

Returns whether the collection is writable. This just returns db()->writable(), unless no database has been set, in which case it always returns true.

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


Member Data Documentation

Record::identifier_type const databases::Collection::external_id = 0x80000000 [static]
 

The first ID number usable by records submitted by databases. Records created by the program will ALWAYS have an ID lower than this one, while records created by an external application should always have an ID greater than this one. This provides greater safety against ID collision (as there is no way a record can be created with the same ID than another record inserted in the database externally).


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