The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Apache-PAR-0.30
River stage zero No dependents
++
/ Apache::PAR::Static

NAME

Apache::PAR::Static - Serve static content to clients from within .par files.

SYNOPSIS

A sample configuration (within a web.conf) is below:

  Alias /myapp/static/ ##PARFILE##/
  <Location /myapp/static>
    SetHandler perl-script
    PerlHandler Apache::PAR::Static
    PerlSetVar PARStaticFilesPath htdocs/
    PerlSetVar PARStaticDirectoryIndex index.htm
    PerlAddVar PARStaticDirectoryIndex index.html
    PerlSetVar PARStaticDefaultMIME text/html
    PerlSetVar PARStaticCacheType memory
    PerlSetVar PARStaticCacheExpires "1 day"
    PerlSetVar PARStaticCacheMaxSize 1000
  </Location>

DESCRIPTION

The Apache::PAR::Static module allows a .par file creator to place any static content into a .par archive (under a configurable directory in the .par file) to be served directly to clients.

To use, add Apache::PAR::Static into the Apache configuration, either through an Apache configuration file, or through a web.conf file (discussed in more detail in Apache::PAR.)

Some things to note:

Apache::PAR::Static does not currently use Apache defaults in mod_dir. Therefore, it is necessary to specify variables for directory index files and the default mime type. To specify files to use for directory indexes, use the following syntax in the configuration:

  PerlSetVar PARStaticDirectoryIndex index.htm
  PerlAddVar PARStaticDirectoryIndex index.html
  ...

To set the default MIME type for requests, use: PerlSetVar PARStaticDefaultMIME text/html

Currently, Apache::PAR::Static does not have the ability to generate directory indexes for directories inside .par files. Also, other Apache module features, such as language priority, do not take effect for content inside .par archives.

The default directory to serve static content out of in a .par file is htdocs/ to override this, set the PARStaticFilesPath directive. For example, to set this to serve files from a static/ directory within the .par file, use:

  PerlSetVar PARStaticFilesPath static/

TIP: To serve the contents of a zip file as static content, this module can be used standalone (without the main Apache::PAR module). Try something like the following (in an httpd.conf file):

  Alias /zipcontents/ /path/to/a/zip/file.zip/
  <Location /zipcontents>
    SetHandler perl-script
    PerlHandler Apache::PAR::Static
    PerlSetVar PARStaticFilesPath /
    PerlSetVar PARStaticDirectoryIndex index.htm
    PerlAddVar PARStaticDirectoryIndex index.html
    PerlSetVar PARStaticDefaultMIME text/html
  </Location>

NOTE: Under mod_perl 1.x, byte range requests are supported, to facilitate the serving of PDF files, etc. For mod_perl 2.x users, use the appropriate Apache filter (currently untested.)

Caching static content

Apache::PAR::Static has the ability to cache static content for faster retrieval. In order to take advantage of this facility, the Cache::Cache module (available from CPAN) must be installed. Options available for caching:

  PerlSetVar PARStaticCacheType [memory|shared|file]
  PerlSetVar PARStaticCacheExpires "<expires string>"
  PerlSetVar PARStaticCacheMaxSize <maximum size in bytes>
  PerlSetVar PARStaticCacheMaxDebug 1

PARStaticCacheType must be set to either memory, shared or file depending on the type of cache desired. PARStaticCacheExpires, if present, must be set to a valid string accepted by Cache::Cache. The default value is "never". If set to a value, this controls how often members of the cache are expired. PARStaticCacheMaxSize, if present, must be set to a positive number representing the maximum size that the cache can grow to in bytes. The default if this is not set is to allow caches of any size. Setting this value may incur a performance penalty, see the documentation for Cache::Cache for more information. PARStaticCacheDebug, if set to a true value, will cause caching information to be displayed in the Apache server log. To see these messages, your LogLevel should be set to debug.

Caching can be very important, depending on performance requirements and hardware used. On my machine (Pentium 733 running RH 8 Linux and an untuned Apache 1.3.27), the following benchmarks were gathered:

  • Static content served via Apache: 177 req/sec.

  • Content served via Apache::PAR::Static without caching: 7 req/sec.

  • Content served via Apache::PAR::Static with memory caching: 111 req/sec.

You may want to play around with the various caching schemes to determing which one is best for your situation. A quick comparison chart is below of the various caching schemes:

  • memory: Fastest access, most memory consumed

  • file: Slowest access, least memory consumed

  • shared: middle in both areas

EXPORT

None by default.

AUTHOR

Nathan Byrd, <nathan@byrd.net>

SEE ALSO

perl.

Apache::PAR.

PAR.

Cache::Cache

COPYRIGHT

Copyright 2002 by Nathan Byrd <nathan@byrd.net>.

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

See http://www.perl.com/perl/misc/Artistic.html