Apache » Cocoon »

  Cocoon Core
      2.2
   homepage

Cocoon Core 2.2

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 typePipe
Cocoon blockcore
Java classorg.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