ImageReader in Cocoon (2.1 legacy document)
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 | boolean | 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 "false". With this parameter set to "false", images will be reduced in size, but not enlarged. The default for this parameter is "true". |
fit-uniform | boolean | This 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". |
grayscale | boolean | 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) | 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