NAME

Mail::Action::Role::Purge - purge expired objects from Mail::Action::Storage collections.

SYNOPSIS

use Mail::TempAddress::Addresses;
use Mail::Action::Role::Purge;
use Class::Roles
   apply => {
       role => 'Purge',
       to   => 'Mail::TempAddress::Addresses',
   };
my $addrs = Mail::TempAddress::Addresses->new( '/foo' );
for my $addr( $addrs->object_names ) {
    print "the address for ", $addr->owner, " expires at ",
          scalar localtime($addr->expires), "\n";
    if( $addr->expires < time() ) {
        $addrs->delete_from_storage($addr);
    }
}

DESCRIPTION

Mail::Action::Role::Purge provides a role to allow subclasses of Mail::Action::Storage to retrieve the names of all object in the collection and remove the file on disk underlying a named object.

ROLES

Purge

This role should be applied to a subclass of Mail::Action::Storage. It allows an object of the class to iterate over all objects in the collection and remove named object from the collection.

It adds several methods to the class to which it is applied:

object_names()

This method returns all a list of names of the objects in the collection. The objects are returned as a list in list context or a list reference in scalar context.

num_objects()

This method returns the number of objects in the collection. Similar to using

scalar @{ $storage->object_names }

But a bit quicker since the names themselves don't have to be passed from the method back to the caller.

delete_from_storage($name)

This method removes the file on disk that represents the named object. A true value is returned upon success and undef upon error. Inspect $! for details as to what went wrong.

purge($min_age)

This method is a frontend to num_objects() and delete_from_storage(). It gets the names of all objects in the collection, then in turn fetches each object and checks if it has expired. If it has, it deletes that object from the storage. The method returns the number of purged objects.

By default each object need only be expired. Passing the $min_expired_age requires that the object have been expired for at least that many seconds. The minimum age may also be passed using a freeform expression like '1h30m' or '2m1w'. See "address_expires" in Mail::Action::Address for more details.

For example, if an address object is set to expire at Mon Oct 27 19:31:39 2003 and the purge() routine is run at 19:33 with an argument of 300, then the data file for the object will not be deleted. If the purge method were to be called at 19:36:40 or any time thereafter then the data file will be deleted.

BACKGROUND

This module began life as Mail::TempAddress::Addresses::Purgeable, which was a simple subclass of Mail::TempAddress::Addresses designed to add purging functionality. At the time I wasn't aware of Mail::SimpleList.

After a few mails back and forth with chromatic, the topic of refactoring the common parts of Mail::TempAddress::Addresses and Mail::SimpleList came up, at which point the functionality provided by the original module made more sense to implement as a mixin.

About a week later chromatic re-factored those common parts out into Mail::Action. A couple of weeks after that he re-factored the common parts out into roles using his new Class::Roles module and suggested that I implement my module as a role rather than a mixin.

ACKNOWLEDGEMENTS

chromatic for providing tons of feedback and for developing Mail::Action and Class::Roles.

AUTHOR

James FitzGibbon <jfitz@CPAN.ORG>

COPYRIGHT

Copyright (c) 2003, James FitzGibbon. All rights reserved. This module is distributed under the same terms as Perl itself.