cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From da...@cocoon.zones.apache.org
Subject [DAISY] Created: CacheableProcessingComponent Contracts
Date Tue, 16 Aug 2005 15:40:39 GMT
A new document has been created.

http://cocoon.zones.apache.org/daisy/documentation/675.html

Document ID: 675
Branch: main
Language: default
Name: CacheableProcessingComponent Contracts
Document Type: Document
Created: 8/16/05 3:40:31 PM
Creator (owner): Berin Loritsch
State: publish

Parts
=====

Content
-------
Mime type: text/xml
Size: 2931 bytes
Content:
<html>
<body>

<h1>CacheableProcessingComponent Contracts</h1>

<p>Just about everything can be cached, so it makes sense to provide some
controls to make sure that the user always gets valid results.  There are two
aspects to a cacheable component: the key and the validition.  The key is used
to determine within the component's scheme of things whether a result is
unique.  For example, if your generator provides dynamic information based on an
ID and a user, you want to combine the two elements into one key.  That way
Cocoon can determine whether to use the cached information for the given ID/User
combination or create it from scratch.</p>

<p>The CachingPipeline will check the component's key to see if it even has the
information cached to begin with.  Next, it will check the validity of the
cached value if there is one.  If the cache has the resource and it is valid,
the CachingPipeline will return the cached results.  If either condition is
false, then the CachingPipeline will generate the results and cache it for later
use.  It is important to realize that only the CachingPipeline will respect the
contracts outlined in this document.</p>

<h2>The Cache Key</h2>

<p>The cache key is the single most important part of the caching
implementation.  If you don't get it right, you can introduce more load on the
caching engine than is necessary.  It is important that the cache key has the
following attributes:</p>

<ul>
<li>It must be Serializable (part of the contract of the <tt>getKey()</tt>
method).</li>
<li>It must be Immutable--the key is used as a lookup value</li>
<li>The <tt>equals()</tt> and <tt><tt><tt>hashCode()</tt></tt></tt>
methods must
be consistent (i.e. if two keys are equal, the hashCode must also be equal).
</li>
</ul>

<p>Thankfully there is a perfectly suitable object that satisfies these
obligations from Java's core: <tt>java.lang.String</tt>.  You can also use your
own specific key objects provided they respect those contracts.</p>

<p>If the cache key is <tt>null</tt> then your component will not be cached
at
all.  You can use this to your advantage to cache some things but not others.
</p>

<h2>The Source Validity</h2>

<p>The caching contracts use the Excalibur SourceValidity interface to determine
whether a resource is valid or not.  The validity can be a compound check that
incorporates time since creation, parameter values, etc.  As long as the sitemap
can determine whether the cached resource is valid or not.  More information is
available on the
<a href="http://excalibur.apache.org/sourceresolve/index.html">Apache Excalibur
site</a>.  Alternatively you can use the built in CacheValidity objects in the
<tt>org.apache.cocoon.caching</tt> package and then use the
<a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/caching/CacheValidityToSourceValidity.html">CacheValidityToSourceValidity</a>
adaptor object.</p>

</body>
</html>

Collections
===========
The document belongs to the following collections: documentation

Mime
View raw message