ResourceReader in Cocoon

ResourceReader

NAME	resource
WHAT	The `ResourceReader` component is used to serve binary data in a sitemap pipeline.
TYPE	Reader, Sitemap Component
BLOCK	Core
CLASS	org.apache.cocoon.reading.ResourceReader
SINCE	Cocoon 2.0
CACHEABLE	yes

Description

The ResourceReader component is used to serve binary data in a sitemap pipeline.

Usage

Sitemap pipeline examples

The ResourceReader is used in a pipline as shown in the pipeline snippet below:

<map:match pattern="*.css">
  <map:read type="resource" 
    src="resources/styles/{1}.css" 
    mime-type="text/css">
    <!-- option sitemap parameters -->
    ...
  </map:read>
</map:match>

It is important to specify the mime-type attribute, as it is passed to the browser as the Content-Type in the HTTP response.

Sitemap component configuration example

A ResourceReader is declared in the sitemap readers section, as shown in the sitemap readers snippet below:

<map:readers default="resource">
  <map:reader name="resource" 
    src="org.apache.cocoon.reading.ResourceReader" 
    logger="sitemap.reader.resource" 
    pool-max="32"/>
    <!-- optional reader configuration -->
    ...
  </map:readers>
...

Configuration

The ResourceReader accepts the following configuration parameters:

Parametername	Type	Comment
expires	Time in milliseconds	This parameter is optional. When specified it determines how long in miliseconds the resources can be cached by any proxy or browser between Cocoon2 and the requesting visitor.
quick-modified-test	boolean	This parameter is optional. This boolean parameter controls the last modified test. If set to true (default is false), only the last modified of the current source is tested, but not if the same source is used as last time.
byte-ranges	boolean	This parameter is optional. This boolean parameter enables or disables support for the byte ranges. By default this parameter is set to true.
buffer-size	integer	This parameter is optional. It specifies the buffer/block size when reading from a resource. By default this parameter is set to 8192.

The following ResourceReader declaration snippet configures the default reader for having an expiration of 1 day (ie. 24 * 60 * 60 * 1000 ms = 86400000 ms)

<map:readers default="resource">
  <map:reader name="resource" 
    src="org.apache.cocoon.reading.ResourceReader" 
    logger="sitemap.reader.resource" 
    pool-max="32"/>
    <!-- optional reader configuration -->
    <parameter name="expires" value="86400000"/>
  </map:readers>
...

Setup

The ResourceReader accepts following sitemap setup parameters that override the configuration settings:

Parametername	Type	Comment
expires	Time in milliseconds	This parameter is optional. When specified it determines how long in miliseconds the resources can be cached by any proxy or browser between Cocoon2 and the requesting visitor.
quick-modified-test	boolean	This parameter is optional. This boolean parameter controls the last modified test. If set to true (default is false), only the last modified of the current source is tested, but not if the same source is used as last time.
byte-ranges	boolean	This parameter is optional. This boolean parameter enables or disables support for the byte ranges. By default this parameter is set to true.
buffer-size	integer	This parameter is optional. It specifies the buffer/block size when reading from a resource. By default this parameter is set to 8192.

The following ResourceReader declaration snippet parameterizes the default reader for having an expiration of 1 day (ie. 24 * 60 * 60 * 1000 ms = 86400000 ms)

  <map:read src="images/picture.gif"/>
    <map:parameter name="expires" value="86400000"/>
  </map:read>
...

Effect on Object Model and Sitemap Parameters

The ResourceReader does not change object model and sitemap parameters. It only access values for reading.

Bugs/Caveats

History

12-25-02: Initial document creation by Bernhard Huber
01-06-03: Added new parameters and byte range support, Torsten Curdt