Added: cocoon/site/site/2.1/userdocs/core/image-reader.html URL: http://svn.apache.org/viewcvs/cocoon/site/site/2.1/userdocs/core/image-reader.html?rev=345438&view=auto ============================================================================== --- cocoon/site/site/2.1/userdocs/core/image-reader.html (added) +++ cocoon/site/site/2.1/userdocs/core/image-reader.html Thu Nov 17 20:00:02 2005 @@ -0,0 +1,1637 @@ + + + + + + + +ImageReader in Cocoon + + + + + + + + + +
+ +
+apache > cocoon +
+ +
+ + + + + + + + + + + + +
+
+
+
+ +
+ + +
+ +
+ +   +
+ + + + + +
+

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

+
+ +
+
+ +
 
+
+ + + Propchange: cocoon/site/site/2.1/userdocs/core/image-reader.html ------------------------------------------------------------------------------ svn:eol-style = native