apache > cocoon

- Home

# ImageReader in Cocoon

## ImageReader

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

## Description

The `ImageReader` component is used to serve binary image data in a sitemap pipeline.

## Usage

### Sitemap pipeline examples

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

    <map:match pattern="*.jpg">
      <map:read type="image"
        src="resources/images/{1}.jpg"
        mime-type="image/jpeg">
        <!-- optional setup 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 `ImageReader` is declared in the sitemap readers section, as shown in the sitemap readers snippet below:

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

### Configuration

The `ImageReader` has no configuration options.

### Sitemap Parameters

The `ImageReader` accepts following sitemap setup parameters:

Parameter Name | 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.
width | Image width in pixels | This parameter is optional. When specified it determines the width of the binary image. If no height parameter is specified the aspect ratio of the image is kept.
height | Image height in pixels | This parameter is optional. When specified it determines the height of the binary image. If no width parameter is specified the aspect ratio of the image is kept.
allow-enlarging | Allow or prevent the enlarging of images | This parameter is optional. The `width` and `height` parameters allow an image to be resized. By default, if the image is smaller than the specified width and height, the image will be enlarged. In some circumstances, this behaviour is undesirable, and can be switched off by setting this parameter to "`no`". With this parameter set to "`no`", images will be reduced in size, but not enlarged. The default for this parameter is "`yes`".
grayscale | Render the colour as a scale of gray. | This parameter is optional. When specified and set to true it will cause each image pixel to be normalized. The default for this parameter is "`false`".
scale(Red|Green|Blue) | Scale the RGB colour components by a multiplication factor. | These parameters are optional. When specified it will cause the specified color component in the image to be multiplied by the specified floating point value.
offset(Red|Green|Blue) | Scale the RGB colour components by an increment. | These parameters are optional. When specified it will cause the specified color component in the image to be incremented by the specified floating point value.

The following pipeline snippet uses the `ImageReader` for serving images having an expiration time of 1 day (ie. 24 * 60 * 60 * 1000 ms = 86400000 ms), and scaling images to width 300 pixels.

    <map:match pattern="*.jpg">
      <map:reader type="image"
        <map:parameter name="expires" value="86400000"/>
        <map:parameter name="width" value="300"/>
      </map:reader>
    ...

### Effect on Object Model and Sitemap Parameters

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

## Bugs/Caveats

The `ImageReader` is able to transform JPEG images only. Nevertheless it can serve any image data in a non transforming mode.

The `ImageReader` does NOT support HTTP ranges, thus it sets `Accept-Ranges` to `none`.

The java Bug Id 4502892 (which is found in *all* JVM implementations from 1.2.x and 1.3.x on all OS!), `ImageReader` must buffer the JPEG generation to avoid that connection resetting by the peer (user pressing the stop button, for example) crashes the entire JVM. This is evidently fixed in Sun JVM 1.3.1_04 however our workaround remains for JVM less than 1.4

## History

12-25-02: Initial document creation by Bernhard Huber
01-06-03: Renamed the expire-time -> expires parameter, Fixed the statement about the byte range support, Torsten Curdt
03-07-03: Added allow-enlarging parameter, Upayavira

## 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).