PerlDoc

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

---

Parent package: Foswiki
Child packages:

More ...Less ...

internal package Foswiki::PageCache

This class is a purely virtual base class that implements the basic infrastructure required to cache pages as produced by the rendering engine. Once a page was computed, it will be cached for subsequent calls for the same output. In addition a Foswiki::PageCache has to ensure cache correctness, that is all content stored in the cache is up-to-date. It must not return any content being rendered on the base of data that has already changed in the meantine by actions performed by the Foswiki::Store.

The Foswiki::Store informs the cache whenever any content has changed by calling Foswiki::PageCache::fireDependency($web, $topic). This will in turn delete any cache entries that used this $web.$topic as an ingredience to render the cached page. That's why there is a dependency graph part of the page cache.

The dependency graph records all topics that have been touched while the current page is being computed. It also records the session and url parameters that were in use, part of which is the user name as well.

An edge in the dependency graph consists of:

• from: the topic being rendered
• variation: an opaque key encoding the context in which the page was rendered
• to: the topic that has been used to render the "from" topic

For every cached page there's a record of meta data describing it:

• topic: the web.topic being cached
• variation: the context which this page was rendered within
• md5: fingerprint of the data stored; this is used to get access to the stored blob related to this page
• contenttype: to be used in the http header
• lastmodified: time when this page was cached in http-date format
• etag: tag used for browser-side caching
• status: http response status
• location: url in case the status is a 302 redirect
• expire: time when this cache entry is outdated
• isdirty: boolean flag indicating whether the cached page has got "dirtyareas" and thus needs post-processing

Whenever the Foswiki::Store informs the cache by firing a dependency for a given web.topic, the cache will remove those cache entries that have a dependency to the given web.topic. It thereby guarentees that whenever a page has been successfully retrieved from the cache, there is no "fresher" content available in the Foswiki::Store, and that this cache entry can be used instead without rendering the related yet again.

ClassMethod new( ) → $object

Construct a new page cache

ObjectMethod genVariationKey() → $key

Generate a key for the current webtopic being produced; this reads information from the current session and url params, as follows: * the server serving the request (HTTP_HOST) * the port number of the server serving the request (HTTP_PORT) * the action used to render the page (view or rest) * the language of the current session, if any * all session parameters EXCEPT: o Those starting with an underscore o VALIDATION o REMEMBER o FOSWIKISTRIKEONE.* o VALID_ACTIONS.* o BREADCRUMB_TRAIL o DGP_hash * all HTTP request parameters EXCEPT: o All those starting with an underscore o refresh o foswiki_redirect_cache o logout o topic o cache_ignore o cache_expire

ObjectMethod cachePage($contentType, $data) → $boolean

Cache a page. Every page is stored in a page bucket that contains all variations (stored for other users or other session parameters) of this page, as well as dependency and expiration information

ObjectMethod getPage($web, $topic)

Retrieve a cached page for the given web.topic, using a variation key based on the current session.

ObjectMethod setPageVariation($web, $topici, $variationKey, $variation) → $bool

stores a rendered page

ObjectMethod getPageVariation($web, $topic, $variationKey)

retrievs a cache entry; returns undef if there is none.

Checks whether the current page is cacheable. It first checks the "refresh" url parameter and then looks out for the "CACHEABLE" preference variable.

ObjectMethod addDependencyForLink($web, $topic)

Add a reference to a web.topic to the dependencies of the current page.

Topic references, unlike hard dependencies, may cause internal links - WikiWords to render incorrectly unless the cache is cleared when the topic changes. (i.e, link to a missing topic, or render as a "new link" for a newly existing topic).

This routine is configurable using {Cache}{TrackInternalLinks}. By default, it treats all topic references as simple dependencies. If disabled, link references are ignored, but if set to authenticated, links are tracked only for logged in users.

ObjectMethod addDependency($web, $topic)

Add a web.topic to the dependencies of the current page

ObjectMethod getDependencies($web, $topic, $variationKey) → \@deps

Return dependencies for a given web.topic. if $variationKey is specified, only dependencies of this page variation will be returned.

ObjectMethod getWebDependencies($web) → \@deps

Returns dependencies that hold for all topics in a web.

ObjectMethod setDependencies($web, $topic, $variation, @topics)

Stores the dependencies for the given web.topic topic. Setting the dependencies happens at the very end of a rendering process of a page while it is about to be cached.

When the optional @topics parameter isn't provided, then all dependencies collected in the Foswiki::PageCache object will be used. These dependencies are collected during the rendering process.

ObjectMethod deleteDependencies($web, $topic, $variation, $force)

Remove a dependency from the graph. This operation is normally performed as part of a call to Foswiki::PageCache::deletePage().

ObjectMethod deletePage($web, $topic, $variation, $force)

Remove a page from the cache; this removes all of the information that we have about this page, including any dependencies that have been established while this page was created.

If $variation is specified, only this variation of $web.$topic will be removed. When $variation is not specified, all page variations of $web.$topic will be removed.

When $force is true, the deletion will take place immediately. Otherwise all delete requests might be delayed and committed as part of Foswiki::PageCache::finish().

ObjectMethod deleteAll()

purges all of the cache

ObjectMethod fireDependency($web, $topic)

This method is called to remove all other cache entries that used the given $web.$topic as an ingredience to produce the page.

A dependency is a directed edge starting from a page variation being rendered towards a depending page that has been used to produce it.

While dependency edges are stored as they are collected during the rendering process, these edges are traversed in reverse order when a dependency is fired.

In addition all manually asserted dependencies of topics in a web are deleted, as well as the given topic itself.

ObjectMethod renderDirtyAreas($text)

Extract dirty areas and render them; this happens after storing a page including the un-rendered dirty areas into the cache and after retrieving it again.

ObjectMethod finish()

clean up finally