BusyBird::StatusStorage - interface for status storage objects
This is an interface (or role) class for status storage objects. This document is mainly for implementors of BusyBird::StatusStorage::* modules.
An BusyBird::StatusStorage implementation stores and serves status objects for multiple timelines. End-users usually access the status storage via BusyBird::Timeline objects.
This class implements nothing. An implementation of BusyBird::StatusStorage must be a subclass of BusyBird::StatusStorage and implement the following methods.
To test if an implementation of BusyBird::StatusStorage meets the specification, you can use functions provided by BusyBird::Test::StatusStorage.
Some methods are already implemented in BusyBird::StatusStorage::Common. You can import those implementations or implement them from scratch for better performance.
The above methods are the basis of BusyBird::Timeline's methods of the same names. See BusyBird::Timeline for the specification.
In addition to BusyBird::Timeline's specification, %args in all the methods has the following field.
%args
timeline
Specifies the name of the timeline. If the name includes Unicode characters, it must be a character string (decoded string), not a binary string (encoded string).
These methods are all in callback-style, that is, the results are not returned but given to the callback functions. This allows for both synchronous and asynchronous implementations.
This section describes guideline of the interface.
Implementations are recommended to follow the guideline, but they are allowed not to follow it if their own rule is clearly documented.
Throw an exception if obviously illegal arguments are given, i.e. if the user is to blame.
Never throw an exception but call callback with truthy $error if you fail to complete the request, i.e. if you is to blame.
callback
$error
If some statuses given to put_statuses() method do not have their id fields, the method may either throw an exception or automatically generate IDs for them and proceed.
put_statuses()
id
ack_statuses() method should update $status->{busybird}{acked_at} field of the target statuses to the date/time string of the current time. The date/time format should be parsable by BusyBird::DateTime::Format class.
ack_statuses()
$status->{busybird}{acked_at}
In timelines, statuses should be sorted in descending order of $status->{busybird}{acked_at} field (interpreted as date/time). Unacked statuses should always be above acked statuses. Ties are broken by sorting the statuses in descending order of $status->{created_at} field (interpreted as date/time).
$status->{created_at}
So the top of timeline is the latest created unacked status. Below unacked statuses are layers of acked statuses. The top of the acked statuses is the latest created status in the latest acked ones.
Toshio Ito <toshioito [at] cpan.org>
<toshioito [at] cpan.org>
To install BusyBird, copy and paste the appropriate command in to your terminal.
cpanm
cpanm BusyBird
CPAN shell
perl -MCPAN -e shell install BusyBird
For more information on module installation, please visit the detailed CPAN module installation guide.