Podius::Persistence::ComponentCache - persistent component manager and read/write cache
use Podius::Persistence::ComponentCache;
$cache = new Podius::Persistence::ComponentCache(
new Podius::Persistence::Media::RDBMS('Oracle', 'mag', 'user', 'pass'),
new Podius::Persistence::Media::RawData('../../rawdata'),
new Podius::Persistence::ComponentPropertyMap,
new Podius::Component::Root(new Parse::PerlConf("my.cfg"), ['Edition', [1]])
);
Components are stored in managed database using serialization. The ComponentCache object provides the persistent component storage and manages component memory (stores components only once, loads properties on demand, swaps components if the component limit is reached etc.).
The ComponentCache object uses: * Podius::Component::Root object (the only transient component in the component tree; it is created in constractor) * Persistence::Media (main and optionally secondary, also there is a posibility of two primary medias, one for load and one for save) * Persistence::ComponentPropertyMap object to ask about component property mapping to a persistence medias.
To write.
The module provides debug info via the Debug manpage module and throws exceptions via the Exception manpage module.
the Exception manpage, the Debug manpage, the Data::NeatFormat manpage. the Podius::Component manpage, the Podius::Component::Root manpage, the Podius::Persistence::ComponentIterator manpage.
* class name (as in any constructor) * primary persistence-media ref of Podius::Persistence::Media * secondary persistence-media ref of Podius::Persistence::Media * component-property-man ref of Podius::Persistence::ComponentPropertyMap * optionally root ref of Podius::Component::Root.
If the persistence-media argument is array ref, it is treated as list of two persistence medias (load and save). Normally loading and saving done using the same persistence-media.
size) and limit for a number of components participating in a
single cache operation, like [get/delete]_components (bunch_max).
Cache swaps out latest components if needed, to ensure there are always
bunch_max free places in the component storage before any operatrion.
Normally, the expression (size/bunch_max - 1) gives the number of cache
operations after them the loaded component is still in the memory. After
this number of operations it is unsafe to suppose a component reference is
still valid, use $component->lock to suppose this.
This method may only be called at the beginning or after free method call.
* size of the component storage * limit of components to request from persistence media at once.
preloads structure. It is a number of last
component groups (given by get_components) to optimize by preloading
properties in a entire component group when one component from the matched
group requests to load properties. This normally optimizes the number of
calls to persistence media methods, because there are big chances that
rest components in the group will shortly request the same properties and
they are already preloaded and cached.
Use parameter 0 to disable preloading optimizations.
This method may only be called at the beginning or after free method call.
Podius::Component::merge
and Podius::Property::merge methods for more details.
In the strict read-only mode (value is 2), calling create_component is
forbidden; in the non strict read-only mode (value is 1), new components can
be created, but they are not saved and when they are swapped out (without
really creating/saving them), there will be errors in accessing them again.
For this reason, it is not suggested to create new components in this mode,
or they should be locked not to be swapped out.
This method may only be called at the beginning or after free method call.
This method can't be called inside transaction.
* optional boolean value (default is 1)
$cache->begin_tx();
This acctually starts a native transaction in persistence media(s).
This call is now not needed for valid cache work. Changes to components, done outside the transaction are auto-commited by persistence media without rollback ability. But this method is better be called in most cases immideately after creating cache.
$cache->commit_tx();
commit to persistence media
$cache->abort_tx();
rollback to persistence media
* reloading all modified component (### or freeing cache?)
* deleting clones
$cache->free();
$component = $cache->get_component($type, $id);
* $type - component type * $id - component id, unique in $type
$cache->get_component('Article', 10);
@components = @{$cache->get_components($type, $id_array_ref)};
The method is optimized to retrieve all components of same type at once.
* $type - component type * $id_array_ref - reference to array of component ids, unique in $type
$cache->get_components('Edition', [1, 2]); # use strict;
$components = $cache->find_components($type, "name =~ 'my cats'"); $count = $cache->find_components($type, $cond, want_count => 1); $ids = $cache->find_components($type, $cond, want_ids => 1); $iterator = $cache->find_components($type, $cond, want_iterator => 1);
* $type - component type * $cond - condition, see Podius::Query for info * %params
Possible params keys (boolean, code or integer):
want_count - return the number of found components instead want_ids - return the component ids instead want_iterator - return the component iterator instead of arrayref sort - sorting function (gets two components, returns -1, 0 or 1) grep - filtering function (gets component, returns boolean) limit - maximal number of components/ids to return start - skip the given number of components/ids caching - string with caching policy, default is usually 'rw'
If sort is not given the returned ids are sorted numerically.
Instead of passing sort function, you may pass a method name (usually a property name, like ``name'' or ``-last_modified'') with optional dash prefix meaning reverse sorting. In this case the numeric sorting is done for numeric values and the string sorting is done otherwise. If you wish to always force the string sorting or to apply multiple conditions, supply your own sorting function.
my $count = $cache->last_find_components_count;
my $new_component = $cache->create_component($type); my $new_component = $cache->create_component($init_component);
* type - component type * id - optional id for a newly created component * init_component - optional component to copy properties from
Additionally, as a shortcut it is possible to pass init_component instead of type, in this case the type of init_component is used.
By default (if id is false) a new free id is assigned for the new component.
delete_component($type, $id);
* $type - component type * $id - component id, unique in $type
or
* $type - component class * $component - component itself to delete
or
* reference to the component to be deleted
$cache->delete_component('Article', 10);
verify_component($type, $id);
If the component existance was changed from the time it was first gotten by the cache, i.e. it does not exist anymore in the persistent storage, the component-delete-callback is called and the component is deleted from (0) or kept in (1) the cache.
You probably only want to call this method from an interactive application, which uses many short transactions, so the state of components in the persistent storage could be changed between transactions and you want to verify that the specified component is still valid before modifying it.
It is optional, you will get the effect of calling this method automatically on save if something had happened with that component.
* $type - component type * $id - component id, unique in $type
or
* $type - component class * $component - component itself to be verified
or
* reference to the component to be verified
* undef - the component does not exist and unknown to cache * -1 - the component exists in the persistent storage
In these 2 cases the component was deleted from the persistent storage and the component-delete-callback is called and its return value is returned:
* 0 - returned 0, lose it * 1 - returned 1, keep it
my $component = $cache->get_component('Publishable', 1);
$cache->verify_component($component);
* $type - container component type * $id - container component id, unique in $type * $collection_name - name of collection to iterate
or
* $type - container component type * $component - container component itself to work on * $collection_name - name of collection to iterate
or
* $component - container component itself to work on * $collection_name - name of collection to iterate
If you use the second variant with queries, query result must be one or more columns and ids are taken from the first column.
* $type - stored component type * $ids - stored component ids
or
* $type - stored component type * $query - low level query for persistence media to get ids
* $type - component type * $id - component id, unique in $type
or
* $type - component type * $component - component itself to clone
or
* reference to the component to be cloned
$cache->save_all_modified_components();
MUST BE OPTIMIZED to save data of all components of same class in one call.
reload_all_modified_components();