/ 
BusyBird-0.12
River stage zero No dependents
/ BusyBird::StatusStorage

NAME

BusyBird::StatusStorage - interface for status storage objects

DESCRIPTION

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.

OBJECT METHODS

$storage->ack_statuses(%args)

$storage->get_statuses(%args)

$storage->put_statuses(%args)

$storage->delete_statuses(%args)

$storage->get_unacked_counts(%args)

$storage->contains(%args)

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.

timeline => TIMELINE_NAME (mandatory)

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.

GUIDELINE

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.

Error Handling for Callback-style Methods

  1. Throw an exception if obviously illegal arguments are given, i.e. if the user is to blame.

  2. Never throw an exception but call callback with truthy $error if you fail to complete the request, i.e. if you is to blame.

  3. 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.

acked_at Field

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.

Order of Statuses

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).

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.

AUTHOR

Toshio Ito <toshioito [at] cpan.org>