A document has been updated:
http://cocoon.zones.apache.org/daisy/documentation/675.html
Document ID: 675
Branch: main
Language: default
Name: CacheableProcessingComponent Contracts (unchanged)
Document Type: Document (unchanged)
Updated on: 8/16/05 8:03:10 PM
Updated by: Berin Loritsch
A new version has been created, state: publish
Parts
=====
Content
-------
This part has been updated.
Mime type: text/xml (unchanged)
File name: (unchanged)
Size: 8622 bytes (previous version: 2931 bytes)
Content diff:
(3 equal lines skipped)
<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
+++ 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
+++ 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
+++ 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>
(6 equal lines skipped)
</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
+++ 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.
+++ 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
+++ 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
+++ 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>
+++ <p>The SourceValidity interface provides two <tt>isValid()</tt> methods,
which
+++ are used to check the validity of a source. The first call is to the version
+++ without parameters, which the SourceValidity will return
+++ <tt>SourceValidity.VALID</tt>,
+++ <tt><tt><tt>SourceValidity.UNKNOWN</tt></tt></tt>, or
+++ <tt>SourceValidity.INVALID</tt>. If the first call responds with
+++ <tt>SourceValidity.UNKNOWN</tt>, then a new SourceValidity object is
obtained
+++ from the CacheableProcessingComponent and that is passed into the
+++ <tt>isValid(SourceValidity)</tt> method. That can return the same set of
+++ responses. At this point, if the second comparison returns
+++ <tt>SourceValidity.UNKNOWN</tt> the action taken depends largely on the
cache's
+++ algorithm. It may play conservative and invalidate the entry, or it may play
+++ loose and use it anyway. The general contract is that the new SourceValidity
+++ object is considered unusable. The contract is that a SourceValidity object
will
+++ only be able to validate against another object of the same type. For
example, a
+++ TimestampValidity object can validate against another TimestampValidity
object
+++ but not a NOPValidity object.</p>
+++
+++ <p>The available SourceValidity objects provided by the Excalibur
SourceResolver
+++ component are (in the order of commonality):</p>
+++
+++ <ul>
+++ <li>NOPValidity--always valid</li>
+++ <li>TimeStampValidity--valid until a newer timestamp is found
+++ (System.currentTimeMillis())</li>
+++ <li>ExpiresValidity--valid until the expiration date is reached
+++ (System.currentTimeMillis() + time)</li>
+++ <li>FileTimestampValidity--valid until the referenced file changes</li>
+++ <li>AggregatedValidity--a compound validity object that is valid as long as
all
+++ the encapsulated validity objects are valid</li>
+++ <li>DeferredAggregatedValidity--a compound validity object that only gets
+++ validity objects if they are needed.</li>
+++ </ul>
+++
+++ <h3>NOPValidity</h3>
+++
+++ <p>Use the NOPValidity if you want to manually invalidate the cache entry
for an
+++ item, or if you have an object that is created once and simply reused. It
has
+++ limited use, but it is the easiest to set up. Just implement the
+++ <tt>getValidity()</tt> method like this:</p>
+++
+++ <pre>public SourceValidity getValidity()
+++ {
+++ return NOPValidity.SHARED_INSTANCE;
+++ }
+++ </pre>
+++
+++ <h3>TimeStampValidity</h3>
+++
+++ <p>The TimeStampValidity object is most commonly used with blobs retrieved
from
+++ the database, or some other information that only needs to be refreshed
when a
+++ newer version exists. The TimeStampValidity will always return
+++ <tt>SourceValidity.UNKNOWN</tt> until it is compared against a new
+++ TimeStampValidity object so that it can compare the dates. You can use this
+++ validity object like this:</p>
+++
+++ <pre>SourceValidity validity = new TimeStampValidity(timestamp.getTime());
+++
+++ public SourceValidity getValidity()
+++ {
+++ return validity;
+++ }
+++ </pre>
+++
+++ <h3>ExpiresValidity</h3>
+++
+++ <p>The ExpiresValidity object is used for items you want to keep around for
a
+++ while, but you know they will change within a certain amount of time. One
+++ example would be a clock snippet generator for your site. The clock is not
going
+++ to change for the granularity that you are displaying. If the clock is
+++ displaying the hour and minute, then you could set the expiration time to
+++ System.currentTimeMillis() plus one minute. All calls during that minute
would
+++ reuse the same information. While I doubt we would have a component that
only
+++ generates the time of day, you get the general idea. You would set it up
like
+++ this:</p>
+++
+++ <pre>SourceValidity validity = new
ExpiresValidity(System.currentTimeMillis() + (60 * 1000));
+++
+++ public SourceValidity getValidity()
+++ {
+++ return validity;
+++ }
+++ </pre>
+++
+++ <h3>FileTimeStampValidity</h3>
+++
+++ <p>The FileTimeStampValidity is used most often by components that depend
on an
+++ external file to produce its output. The most common examples would be your
+++ FileGenerator and the XSLTransformer components. The FileTimeStampValidity
+++ always checks the source file itself and uses the file system's timestamp to
+++ verify if the entry is still valid. You have three ways of setting it up:
+++ passing in the File reference, passing in the filename as a string, and
passing
+++ in a combination of the File and the original timestamp. The
+++ FileTimeStampValidity is commonly used by the FileSource object. Below is an
+++ example of using the validity object:</p>
+++
+++ <pre>SourceValidity validity = new FileTimeStampValidity( sourceFile );
+++
+++ public SourceValidity getValidity()
+++ {
+++ return validity;
+++ }
+++ </pre>
+++
+++ <h3>AggregatedValidity</h3>
+++
+++ <p>The AggregatedValidity is the mechanism that you would usually use to
combine
+++ any of the above validity types together and validate against all of them.
For
+++ example, let's assume your Generator depends on a source file, but it also
+++ depends on some time dependant information that needs to be calculated every
+++ minute. We would set it up like this:</p>
+++
+++ <pre>AggregatedValidity validity = new AggregatedValidity();
+++ validity.add( fileSource.getValidity() );
+++ validity.add( new ExpiresValidity( System.currentTimeMillis() + (60 * 1000)
) );
+++
+++ public SourceValidity getValidity()
+++ {
+++ return validity;
+++ }
+++ </pre>
+++
+++ <h3>DefferedAggregatedValidity</h3>
+++
+++ <p>We usually don't use this validity object directly for Sitemap
components,
+++ but it is referenced for the sake of completeness. It is used just like the
+++ AggregatedValidity object, only it adds an additional method to add
+++ DeferredValidity objects. The purpose is presumably to perform lazy
+++ initialization on some expensive validity objects so that the normal
validity
+++ objects are evaluated first, and the other validity objects are created on
+++ demand. There are no stock DeferredValidity object implementations that I
know
+++ of, so this is of little more than academic value for Cocoon components.</p>
+++
+++ <pre> </pre>
+++
</body>
</html>
Fields
======
no changes
Links
=====
no changes
Custom Fields
=============
no changes
Collections
===========
no changes
