From: Mugen Kenichi <mugen.kenichi@uninets.eu>
Date: Thu, 29 Sep 2011 13:36:07 +0000 (+0200)
Subject: added documentation for DBIC and Mongo storage
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=c5fd316378c75a594660428da1daaa65b2f9dc74;p=p5sagit%2FEmail-Archive.git

added documentation for DBIC and Mongo storage
---

diff --git a/lib/Email/Archive.pm b/lib/Email/Archive.pm
index 66af16b..e6bf3e0 100644
--- a/lib/Email/Archive.pm
+++ b/lib/Email/Archive.pm
@@ -18,7 +18,6 @@ has storage => (
 
 1;
 
-
 __END__
 
 =head1 NAME
diff --git a/lib/Email/Archive/Storage/DBIC.pm b/lib/Email/Archive/Storage/DBIC.pm
index 0875c1a..58f6390 100644
--- a/lib/Email/Archive/Storage/DBIC.pm
+++ b/lib/Email/Archive/Storage/DBIC.pm
@@ -76,3 +76,73 @@ sub storage_connect {
 
 1;
 
+__END__
+
+=head1 NAME
+
+Email::Archive::Storage::DBIC - write emails to relational databases
+
+=head1 SYNOPSIS
+
+Email::Archive::Storage::DBIC is a storage engine for Email::Archive
+to store emails in databases utilizing DBIx::Class.
+
+All methods should work like documented in Email::Archive. Construction
+is slightly different as you have to tell Email::Archive to use the storage.
+
+    my $dbic_archive = Email::Archive->new(
+        storage => Email::Archive::Storage::DBIC->new,
+    );
+
+=head1 METHODS
+
+=head2 connect
+
+Takes a DBI connection string as parameter.
+
+    $email_archive->connect('dbi:SQLite:dbname=emails');
+
+For more information see DBI documentation.
+
+If the database schema does not exist it will be deployed automatically by
+the connect method.
+
+=head2 store
+
+    $email_archive->store($msg);
+
+Where $msg could be anything feedable to Email::Abstract. That is a raw
+email, an Email::MIME object or even an Email::Abstract object.
+
+The message will be stored in the messages table of the connected database.
+
+=head2 search
+
+    $email_archive->search($attributes);
+
+Search the database for emails where $attributes is a hashref containing
+the fields to search and the values filter.
+
+    $attributes = { from_addr => $addr };
+
+Will return the first found result as Email::MIME object.
+
+    $email_archive->search({ message_id => $some_id });
+
+Is exactly the same as retrieval by Message-ID.
+
+=head2 retrieve
+
+    $email_archive->retrieve($msg_id);
+
+Retrieve emails by Message-ID. Is a shortcut for
+
+    $email_archive->search({ message_id => $some_id });
+
+=head1 LICENSE
+
+This library may be used under the same terms as Perl itself.
+
+=head1 AUTHOR AND COPYRIGHT
+
+Copyright (c) 2010, 2011 Chris Nehren C<apeiron@cpan.org>.
diff --git a/lib/Email/Archive/Storage/MongoDB.pm b/lib/Email/Archive/Storage/MongoDB.pm
index 4c6bd94..ddefc72 100644
--- a/lib/Email/Archive/Storage/MongoDB.pm
+++ b/lib/Email/Archive/Storage/MongoDB.pm
@@ -84,3 +84,110 @@ sub storage_connect {
 
   return 1;
 }
+
+__END__
+
+=head1 NAME
+
+Email::Archive::Storage::MongoDB - write emails to MongoDB
+
+=head1 SYNOPSIS
+
+Email::Archive::Storage::MongoDB is a storage engine for Email::Archive
+to store emails in a MongoDB database.
+
+Construction and connecting to the database is slightly different from the
+default. The other methods should work like documented in Email::Archive.
+
+    my $storage = Email::Archive::Storage::MongoDB->new(
+        host       => $hostname,        # defaults to localhost
+        port       => $port,            # defaults to 27017
+        database   => $db_name,
+        collection => $collection_name,
+    );
+
+    my $mongo_archive = Email::Archive->new(
+        storage => $storage,
+    );
+
+Or
+    my $mongo_archive = Email::Archive->new(
+        storage => Email::Archive::Storage::MongoDB->new;
+    );
+
+The alternate construction needs a connection string passed to connect.
+
+=head1 ATTRIBUTES
+
+=head2 host
+
+The database host to connect to. Default is localhost.
+
+=head2 port
+
+The port on the database host to connect to. Defaults to MongoDBs default
+port 27017.
+
+=head2 database
+
+A valid MongoDB database name. If the database does not exist it will be
+created.
+
+=head2 collection
+
+A MongoDB collection name. If the collection does not exist it will be
+created automatically.
+
+=head1 METHODS
+
+=head2 connect
+
+If the storage was constructed passing all the needed arguments just connect.
+
+    $mongo_archive->connect;
+
+Alternative connection needs to have a connection string of the format
+host:port:database:collection and will override previously configured
+values.
+
+    $mongo_archive->connect("$host:$port:$dbname:$collname");
+
+=head2 store
+
+    $email_archive->store($msg);
+
+Where $msg could be anything feedable to Email::Abstract. That is a raw
+email, an Email::MIME object or even an Email::Abstract object.
+
+The message will be stored in the messages table of the connected database.
+
+=head2 search
+
+    $email_archive->search($attributes);
+
+Search the database for emails where $attributes is a hashref containing
+the fields to search and the values filter.
+
+    $attributes = { from_addr => $addr };
+
+Will return the first found result as Email::MIME object.
+
+    $email_archive->search({ message_id => $some_id });
+
+Is exactly the same as retrieval by Message-ID.
+
+=head2 retrieve
+
+    $email_archive->retrieve($msg_id);
+
+Retrieve emails by Message-ID. Is a shortcut for
+
+    $email_archive->search({ message_id => $some_id });
+
+=head1 LICENSE
+
+This library may be used under the same terms as Perl itself.
+
+=head1 AUTHOR AND COPYRIGHT
+
+Copyright (c) 2010, 2011 Chris Nehren C<apeiron@cpan.org>.