














































|
 |  |  |  | A Brief Guide to the Cocoon Cache System |  |  |  |  |
The Cocoon cache system started off clean, simple, and easy to understand.
However, unfortunately, it has outstripped its original design, and there
are now various confusing aspects to it. This document does not attempt to
be an exhaustive guide to Cocoon caching, but attempts to briefly document
the most important aspects. A more comprehensive version may be written a
later time - and remember, we're always
looking for volunteers to write
documentation!
Please read the comments in cocoon.properties for an
explanation of the global caching parameters that Cocoon accepts.
In particular, disabling Last-Modified support appears to disable all
external caching (i.e. caching in web browsers, proxies, etc.)
 |  |  |  | What is cached and what is not? |  |  |  |  |
Currently, in Cocoon 1.x, the main result
that is cached is the final output (usually HTML) of the request.
Although a few other things are cached (such as in-memory representations
of stylesheets and logicsheets) these are largely transparent to the Cocoon
developer. In other words, the results of each stage in the pipeline
are not cached.
Various Cocoon components have different behaviours with regard to caching.
Some components disable caching for all requests that use them; others
flush a page from the cache and regenerate it under certain conditions.
As per the HTTP 1.1 spec, certain request types
such as PUT are never cached under any circumstances (however, POST is
not one of these types - although 99% of the time it is not advisable to
cache a POST request, it is possible to do so.)
The easiest way to disable caching for a particular page is to add
the <?cocoon-disable-caching?> processing instruction.
(But this won't work if inserted dynamically, except if it is inserted by
a Producer.)
 | This document is accurate with respect to Cocoon 1.8.1. Older and
newer versions may behave differently. |
In the table below, if any component being used by a request disables caching,
caching is disabled for that request. If any component being used by a request
invalidates the cache, the cached copy of that request is invalidated and removed.
Component
|
Component Type
|
Disables Caching For Affected Requests?
|
Invalidates Cache?
|
ProducerFromFile
|
Producer (default)
|
Never
|
When file changes
|
DCP
|
Processor
|
Always
|
n/a
|
LDAP
|
Processor
|
Always
|
n/a
|
SQL
|
Processor
|
Always
|
n/a
|
XInclude
|
Processor
|
Never
|
When included file changes(?)
|
XSLT
|
Processor
|
Never
|
When stylesheet changes. NOTE: The caching behaviour of
the XSLT document() function is not specified in the XSLT 1.0
specification, so we recommend an alternative (e.g.
the more powerful XInclude)
unless you don't care about caching.
|
XSP
|
"Processor"/"Producer"
|
By default, yes; however, XSP pages can override this by putting
<util:cacheable/> within <xsp:structure>
(see XSP documentation.)
|
Not applicable if util:cacheable tag is missing, since page will
never be cached. Otherwise, define the public boolean hasChanged
(Object context) method to define cache invalidation behaviour.
Always returning false will never invalidate, for example.
The context object is currently a HttpServletRequest. Default behaviour
is always invalidate. (see XSP documentation.)
|
All Cocoon-supplied Formatters
|
Formatters
|
Never
|
Never
|
|
The XSP repository where compiled XSP pages are stored
(see cocoon.properties ) is often thought of as a cache, but
strictly speaking it is not. At the moment, all commonly available Java compilers
such as javac and jikes will only read and write files,
not in-memory objects. Thus, writing .java and .class
files to disk is essential.
It does not really make sense to say that XSP pages are compiled once, and then
"cached" thereafter so that they do not have to be used again. While this is
approximately true, XSP generated classes are just normal classes - they remain
in memory after use. No caching mechanism is needed.
Although XSP is implemented in Cocoon 1 as a Processor, it is really more like a
Producer, because it ignores whether its input has changed. It was written based
on the assumption that it would be fed directly from a ProducerFromFile, and nothing
else. Thus XSPProcessor will not correctly handle dynamic input.
This is also why you cannot use XSP twice for one request
(unless you use something like XInclude).
 |
This anomaly has been corrected in Cocoon 2, where XSP is a Generator.
|
|
 |  |  |  | Example of caching dynamic content - Why Bother? |  |  |  |  |
If writing your own Producer or Processor, implement the
org.apache.cocoon.framework.Cacheable and
org.apache.cocoon.framework.Changeable interfaces to
define custom caching behaviour. The same degree of control is also
available to XSP pages - see table above.
|
|
|
|