apache > cocoon

- Home

# 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

## See also

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).