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