Cocoon Documentation
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.)
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.
Cocoon uses the following factors to decide if a request is equivalent to a previous one. Only if all factors are identical will the cached copy (if any) be used.
It is on the todo list to make this more configurable.
Sometimes there is no point, and it can even cause bugs. Hence, all dynamic content, by default, is not cached. However, because Cocoon caches based on the query string, as mentioned above, it can be useful to override this.
Suppose you are presenting a large web directory with Cocoon.
All of the directory content is served from a robust back-end database.
Since the root of the directory (?node=1) is requested so frequently, it
makes sense to cache the transformed representation (HTML) of this
and other popular nodes. Assuming you are using
XSP, you can simply declare <util:cacheable/>
and the
following method:
public boolean hasChanged (Object context) { return false; // to cache everything and leave // memory management up to Cocoon // or try { return Integer.parseInt (((HttpServletRequest) context).getParameter ("node")) < 50; // only cache the most important 50 nodes. } catch (NumberFormatException ex) { // error pages don't change return false; } }
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.
Copyright © 1999-2001 The Apache Software Foundation.
All rights reserved.