NAME

       Cache::Entry - interface for a cache entry

SYNOPSIS

         my Cache::Entry $entry = $cache->entry( $key )
         my $data;
         if ($entry->exists()) {
             $data = $entry->get();
         }
         else {
             $data = get_some_data($key);
             $entry->set($data, '10 minutes');
         }

DESCRIPTION

       Objects derived from Cache::Entry represent an entry in a Cache.  Methods are provided
       that act upon the data in the entry, and allow you to set things like the expiry time.

       Users should not create instances of Cache::Entry directly, but instead use the
       entry($key) method of a Cache instance.

METHODS

       my $cache = $e->cache()
           Returns a reference to the cache object this entry is from.

       my $key = $e->key()
           Returns the cache key this entry is associated with.

       my $bool = $e->exists()
           Returns a boolean value (1 or 0) to indicate whether there is any data present in the
           cache for this entry.

       $e->set( $data, [ $expiry ] )
           Stores the data into the cache.  The data must be a scalar (if you want to store more
           complex data types, see freeze and thaw below).

           The expiry time may be provided as an optional 2nd argument and is in the same form as
           for 'set_expiry($time)'.

       my $data = $e->get()
           Returns the data from the cache, or undef if the entry doesn't exist.

       my $size = $e->size()
           Returns the size of the entry data, or undef if the entry doesn't exist.

       $e->remove()
           Clear the data for this entry from the cache.

       my $expiry = $e->expiry()
           Returns the expiry time of the entry, in seconds since the epoch.

       $e->set_expiry( $time )
           Set the expiry time in seconds since the epoch, or alternatively using a string like
           '10 minutes'.  Valid units are s, second, seconds, sec, m, minute, minutes, min, h,
           hour, hours, w, week, weeks, M, month, months, y, year and years.  You can also
           specify an absolute time, such as '16 Nov 94 22:28:20' or any other time that
           Date::Parse can understand.  Finally, the strings 'now' and 'never' may also be used.

       my $fh = $e->handle( [$mode, [$expiry] ] )
           Returns an IO::Handle by which data can be read, or written, to the cache.  This is
           useful if you are caching a large amount of data - although it should be noted that
           only some cache implementations (such as Cache::File) provide an efficient mechanism
           for implementing this.

           The optional mode argument can be any of the perl mode strings as used for the open
           function '<', '+<', '>', '+>', '>>' and '+>>'.  Alternatively it can be the
           corresponding fopen(3) modes of 'r', 'r+', 'w', 'w+', 'a' and 'a+'.  The default mode
           is '+<' (or 'r+') indicating reading and writing.

           The second argument is used to set the expiry time for the entry if it doesn't exist
           already and the handle is opened for writing.  It is also used to reset the expiry
           time if the entry is truncated by opening in the '>' or '+>' modes.  If the expiry is
           not provided in these situations then the default expiry time for the cache is
           applied.

           Cache implementations will typically provide locking around cache entries, so that
           writers will have have an exclusive lock and readers a shared one.  Thus the method
           get() (or obtaining another handle) should be avoided whilst a write handle is held.
           Using set() or remove(), however, should be supported.  These clear the current entry
           and whilst they do not invalidate open handles, those handle will from then on refer
           to old data and any changes to the data will be discarded.

STORING VALIDITY OBJECTS

       There are two additional set & get methods that can be used to store a validity object
       that is associated with the data in question.  Typically this is useful in conjunction
       with a validate_callback, and may be used to store a timestamp or similar to validate
       against.  The validity data stored may be any complex data that can be serialized via
       Storable.

       $e->validity()
       $e->set_validity( $data )

STORING COMPLEX OBJECTS

       The set and get methods only allow for working with simple scalar types, but if you want
       to store more complex types they need to be serialized first.  To assist with this, the
       freeze and thaw methods are provided.  They are simple wrappers to get & set that use
       Storable to do the serialization and de-serialization of the data.

       Note, however, that you must be careful to ONLY use 'thaw' on data that was stored via
       'freeze'.  Otherwise the stored data wont actually be in Storable format and it will
       complain loudly.

       $e->freeze( $data, [ $expiry ] )
           Identical to 'set', except that data may be any complex data type that can be
           serialized via Storable.

       $e->thaw()
           Identical to 'get', except that it will return a complex data type that was set via
           'freeze'.

SEE ALSO

       Cache, Cache::File

AUTHOR

        Chris Leishman <chris@leishman.org>
        Based on work by DeWitt Clinton <dewitt@unto.net>

COPYRIGHT

        Copyright (C) 2003-2006 Chris Leishman.  All Rights Reserved.

       This module is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
       expressed or implied. This program is free software; you can redistribute or modify it
       under the same terms as Perl itself.

       $Id: Entry.pm,v 1.8 2006/01/31 15:23:58 caleishm Exp $