The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Sietima-1.0.0
River stage zero No dependents
2 ++
/ Sietima::MailStore

NAME

Sietima::MailStore - interface for mail stores

VERSION

version 1.0.0

DESCRIPTION

This role defines the interface that all mail stores must adhere to. It does not provide any implementation.

REQUIRED METHODS

store

  my $id = $ms->store($email_mime_object,@tags);

Must persistently store the given email message (as an Email::Simple object or similar), associating it with the gives tags (which must be strings). Must return a unique identifier for the stored message. It is acceptable if identical messages are indistinguishable by the storage.

retrieve_by_id

  my $email_mime_object = $ms->retrieve_by_id($id);

Given an identifier returned by "store", this method must return the email message (as an Email::Simple or Email::MIME object).

If the message has been deleted, or the identifier is not recognised, this method must return undef in scalar context.

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') ==> [ ]

retrieve_by_tags

  my @email_mime_objects = $ms->retrieve_by_tags(@tags)->@*;

This method is similar to "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 },
  ]

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.

clear

  $ms->clear();

This method must remove all messages from the persistent storage. Clearing an empty store must succeed, and do nothing.

AUTHOR

Gianni Ceccarelli <dakkar@thenautilus.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Gianni Ceccarelli <dakkar@thenautilus.net>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.