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