#include <collection.h>
Public Types | |
enum | { ceUnknown = 1, ceID = 2, ceList = 3, ceDatabase = 4, ceHook = 5, ceCustom = 128 } |
Error constants. More... | |
enum | { csChanges = 0x0001, csInitial = 0x0002, csImport = 0x0004, csCreation = 0x0008, csUpdate = 0x0010, csDeletion = 0x0020, csNoDelete = 0x8000 } |
Possible status flags. More... | |
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. | |
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 Record * | create (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. | |
Record * | find (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. | |
void | add_hook (Hook *hook) |
Adds a hook to the collection. | |
void | remove_hook (Hook *hook) |
Removes a hook from the 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. | |
Database * | db () |
Returns the database associated to the collection (if any). | |
Database * | db (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. | |
Protected Types | |
enum | { chtPreAdd, chtPostAdd, chtPreUpdate, chtPostUpdate, chtPreRemove, chtPostRemove, chtNameChange, chtCount = 7 } |
Hook types. More... | |
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. | |
typedef std::list < Hook * > | hooks_list |
Type of the hooks 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. | |
bool | run_hooks (int type, Record *record, Field const *field=0) const |
Runs hooks of the given type. | |
Protected Attributes | |
id_hashlist | m_members |
The collection members, searchable by ID. | |
Database * | m_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. | |
hooks_list | m_hooks [chtCount] |
Hooks. | |
Static Protected Attributes | |
static uint32_t const | id_hashsize = ID_HASH_SIZE |
Size of the ID hash list. | |
Classes | |
class | Hook |
Collection hook. More... |
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.
anonymous enum |
anonymous enum |
anonymous enum [protected] |
virtual databases::Collection::~Collection | ( | ) | [virtual] |
Removes the Record::dbsMember status flag from each record in the collection, then calls operator delete on them.
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.
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.
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.
[in] | type | The type of import that will take place, which must be one of the following:
|
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().
[in] | type | The type of import that took place, which must be one of the following:
|
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.
virtual Record* databases::Collection::create | ( | Record::identifier_type | id = 0 |
) | const [pure virtual] |
Creates a new record suitable for this collection.
[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. |
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.
[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). |
Reimplemented in databases::ArrayCollection.
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.
[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. |
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.
[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. |
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.
[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. |
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.
[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. |
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.
[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. |
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.
[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). |
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.
[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::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.
[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). |
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.
[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). |
virtual bool databases::Collection::clear | ( | int * | err = 0 |
) | [virtual] |
Clears the collection. The function will call operator delete on each record in the 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). |
Record* databases::Collection::find | ( | Record::identifier_type | id | ) |
Finds a record in the collection.
[in] | id | The unique identifier of the record to find. |
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.
[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. |
void databases::Collection::unset_owned | ( | Collection & | coll | ) | [inline] |
Unsets an owned collection, that has been previously set through set_owned().
[in] | coll | The collection. |
void databases::Collection::add_hook | ( | Hook * | hook | ) |
Adds a hook to the collection. Hooks receive notification of various events in the collection.
[in] | hook | The hook to add. No copy is made, and the caller is responsible to remove the hook from the collection once it is no longer needed, AND to free it. |
void databases::Collection::remove_hook | ( | Hook * | hook | ) |
Removes a hook from the collection.
[in] | hook | The hook to remove. The caller is responsible for freeing the hook after it has been removed. |
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.
Reimplemented in databases::NameCollection, and databases::ArrayCollection.
Sets the database associated to the collection. The collection will then insert, update and delete records through it when the corresponding functions are called.
[in] | db | The database. This may be NULL if you don't want to store the collection records in a database. |
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.
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.
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.
[in] | coll | The owner collection. |
uint16_t databases::Collection::status_add | ( | uint16_t | flags | ) | [inline] |
Adds flags to the status of the collection.
[in] | flags | The flags to add. |
uint16_t databases::Collection::status_remove | ( | uint16_t | flags | ) | [inline] |
Removes flags from the status of the collection.
[in] | flags | The flags to remove. |
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.
[in] | record | The record to add. |
Reimplemented in databases::NameCollection, and 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.
[in] | record | The record to add. |
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.
[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). |
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).
[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). |
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!
[in] | record | The record to add. |
Reimplemented in databases::NameCollection, and databases::ArrayCollection.
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.
[in] | record | The record to add. |
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().
[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). |
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_db | ( | ) | [protected, virtual] |
Removes all records from the database. This is called by the clear() function.
bool databases::Collection::run_hooks | ( | int | type, | |
Record * | record, | |||
Field const * | field = 0 | |||
) | const [protected] |
Runs hooks of the given type. For hook types that have a boolean return values, hooks are called only until the first false return value is yielded.
[in] | type | The hook type, one of chtPreAdd, chtPostAdd, chtPreUpdate, chtPostUpdate, chtPreRemove, chtPostRemove |
[in] | record | The record. |
[in] | field | The field, if needed. |