View source for PersistentPoolStorage

When [[Writing own storage|writing your own storage]], the '''PerstentPoolStorage''' can be used as the base for all storages that contain several entries of the same kind that are identified by an id and can write itself to some kind of persistent storage (like a harddisk or a database). This storages fills the dummy methods commit(), rollback() and isDirty() with some life. 

== Additional Methods ==

=== load(mixed $id = null) ===
Loads the data for the entry identified by $id from the persistent storage. 

=== reset() ===
Marks a storage as not loaded and resets all values and the shadow storage.

=== getID(): mixed ===
Returns the current id.

=== isLoaded(): bool ===
Returns if the storage is loaded at all.

=== setStructure(array $structure) ===
For some methods it could be necessary to tell the storage something about the structure of the owning property. Just thing about creating database tables or storing data to several files depending on the origin of a property.

The above function takes an array parameter called $structure. This array contains the structure of the owning property. The elements of the array are a stdClass with following members:
* '''name''': A string parameter that holds the name of this property
* '''type''': The primitive type (like integer, date, string, etc.) of this property
* '''property_class''': The full qualified name of the owning property class. This is important for the objects.

Depending on type there could be some additional members that give additional information
* '''string'''
** '''max_length''': The maximum length that the string could take
* '''array'''
** '''element_type''': The type of a element of the array.

=== structureNeeded() ===
This method checks, if a structure of the owning property was passed. If not it raises an exception.

=== getModifiedValues(): array ===
Returns an associative array with all fields that where modified or added. The key of the array is the name of the field and the value is a stdClass object with two memebers:
*'''old''': is the previous value (or null if previously unset or new)
*'''new''': is the new value

=== migrate() ===
Checks if the persistent storage media is prepared at all and if yes if its on the current state that fits to the structure. 

== Mandatory methods to overwrite ==

=== doCommitLoaded() ===
Performs the transfer of a existing entry to the persistent storage (like database, file, etc.).

=== doCommitNew() ===
Performs the transfer of a new entry to the persistent storage. This method has to return the newly given id that is used 
as a id for the storage.

=== isValidID(mixed $id): bool ===
Checks if the given $id is a valid one. Overwrite to check for a valid id (or if null is allowed as a ID)

== Optional methods to overwrite ==
=== doMigrateNew() ===
Optional. By default it does nothing. This method should prepare the persistent storage to store values to it (like creating database tables, files, etc.)

=== doMigrateUpdate() ===
Optional. By default it does nothing. This method should update the persistent storage so that it fits to the current structure (like modifying database tables, files, etc.)

=== isAlreadyMigrated(): bool ===
Optional. By default it returns true. Overwrite this method if the persistent storage has to be prepared. This method then checkes if the persistent storage is prepared at all.

=== isMigrationUptodate(): bool ===
Optional. By default it returns true. Overwrite this method if the persistent storage has to be prepared. This method then checks if the persistent storage is on a current state that fits to the structure. 

[[Category:Storages]]