Caching services for Foswiki extensions
Description
This package is used by other extensions in need of caching services. This specific cache stores data
for a short period time, e.g. one day, for faster access in the meantime. Data might be any arbitrary
perl data object which is serialized by the underlying cache implementation
CHI - Unified cache handling interface.
CHI offers some interesting features such as multi-level caching, shared caching and distributed caching
based on the configuration. It thus is suitable to share cached data among several Foswiki backends, either on the same host
or in a distributed setup.
Perl API
Interface to the caching services. This consists of two parts:
- basic caching: cache computational results for a short period of time for faster access
- a caching user agent: fetch external resources and cache them
Both of these requirements happen so often in Foswiki plugins that they have been provided as
a basic service to be accessed by third party plugins. For instance, ImagePlugin caches
image geometries as analysing and extracting this information from pictures can be quite expensive.
NumberPlugin fetches exchange rates of currencies from an external provider and caches them locally.
FeedPlugin fetches RSS and Atom feeds and caches them locally when rerendering them on a Foswiki page.
SolrPlugin serializes binary document formats while indexing their content with interim results cached
locally to speed up reindexing those documents.
getUserAgent($namespace) → $ua
returns a singleton caching user agent compatible to
CPAN:LWP::UserAgent.
The optional
namespace (defaults to "UserAgent") parameter defines the cache section used for this agent.
getCache($namespace, $expire) → $cache
returns a
CHI cache object for the given namespace.
my $cache = Foswiki::Contrib::CacheContrib::getCache("ImagePlugin");
getExternalResource($url, ...) → $response
Fetch an external resource using the caching UserAgent. This is equivalent
to
Foswiki::Func::getExternalResource() with just adding caching.
It basically is compatible with
LWP::UserAgent::get.
Usage:
my $response = Foswiki::Contrib::CacheContrib::getExternalResource($url);
throw Error::Simple("http error fetching $url: ".$response->code." - ".$response->status_line)
unless $response->is_success;
my $content = $response->decoded_content();
clearCache($namespace)
clears the cache for the given namespace
purgeCache($namespace)
purges expired entries of the cache for the given namespace
Clearing and Purging the cache
The cache can be cleared or purged using a separate tool that is best installed as a cronjob to perform these
maintenance steps offline on a regular base.
-
purgeCache: purge outdated cache entries as configured in the $Foswiki::cfg{CacheContrib}{CacheExpire} setting
-
clearCache: clear all of the cache independently of its expiry time
-
virtualhosts-pureCache, virtualhosts-clearCache: same scripts as above but to be used in a virtual hosting environment
LWP::UserAgent
CacheContrib implements a caching user agent ontop of the regular LWP::UserAgent. This can either be instanciated using the
Foswiki::Contrib::CacheContrib::getUserAgent() api
or by directly creating an object of the class
Foswiki::Contrib::CacheContrib::UserAgent. The default caching namespace for both is
UserAgent, that is all instances share
the same cache. The
UserAgent cache may be purged individually using the url parameter
refresh=on or
refresh=ua.
For convenience there is a caching variat of the standard API
Foswiki::Func::getExternalResource available at
Foswiki::Contrib::CacheContrib::getExternalResource which basically
behaves the same but except:
- uses proper proxy settings
- uses LWP::UserAgent for any network interaction
- uses caching
Installation Instructions
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.
Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button.
Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will
not show up in the
search results.
You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)
cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install
If you have any problems, or if the extension isn't available in
configure, then you can still install manually from the command-line. See
https://foswiki.org/Support/ManuallyInstallingExtensions for more help.
Dependencies
| Name | Version | Description |
|---|
| LWP::UserAgent | >=0 | Required |
| CHI | >=0 | Required |
Change History
| 02 Feb 2023 |
only http and https protocols are allowed fetching external resources |
| 27 Apr 2022 |
add support for multiple namespaces and cache agents; improve handling of per cache expiry parameters |
| 14 Oct 2020 |
initial release |
