NAME
Starch::Store - Base role for Starch stores.
DESCRIPTION
This role defines an interfaces for Starch store classes. Starch store classes are meant to be thin wrappers around the store implementations (such as DBI, CHI, etc).
See "STORES" in Starch for instructions on using stores and a list of available Starch stores.
See "WRITING" for instructions on writing your own stores.
This role adds support for method proxies to consuming classes as described in "METHOD PROXIES" in Starch.
REQUIRED ARGUMENTS
manager
The Starch::Manager object which is used by stores to access configuration and create sub-stores (such as the Layered store's outer and inner stores). This is automatically set when the stores are built by Starch::Factory.
OPTIONAL ARGUMENTS
max_expires
Set the per-store maximum expires which will override the state's expires if the state's expires is larger.
ATTRIBUTES
can_reap_expired
Return true if the stores supports the "reap_expired" method.
short_store_class_name
Returns "short_class_name" in Starch::Role::Log with the Store:: prefix remove.
METHODS
new_sub_store
Builds a new store object. Any arguments passed will be combined with the "sub_store_args".
sub_store_args
Returns the arguments needed to create a sub-store. Any arguments passed will be combined with the default arguments. The default arguments will be "manager" and "max_expires" (if set). More arguments may be present if any plugins extend this method.
calculate_expires
Given an expires value this will calculate the expires that this store should use considering what "max_expires" is set to.
reap_expired
This triggers the store to find and delete all expired states. This is meant to be used in an offline process, such as a cronjob, as finding and deleting the states could take hours depending on the amount of data and the storage engine's speed.
By default this method will throw an exception if the store does not define its own reap method. You can check if a store supports this method by calling "can_reap_expired".
WRITING
The Starch::Store::CHI store is a good example store to use for building new store classes. See "STORES" in Starch for more existing stores.
A store must implement the "set", "get", and "remove" methods and consume the Starch::Store role.
Writing new stores is generally a trivial process where the store class does nothing more than glue those three methods with some underlying implementation such as DBI or CHI.
Stores should be written so that the underlying driver object (the $dbh for a DBI store, for example) can be passed as an argument. This allows the user to utilize "METHOD PROXIES" in Starch to build their own driver objects.
A state's expires duration is stored in the state data under the "expires_state_key" in Starch::Manager. This should not be considered as anything meaningful to the store, since stores can have their "max_expires" in Starch::Store argument set which will automatically change the value of the expiration argument passed to set.
REQUIRED METHODS
Stores must implement three methods for setting, getting, and removing state data. These methods receive a state ID and a namespace array ref as their first two arguments. The combination of these two values should identify a unique location in the store. They can be combined to create a single key string using "stringify_key" in Starch::Manager.
A more detailed description of the methods that a store must implement:
set
Sets the data for the key. The $expires value will always be set and will be either 0 or a positive integer representing the number of seconds in the future that this state data should be expired. If 0 then the store may expire the data whenever it chooses.
get
Returns the data for the given key. If the data was not found then undef is returned.
remove
Deletes the data for the key. If the data does not exist then this is just a no-op.
EXCEPTIONS
Stores should detect issues and throw exceptions loudly. If the user would like to automatically turn store exceptions into log messages they can use the Starch::Plugin::LogStoreExceptions plugin.
REAPING EXPIRED STATES
Stores may choose to support an interface for deleting old state data suitable for a cronjob. To do this two methods must be declared, "can_reap_expired" and "reap_expires". See Starch::Store::Amazon::DynamoDB for an example of a store which supports this feature.
The actual implementation of how to reap old state data is a per-store and is something that will differ greatly between them.
Consider adding extra arguments to your store class to control how state reaping functions. For example, a DBI store may allow the user to reap the states in batches, and a DynamoDB store may allow the user to specify a secondary global index to do the scan on.
AUTHORS AND LICENSE
See "AUTHOR" in Starch, "CONTRIBUTORS" in Starch, and "LICENSE" in Starch.