ExpiresCachingProcessingPipeline
Summary
No summary available. The summary needs to be defined using the @cocoon.sitemap.component.documentation annotation in the Java source file for this component.
Basic information
Component type | Pipe |
---|---|
Cocoon block | core |
Java class | org.apache.cocoon.components.pipeline.impl.ExpiresCachingProcessingPipeline |
Name in Sitemap | |
Cacheable |
Documentation
Intro
This pipeline implementation caches the complete content for a defined period of time (expires). You use this caching strategy, when you know your result is valid for example at least an hour. Since cocoon 2.1.9 (before this version, despite the fact that the ExpiresCachingProcessingPipeline only has to take its own cachekey and expiresValidity into account, it checked all cachekeys and validities of pipelines it used), this is by far the fastest caching strategy, because you define the exact cache key to be used by the expires pipeline AND you define how long it is valid after the first call: This means, and this only holds for the ExpiresCachingProcessingPipeline, that the validities and cache keys of other pipelines that it includes with map:part/map:generate won't have to evaluated.
Declaration
Make sure you declare the ExpiresCachingProcessingPipeline in your sitemap's component section in map:pipes:
<map:pipe name="expires" src="org.apache.cocoon.components.pipeline.impl.ExpiresCachingProcessingPipeline"> <parameter name="cache-expires" value="180"/> <!-- Expires in seconds --> </map:pipe>
The value can also be written like:
access plus 1 minutes access plus 1 hours access plus 1 month access plus 4 weeks access plus 30 days access plus 1 month 15 days 2 hours
The value of the parameter is in a format borrowed from the Apache HTTP module mod_expires.
Usage
In cocoon, you can define a different cache strategy for every pipeline. After adding the declaration above, you can use the "expires" pipeline:
<map:pipeline type="expires"> <map:match pattern="foo"> <map:generate src="bar.xml" type="jx"> <map:parameter name="time" value="{date:yyyyMMddHHmmss}"/> </map:generate> <map:serialize type="xml"/> </map:match> </map:pipeline>
If bar.xml would look like <time>${cocoon.parameters.time}</time>, and you would refresh it again and again, you would get the same output for 3 minutes (180 seconds from the declaration in map:components). After 3 minutes, it would result in a new output, again caching it for 3 minutes. The above map:pipeline is the most basic example.
If you want to have different cache-expires in different map:pipelines, then you add a map:parameter with name cache-expires directly under the map:pipeline of type expires:
<map:pipeline type="expires"> <map:parameter name="cache-expires" value="60"/> <map:match pattern="foo2"> <map:generate src="bar.xml" type="jx"> <map:parameter name="time" value="{date:yyyyMMddHHmmss}"/> </map:generate> <map:serialize type="xml"/> </map:match> </map:pipeline>
The match "foo2" will be cached for 1 minute.
With the example above, all urls "/foo", "/foo?bar=1", "foo?bar=1&foo=2" will be expired under the same cache key. So having the following sitemap block,
<map:pipeline type="expires"> <map:parameter name="cache-expires" value="60"/> <map:match pattern="foo2"> <map:generate src="bar.xml" type="jx"> <map:parameter name="time" value="{date:yyyyMMddHHmmss}"/> <map:parameter name="bar" value="{request-param:bar}"/> </map:generate> <map:serialize type="xml"/> </map:match> </map:pipeline>
and bar.xml <time>${cocoon.parameters.time}-${cocoon.parameters.bar}</time>, would have the same result for three minutes for every link above. This is because the cache-key of the expires pipeline, is by DEFAULT the sitemap uri! But, you can define how your cache-key is constructed for every the map:pipeline:
<map:pipeline type="expires"> <map:parameter name="cache-expires" value="60"/> <map:parameter name="cache-key" value="{0}"/> ....... </map:pipeline>
The above, is how it behaves by default, since {0} refers to the sitemap uri. But, you can also construct your cache-key like:
<map:pipeline type="expires" internal-only="false"> <map:parameter name="cache-expires" value="60"/> <map:parameter name="cache-key" value="{0}{request-param:bar}{session-attr:locale}"/> ....... </map:pipeline>
Now, your cache-key is different for different locale sessions and parameters bar.
Purging your cache
The last thing about this caching mechanism, is that you can you can use purge-cache parameter. This is particularly useful, when you want for example a very large cache-expires value, and purge the cache only when a specific request comes in. Then, for example, you could use
<map:pipeline type="expires" internal-only="false"> <map:parameter name="cache-expires" value="600000"/> <!--very long--> <map:parameter name="cache-key" value="{0}{request-param:bar}{session-attr:locale}"/> <map:parameter name="purge-cache" value="{request-param:purge}"/> ....... </map:pipeline>
Now, if a request comes in with a parameter purge=true, the specific cache related to the cache-key is purged, and the content is re-evaluated