NAME

Class::Cache - object factory with revivifying cache

SYNOPSIS

 use Class::Cache;

 my $class_cache = Class::Cache->new(
   # expire cache items when retrieved (on_get). The other option is
   # to never expire them, by setting this key's value to 0. Timed
   # expiry is not implemented or entirely expected in the application
   # domain of this module.
   expires   => 'on_get',

   # default constructor is new for items constructed by simple_* call
   new       => 'new',

   # call the constructor eagerly?
   lazy      => 0,

   # constructor takes no args by default
   args      => [],

   # IMPORTANT:
   # There is *_NO_* default package for object construction. If the
   # key C<pkg> does not exist in the configuration hash for a cache
   # item, then it is assumed that the cache item key is the package
   # name 

 );

 # All ofthe above constructor parms are the defaults, so the same
 # Class::Cache could have been created via Class::Cache->new();


 # Key and package are assumed to have the same name if "pkg" is not
 # part of the configuration hashref. Therefore, in this case
 # constructor name is "build". Do not expire this cache entry.
 $class_cache->set(
    'html::footer' => { new  => 'build', expires => 0 },
  );

 # Here, key and package have the same name. Constructor is new and we
 # supply args for it:
 $class_cache->set(
   'Class::Cache::Adder' => { args => [1,2,3] },
 )

 # key and package same name, constructor is new, takes no args 
 $class_cache->set(
    'Super::SimpleClass'   => 1,
 );

 $class_cache->set(
    # key is lazy_adder, lazily call as Lazy->Adder->new(1,2,3);
    lazy_adder => { lazy => 1, pkg => 'Lazy::Adder', args => [1,2,3] }
  );

 # Write a constructor as opposed to having this module build it.
 # Do not forget to use or require the module you need for your
 # custom factory to work!
 $class_cache->set(
   compo => { lazy => 1, new => sub { 
     my $pkg = 'Uber::Super::Cali::Fragi::Listic::Complex::Package';
     my $x = $pkg->this; $pkg->that; $pkg->give_object;
     }
   }

  );

DESCRIPTION

In mod_perl, one wants to pre-load as many things as possible. However, the objects created from the classes that I was loading can only be used once, after which they have to be recreated. So, to save oneself the trouble of keeping track of which class instances have been used and then writing code to re-vivify them, this module handles that.

METHODS

new

 Usage     : ->new(%factory_config)
 Purpose   : creates a new class cache. All object instances will be
             created per %default_factory_config, unless overridden in
             the call to set(). The possible configuration options
             were documented in the SYNOPSIS. The values given to
             these options are the default values.
 Returns   : returns a Class::Cache object
 Argument  : %factory_config
 Throws    : Exceptions and other anomolies: none

set

 Usage     : ->set($key => $factory_config)
 Purpose   : Creates a FactoryCache item accessible by $key whose value will
             be the object created in fashion specified by $factory_config.
             $factory_config can be either a hashref or a scalar. 
             If it is a scalar, then it uses the defaults for object
             creation
             If it is a hashref, then each of the given parameters in
             this hashref overwrite the default ones. Of particular
             important is the new parameter. If this is a scalar, then
             it is taken as the name of the constructor. If it is a
             coderef, then the only other factory_config parameter
             that matters is lazy. If lazy is set, then the
             constructor execution is delayed until the cache item is
             requested. Otherwise, the constructor runs immediately.
 Returns   : nothing
 Throws    : Exception if class cannot be created

get

 Usage     : ->get($cache_item_key)
 Purpose   : returns the cache item with name $cache_item_key. If the
             cache item was stored with the "lazy" parameter, then
             the cache item value is constructed now. If the cache
             item was stored with the "expires" parameter set to
             "on_get" then we expire this item.
 Returns   : the cache item value or undef

refill

 Usage     : ->refill
 Purpose   : recreates the objects which were expired from cache
 Returns   : nothing
 Argument  : none
 Throws    : nothing

classes

 Usage     : ->classes
 Purpose   : returns a list of the classes in the cache available for 
             retrieval
 Returns   : a list
 Argument  : none
 Throws    : nothing

expired

 Usage     : ->expired
 Purpose   : returns a list of the expired classes in the cache
 Returns   : a list
 Argument  : none
 Throws    : nothing

BUGS

None known.

SUPPORT

Email the author.

CVS SOURCES

 cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/seamstress login
 cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/seamstress co -P classcache

Or browse the repository here: http://cvs.sourceforge.net/viewcvs.py/seamstress

AUTHOR

        Terrence Brannon
        CPAN ID: TBONE
        metaperl.com
        metaperl@gmail.com
        http://www.metaperl.com

Original implementation had substantial help from mauke on

        irc://irc.efnet.org

Current version is completely new. I am indebted to Randal Schwartz for generating my interest in Class::Prototyped.

COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

perl(1).