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
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