File Coverage

blib/lib/Cache/FileCache.pm
Criterion Covered Total %
statement 68 83 81.9
branch 4 8 50.0
condition 2 3 66.7
subroutine 23 29 79.3
pod 4 10 40.0
total 101 133 75.9


line stmt bran cond sub pod time code
1             ######################################################################
2             # $Id: FileCache.pm,v 1.32 2003/04/15 14:46:22 dclinton Exp $
3             # Copyright (C) 2001-2003 DeWitt Clinton All Rights Reserved
4             #
5             # Software distributed under the License is distributed on an "AS
6             # IS" basis, WITHOUT WARRANTY OF ANY KIND, either expressed or
7             # implied. See the License for the specific language governing
8             # rights and limitations under the License.
9             ######################################################################
10              
11              
12             package Cache::FileCache;
13              
14              
15 2     2   59 use strict;
  2         27  
  2         56  
16 2     2   31 use vars qw( @ISA );
  2         19  
  2         39  
17 2     2   106 use Cache::BaseCache;
  2         21  
  2         54  
18 2     2   40 use Cache::Cache;
  2         18  
  2         33  
19 2     2   28 use Cache::CacheUtils qw ( Assert_Defined Build_Path Static_Params );
  2         19  
  2         83  
20 2     2   76 use Cache::FileBackend;
  2         23  
  2         76  
21 2     2   43 use Cache::Object;
  2         21  
  2         70  
22 2     2   30 use Error;
  2         18  
  2         32  
23 2     2   74 use File::Spec::Functions;
  2         20  
  2         41  
24              
25              
26             @ISA = qw ( Cache::BaseCache );
27              
28              
29             # by default, the cache nests all entries on the filesystem three
30             # directories deep
31              
32             my $DEFAULT_CACHE_DEPTH = 3;
33              
34              
35             # by default, the root of the cache is located in 'FileCache'. On a
36             # UNIX system, this will appear in "/tmp/FileCache/"
37              
38             my $DEFAULT_CACHE_ROOT = "FileCache";
39              
40              
41             # by default, the directories in the cache on the filesystem should
42             # be globally writable to allow for multiple users. While this is a
43             # potential security concern, the actual cache entries are written
44             # with the user's umask, thus reducing the risk of cache poisoning
45              
46             my $DEFAULT_DIRECTORY_UMASK = 000;
47              
48              
49             sub Clear
50             {
51 16     16 1 205   my ( $p_optional_cache_root ) = Static_Params( @_ );
52              
53 16         472   foreach my $namespace ( _Namespaces( $p_optional_cache_root ) )
54               {
55 18         190     _Get_Cache( $namespace, $p_optional_cache_root )->clear( );
56               }
57             }
58              
59              
60             sub Purge
61             {
62 4     4 1 57   my ( $p_optional_cache_root ) = Static_Params( @_ );
63              
64 4         45   foreach my $namespace ( _Namespaces( $p_optional_cache_root ) )
65               {
66 4         44     _Get_Cache( $namespace, $p_optional_cache_root )->purge( );
67               }
68             }
69              
70              
71             sub Size
72             {
73 14     14 1 169   my ( $p_optional_cache_root ) = Static_Params( @_ );
74              
75 14         127   my $size = 0;
76              
77 14         147   foreach my $namespace ( _Namespaces( $p_optional_cache_root ) )
78               {
79 6         64     $size += _Get_Cache( $namespace, $p_optional_cache_root )->size( );
80               }
81              
82 14         230   return $size;
83             }
84              
85              
86             sub new
87             {
88 31     31 1 1761   my ( $self ) = _new( @_ );
89              
90 31         770   $self->_complete_initialization( );
91              
92 31         447   return $self;
93             }
94              
95              
96             sub _Get_Backend
97             {
98 34     34   393   my ( $p_optional_cache_root ) = Static_Params( @_ );
99              
100 34         391   return new Cache::FileBackend( _Build_Cache_Root( $p_optional_cache_root ) );
101              
102             }
103              
104              
105             # return the OS default temp directory
106              
107             sub _Get_Temp_Directory
108             {
109 68 50   68   1302   my $tmpdir = File::Spec->tmpdir( ) or
110                 throw Error::Simple( "No tmpdir on this system. Upgrade File::Spec?" );
111              
112 68         29644   return $tmpdir;
113             }
114              
115              
116             sub _Build_Cache_Root
117             {
118 34     34   429   my ( $p_optional_cache_root ) = Static_Params( @_ );
119              
120 34 50       333   if ( defined $p_optional_cache_root )
121               {
122 0         0     return $p_optional_cache_root;
123               }
124               else
125               {
126 34         316     return Build_Path( _Get_Temp_Directory( ), $DEFAULT_CACHE_ROOT );
127               }
128             }
129              
130              
131             sub _Namespaces
132             {
133 34     34   364   my ( $p_optional_cache_root ) = Static_Params( @_ );
134              
135 34         343   return _Get_Backend( $p_optional_cache_root )->get_namespaces( );
136             }
137              
138              
139             sub _Get_Cache
140             {
141 28     28   329   my ( $p_namespace, $p_optional_cache_root ) = Static_Params( @_ );
142              
143 28         471   Assert_Defined( $p_namespace );
144              
145 28 50       270   if ( defined $p_optional_cache_root )
146               {
147 0         0     return new Cache::FileCache( { 'namespace' => $p_namespace,
148                                                'cache_root' => $p_optional_cache_root } );
149               }
150               else
151               {
152 28         2394     return new Cache::FileCache( { 'namespace' => $p_namespace } );
153               }
154             }
155              
156              
157             sub _new
158             {
159 34     34   459   my ( $proto, $p_options_hash_ref ) = @_;
160 34   66     491   my $class = ref( $proto ) || $proto;
161              
162 34         3309   my $self = $class->SUPER::_new( $p_options_hash_ref );
163 34         9170   $self->_initialize_file_backend( );
164 34         2455   return $self;
165             }
166              
167              
168             sub _initialize_file_backend
169             {
170 34     34   363   my ( $self ) = @_;
171              
172 34         1289   $self->_set_backend( new Cache::FileBackend( $self->_get_initial_root( ),
173                                                            $self->_get_initial_depth( ),
174                                                            $self->_get_initial_umask( ) ));
175             }
176              
177              
178             sub _get_initial_root
179             {
180 34     34   307   my ( $self ) = @_;
181              
182 34 50       442   if ( defined $self->_read_option( 'cache_root' ) )
183               {
184 0         0     return $self->_read_option( 'cache_root' );
185               }
186               else
187               {
188 34         613     return Build_Path( _Get_Temp_Directory( ), $DEFAULT_CACHE_ROOT );
189               }
190             }
191              
192              
193             sub _get_initial_depth
194             {
195 34     34   332   my ( $self ) = @_;
196              
197 34         376   return $self->_read_option( 'cache_depth', $DEFAULT_CACHE_DEPTH );
198             }
199              
200              
201             sub _get_initial_umask
202             {
203 34     34   359   my ( $self ) = @_;
204              
205 34         450   return $self->_read_option( 'directory_umask', $DEFAULT_DIRECTORY_UMASK );
206             }
207              
208              
209             sub get_cache_depth
210             {
211 0     0 0     my ( $self ) = @_;
212              
213 0             return $self->_get_backend( )->get_depth( );
214             }
215              
216              
217             sub set_cache_depth
218             {
219 0     0 0     my ( $self, $p_cache_depth ) = @_;
220              
221 0             $self->_get_backend( )->set_depth( $p_cache_depth );
222             }
223              
224              
225             sub get_cache_root
226             {
227 0     0 0     my ( $self ) = @_;
228              
229 0             return $self->_get_backend( )->get_root( );
230             }
231              
232              
233             sub set_cache_root
234             {
235 0     0 0     my ( $self, $p_cache_root ) = @_;
236              
237 0             $self->_get_backend( )->set_root( $p_cache_root );
238             }
239              
240              
241             sub get_directory_umask
242             {
243 0     0 0     my ( $self ) = @_;
244              
245 0             return $self->_get_backend( )->get_directory_umask( );
246             }
247              
248              
249             sub set_directory_umask
250             {
251 0     0 0     my ( $self, $p_directory_umask ) = @_;
252              
253 0             $self->_get_backend( )->set_directory_umask( $p_directory_umask );
254             }
255              
256              
257             1;
258              
259              
260             __END__
261            
262             =pod
263            
264             =head1 NAME
265            
266             Cache::FileCache -- implements the Cache interface.
267            
268             =head1 DESCRIPTION
269            
270             The FileCache class implements the Cache interface. This cache stores
271             data in the filesystem so that it can be shared between processes.
272            
273             =head1 SYNOPSIS
274            
275             use Cache::FileCache;
276            
277             my $cache = new Cache::FileCache( { 'namespace' => 'MyNamespace',
278             'default_expires_in' => 600 } );
279            
280             See Cache::Cache for the usage synopsis.
281            
282             =head1 METHODS
283            
284             See Cache::Cache for the API documentation.
285            
286             =over
287            
288             =item B<Clear( [$cache_root] )>
289            
290             See Cache::Cache, with the optional I<$cache_root> parameter.
291            
292             =item B<Purge( [$cache_root] )>
293            
294             See Cache::Cache, with the optional I<$cache_root> parameter.
295            
296             =item B<Size( [$cache_root] )>
297            
298             See Cache::Cache, with the optional I<$cache_root> parameter.
299            
300             =back
301            
302             =head1 OPTIONS
303            
304             See Cache::Cache for standard options. Additionally, options are set
305             by passing in a reference to a hash containing any of the following
306             keys:
307            
308             =over
309            
310             =item I<cache_root>
311            
312             The location in the filesystem that will hold the root of the cache.
313             Defaults to the 'FileCache' under the OS default temp directory (
314             often '/tmp' on UNIXes ) unless explicitly set.
315            
316             =item I<cache_depth>
317            
318             The number of subdirectories deep to cache object item. This should
319             be large enough that no cache directory has more than a few hundred
320             objects. Defaults to 3 unless explicitly set.
321            
322             =item I<directory_umask>
323            
324             The directories in the cache on the filesystem should be globally
325             writable to allow for multiple users. While this is a potential
326             security concern, the actual cache entries are written with the user's
327             umask, thus reducing the risk of cache poisoning. If you desire it to
328             only be user writable, set the 'directory_umask' option to '077' or
329             similar. Defaults to '000' unless explicitly set.
330            
331             =back
332            
333             =head1 PROPERTIES
334            
335             See Cache::Cache for default properties.
336            
337             =over
338            
339             =item B<(get|set)_cache_root>
340            
341             See the definition above for the option I<cache_root>
342            
343             =item B<(get|set)_cache_depth>
344            
345             See the definition above for the option I<cache_depth>
346            
347             =item B<(get|set)_directory_umask>
348            
349             See the definition above for the option I<directory_umask>
350            
351             =back
352            
353             =head1 SEE ALSO
354            
355             Cache::Cache
356            
357             =head1 AUTHOR
358            
359             Original author: DeWitt Clinton <dewitt@unto.net>
360            
361             Last author: $Author: dclinton $
362            
363             Copyright (C) 2001-2003 DeWitt Clinton
364            
365             =cut
366