Return-Path: 
 <cocoon-cvs-return-2489-apmail-xml-cocoon-cvs-archive=xml.apache.org@xml.apache.org>
Delivered-To: apmail-xml-cocoon-cvs-archive@xml.apache.org
Received: (qmail 43792 invoked by uid 500); 2 Jul 2001 09:03:42 -0000
Mailing-List: contact cocoon-cvs-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cocoon-dev@xml.apache.org
list-help: <mailto:cocoon-cvs-help@xml.apache.org>
list-unsubscribe: <mailto:cocoon-cvs-unsubscribe@xml.apache.org>
list-post: <mailto:cocoon-cvs@xml.apache.org>
Delivered-To: mailing list cocoon-cvs@xml.apache.org
Received: (qmail 43776 invoked by uid 500); 2 Jul 2001 09:03:39 -0000
Delivered-To: apmail-xml-cocoon2-cvs@apache.org
Date: 2 Jul 2001 09:03:38 -0000
Message-ID: <20010702090338.43772.qmail@apache.org>
From: cziegeler@apache.org
To: xml-cocoon2-cvs@apache.org
Subject: 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