You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by cz...@apache.org on 2001/07/02 11:03:38 UTC
cvs commit: xml-cocoon2/xdocs caching.xml
cziegeler 01/07/02 02:03:38
Modified: xdocs caching.xml
Log:
Finished first version of caching docs
Revision Changes Path
1.7 +108 -9 xml-cocoon2/xdocs/caching.xml
Index: caching.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/xdocs/caching.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- caching.xml 2001/06/26 07:24:18 1.6
+++ caching.xml 2001/07/02 09:03:36 1.7
@@ -4,7 +4,7 @@
<header>
<title>Caching</title>
<subtitle>in Cocoon 2</subtitle>
- <version>0.1</version>
+ <version>0.9</version>
<type>Technical document</type>
<authors><person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
@@ -15,14 +15,19 @@
<p>This document explains the basic caching algorithm of Cocoon 2.</p>
</s1>
<s1 title="Overview">
- <p>Overview is forthcoming</p>
+ <p>The caching algorithm of Cocoon 2 has a very flexible and powerful design.
+ The used algorithms and components are not hardcoded into the core of
+ Cocoon 2. They can be configured using Avalon components.</p>
+ <p>This document describes the available components for caching,
+ how they can be configured and how to implement own cacheable components.
+ </p>
</s1>
<s1 title="Caching of event pipelines">
<p>The algorithm used for caching depends on the configured event pipeline.
For more information about configuration see the chapter below.</p>
<p>The following subchapters describe the available caching algorithms.</p>
- <s2 title="The CacheableEventPipeline">
- <p>The CacheableEventPipeline used a very easy but effectiv approach
+ <s2 title="The CachingEventPipeline">
+ <p>The CachingEventPipelineuses a very easy but effectiv approach
to cache the event pipelines of a request: The pipeline process
is cached up to the most possible point.</p>
<p>Each sitemap component (generator or transformer) which might be
@@ -97,7 +102,7 @@
</s3>
</s2>
<s2 title="The XMLSerializer/XMLDeserializer">
- <p>The caching if the sax events is implemented by two Avalon components:
+ <p>The caching of the sax events is implemented by two Avalon components:
The XMLSerializer and the XMLDeserializer. The XMLSerializer gets
sax events and creates an object which is used by the XMLDeserializer
to recreate these sax events.</p>
@@ -110,13 +115,90 @@
stream and creates sax events.</p>
</s3>
</s2>
+ <s2 title="The Event Cache">
+ <p>The event cache contains the cached event pipelines (or the
+ <code>CachedEventObject</code>). It is another Avalon component which
+ can be configured. It is possible to use the memory as a cache,
+ or the file system or a combination of both etc. This depends on
+ the used/configured event cache.
+ </p>
+ </s2>
</s1>
<s1 title="Caching of stream pipelines">
- <p>Forthcoming.</p>
+ <p>The algorithm used for caching depends on the configured stream pipeline.
+ For more information about configuration see the chapter below.</p>
+ <p>The following subchapters describe the available caching algorithms.</p>
+ <s2 title="The CachingStreamPipeline">
+ <p>The <code>CachingStreamPipeline</code> uses a very easy but effectiv approach
+ to cache the stream pipelines of a request: If the underlying
+ event stream and the serializer is cacheable the request is cached.
+ If a reader is used instead and it is cacheable, the response
+ is cached, too.</p>
+ <p>An event pipeline is cacheable if it implements the <code>CacheableEventPipeline</code>
+ interface. It generates a unique key for this event pipeline
+ and delivers the cache validity objects. The current CachingEventPipeline
+ for example is cacheable if all sitemap components are cacheable,
+ this includes the generator and all transformers. The generated key
+ is build upon the returned keys of the sitemap components and
+ the validity objects are the collected validity objects from the
+ sitemap components. If the response is cacheable the <code>CachingStreamPipeline</code>
+ informs the <code>CacheableEventPipeline</code> by calling the
+ method <code>setStreamPipelineCaches</code>. The event pipeline
+ can now decide if it also wants to cache the response thus nearly
+ duplicating the cached contents.</p>
+ <p>A serializer is cacheable if it implements the <code>Cacheable</code> interface.
+ In the case of a serializer the implementation is in most cases very
+ simple as a serializer often has no other input than the sax events. In
+ this case the key for this serializer can be a simple constant value
+ and the validity object is the <code>NOPCacheValidity</code>.</p>
+ <p>A reader is cacheable if it imimplements the <code>Cacheable</code>
+ interface.</p>
+ <p>When a response is cached all validity objects are stored together with
+ the cached response, which is actually a byte array, in the cache.
+ The <code>CachedStreamObject</code> encapsulates all this information.</p>
+ <p>When a new response is generated and the key is build, the caching
+ algorithm collects all uptodate cache validity objects. So if the
+ cached response is found in the cache these validity objects are compared.
+ If they are valid (or equal) the cached response is used and directly
+ returned. If they are not valid any more the cached response is removed
+ from the cache, the new response is generated and then stored together with
+ the new validity objects in the cache.</p>
+ </s2>
+ <s2 title="The Stream Cache">
+ <p>The stream cache contains the cached stream pipelines (or the
+ <code>CachedStreamObject</code>). It is another
+ Avalon component which can be configured. It is possible to use
+ the memory as a cache, or the file system or a combination of both
+ etc. This depends on the used/configured event cache.
+ </p>
+ </s2>
</s1>
<s1 title="Configuration">
- <p>Configuration is forthcoming</p>
- <s2 title="The XMLSerializer/XMLDeserializer">
+ <p>The caching of Cocoon 2 can be completely configured by different Avalon
+ components. This chapter describes which roles must/can be changed
+ to tune up your Cocoon 2 system.</p>
+ <s2 title="The Stream and the Event Pipeline">
+ <p>The stream and the event pipeline are represented by two Avalon
+ components which can be configured in the cocoon.xconf:</p>
+ <source>
+ <![CDATA[
+ <event-pipeline class="org.apache.cocoon.components.pipeline.CachingEventPipeline"/>
+
+ <stream-pipeline class="org.apache.cocoon.components.pipeline.CachingStreamPipeline"/>
+
+ ]]>
+ </source>
+ <p>If you want to completely turn off caching, use the following
+ definitions:</p>
+ <source>
+ <![CDATA[
+ <event-pipeline class="org.apache.cocoon.components.pipeline.NonCachingEventPipeline"/>
+
+ <stream-pipeline class="org.apache.cocoon.components.pipeline.NonCachingStreamPipeline"/>
+
+ ]]>
+ </source> </s2>
+ <s2 title="The XMLSerializer/XMLDeserializer">
<p>The XMLSerializer and XMLDeserialzer are two Avalon components which
can be configured in the cocoon.xconf:</p>
<source>
@@ -130,9 +212,26 @@
<p>You must assure that the correct (or matching) deserializer is
configured for the serializer.</p>
</s2>
+ <s2 title="Event Cache and Stream Cache">
+ <p>The EventCache and the StreamCache are two Avalon components which
+ can be configured in the cocoon.xconf:</p>
+ <source>
+ <![CDATA[
+ <event-cache class="org.apache.cocoon.caching.EventMemoryCache"/>
+
+ <stream-cache class="org.apache.cocoon.caching.StreamMemoryCache"/>
+
+ ]]>
+ </source> </s2>
</s1>
<s1 title="Java APIs">
- <p>Description of the interfaces is forthcoming</p>
+ <p>For more information on the java apis refer directly to the
+ javadocs of Cocoon2.</p>
+ <p>The most important packages are:</p>
+ <ol>
+ <li><code>org.apache.cocoon.caching</code>: This package declares all interfaces for caching.</li>
+ <li><code>org.apache.cocoon.components.pipeline</code>: The interfaces and implementations of the pipelines.</li>
+ </ol>
</s1>
<s1 title="Utility classes">
<s2 title="Hash Util">
----------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org