apache > cocoon
 
Font size:      

ImageReader in Cocoon (2.1 legacy document)

Warning
This document was copied as is from the Cocoon 2.1 documentation, but has not yet been fully reviewed or moved to its new home.

ImageReader

NAMEimage
WHATThe ImageReader component is used to serve binary image data in a sitemap pipeline.
TYPEReader, Sitemap Component
BLOCKCore
CLASSorg.apache.cocoon.reading.ImageReader
SINCECocoon 2.1
CACHEABLEyes

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 NameTypeComment
expiresTime in millisecondsThis 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.
widthImage width in pixelsThis 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.
heightImage height in pixelsThis 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-enlargingbooleanThis 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 "false". With this parameter set to "false", images will be reduced in size, but not enlarged. The default for this parameter is "true".
fit-uniformbooleanThis parameter is optional. When set to "true", it constrains the image size to the dimensions of the specified width and height, while preserving the original aspect ratio. The value of <allow-enlarging> is honored. If <allow-enlarging> is "true", then the image will be enlarged as much as possible while still fitting in the "box"; if <allow-enlarging> is "false," the image may be reduced to fit the box, but never enlarged. The default setting of <fit-uniform> is "false".
grayscalebooleanThis 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)float(Optional) Scale the RGB colour components by a multiplication factor.
offset(Red|Green|Blue)float(Optional) Offset the RGB colour components by an increment.

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

Comments

add your comments