diff options
author | dakkar <dakkar@thenautilus.net> | 2017-02-03 19:12:21 +0000 |
---|---|---|
committer | dakkar <dakkar@thenautilus.net> | 2017-02-03 19:12:21 +0000 |
commit | 7f9bafcc3ff4c959133fa1ca127b2a69206f9215 (patch) | |
tree | a021fc8d644890dcfccf07c609e7dc9b8ad2d14c /lib | |
parent | POD for ::Runner (diff) | |
download | Sietima-7f9bafcc3ff4c959133fa1ca127b2a69206f9215.tar.gz Sietima-7f9bafcc3ff4c959133fa1ca127b2a69206f9215.tar.bz2 Sietima-7f9bafcc3ff4c959133fa1ca127b2a69206f9215.zip |
POD for the MailStore interface
Diffstat (limited to 'lib')
-rw-r--r-- | lib/Sietima/MailStore.pm | 92 |
1 files changed, 91 insertions, 1 deletions
diff --git a/lib/Sietima/MailStore.pm b/lib/Sietima/MailStore.pm index 62fb835..5e9aa82 100644 --- a/lib/Sietima/MailStore.pm +++ b/lib/Sietima/MailStore.pm @@ -3,6 +3,96 @@ use Moo::Role; use Sietima::Policy; use namespace::clean; -requires 'store','retrieve_ids_by_tags','retrieve_by_tags','retrieve_by_id','remove','clear'; +=head1 NAME + +Sietima::MailStore - interface for mail stores + +=head1 DESCRPITON + +This role defines the interface that all mail stores must adhere +to. It does not provide any implementation. + +=head1 REQUIRED METHODS + +=head2 C<store> + + my $id = $ms->store($email_mime_object,@tags); + +Must persistently store the given email message (as an L<< +C<Email::Simple>> object or similar), associating it with the gives +tags (which must be strings). Must returns a unique identifier for the +stored message. It is acceptable if identical messages are +indistinguishable by the storage. + +=head2 C<retrieve_by_id> + + my $email_mime_object = $ms->retrieve_by_id($id); + +Given an identifier returned by L<< /C<store> >>, this method must +return the email message (as an L<< C<Email::Simple> >> or L<< +C<Email::MIME> >> object). + +If the message has been deleted, or the identifier is not recognised, +this method must return C<undef> in scalar context. + +=head2 C<retrieve_ids_by_tags> + + my @ids = $ms->retrieve_ids_by_tags(@tags)->@*; + +Given a list of tags (which must be strings), this method must return +an arrayref containing the identifiers of all (and only) the messages +that were stored associated with (at least) all those tags. The order +of the returned identifiers is not important. + +If there are no messages associated with the given tags, this method +must return an empty arrayref. + +For example: + + my $id1 = $ms->store($msg1,'t1'); + my $id2 = $ms->store($msg2,'t2'); + my $id3 = $ms->store($msg3,'t1','t2'); + + $ms->retrieve_ids_by_tags('t1') ==> [ $id3, $id1 ] + $ms->retrieve_ids_by_tags('t2') ==> [ $id2, $id3 ] + $ms->retrieve_ids_by_tags('t1','t2') ==> [ $id3 ] + $ms->retrieve_ids_by_tags('t3') ==> [ ] + +=head2 C<retrieve_by_tags> + + my @email_mime_objects = $ms->retrieve_by_tags(@tags)->@*; + +This method is similar to L<< /C<retrieve_ids_by_tags> >>, but it must +return an arrayref of hashrefs. For example: + + my $id1 = $ms->store($msg1,'t1'); + my $id2 = $ms->store($msg2,'t2'); + my $id3 = $ms->store($msg3,'t1','t2'); + + $ms->retrieve_ids_by_tags('t1') ==> [ + { id => $id3, mail => $msg3 }, + { id => $id1, mail => $msg1 }, + ] + +=head2 C<remove> + + $ms->remove($id); + +This method must remove the message corresponding to the given +identifier from the persistent storage. Removing a non-existent +message must succeed, and do nothing. + +=head2 C<clear> + + $ms->clear(); + +This method must remove all messages from the persistent +storage. Clearing a empty store must succeed, and do nothing. + +=cut + +requires 'store', + 'retrieve_ids_by_tags','retrieve_by_tags','retrieve_by_id', + 'remove','clear'; 1; |