ASF_20_SRC_AUTO/src/documentation/xdocs/userdocs/readers/image-reader.xml - cocoon - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">

 <document>
   <header>
     <title>ImageReader in Cocoon</title>
     <version>0.9</version>
     <type>Technical document</type>
     <authors>
       <person name="Bernhard Huber" email="huber@apache.org"/>
       <person name="Upayavira" email="upayavira@apache.org"/>
     </authors>
     <abstract>This document describes the ImageReader of Cocoon.</abstract>
   </header>
   <body>
     <s1 title="ImageReader">
       <table>
         <tr>
           <td>NAME</td><td>image</td>
         </tr>
         <tr>
           <td>WHAT</td><td>The <code>ImageReader</code> component is used
             to serve binary image data in a sitemap pipeline.
           </td>
         </tr>
         <tr>
           <td>TYPE</td><td>Reader, Sitemap Component</td>
         </tr>
         <tr>
           <td>BLOCK</td><td>Core</td>
         </tr>
         <tr>
           <td>CLASS</td><td>org.apache.cocoon.reading.ImageReader</td>
         </tr>
         <!--tr>
           <td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
         </tr-->
         <tr>
           <td>SINCE</td><td>Cocoon 2.1</td>
         </tr>
         <tr>
           <td>CACHEABLE</td><td>yes</td>
         </tr>
       </table>
     </s1>
     <s1 title="Description">
     <p>
       The <code>ImageReader</code> component is used to serve binary image data
       in a sitemap pipeline.
     </p>
     </s1>
     <s1 title="Usage">
       <p>
       </p>
       <s2 title="Sitemap pipeline examples">
         <p>
           The <code>ImageReader</code> is used in a pipline as shown in the
           pipeline snippet below:
         </p>
         <source><![CDATA[
 <map:match pattern="*.png">
   <map:read type="image"
     src="resources/styles/{1}.css"
     mime-type="image/jpeg">
     <!-- optional setup parameters -->
   </map:read>
 </map:match>
 ]]></source>
         <p>
           It is important to specify the <code>mime-type</code> attribute,
           as it is passed to the browser as the <code>Content-Type</code>
           in the <code>HTTP</code> response.
         </p>
       </s2>
       <s2 title="Sitemap component configuration example">
         <p>
           A <code>ImageReader</code> is declared in the sitemap readers
           section, as shown in the sitemap readers snippet below:
         </p>
         <source><![CDATA[
 <map:readers default="resource">
 ...
   <map:reader name="image"
     src="org.apache.cocoon.reading.ImageReader"
     logger="sitemap.reader.image"
     pool-max="32" pool-min="1" pool-grow="4"/>
     <!-- optional reader configuration -->
     ...
   </map:readers>
 ...
         ]]></source>
       </s2>
       <s2 title="Configuration">
         <p>
           The <code>ImageReader</code> has no configuration options.
         </p>
       </s2>
       <s2 title="Sitemap Parameters">
         <p>
           The <code>ImageReader</code> accepts following sitemap
           setup parameters
         </p>
         <table>
           <tr><th>Parameter Name</th><th>Type</th><th>Comment</th></tr>
           <tr><td>expires</td><td>Time in milliseconds</td>
             <td>
               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.
             </td>
           </tr>
           <tr><td>width</td><td>Image width in pixels</td>
             <td>
               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.
             </td>
           </tr>
           <tr><td>height</td><td>Image height in pixels</td>
             <td>
               This parameter is optional. When specified it determines the width
               of the binary image.
               If no width parameter is specified the aspect ratio
               of the image is kept.
             </td>
           </tr>
           <tr><td>allow-enlarging</td><td>Allow or prevent the enlarging of images</td>
             <td>
               This parameter is optional. The <code>width</code> and <code>height</code> 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 <code>no</code>. With this parameter set to <code>no</code>, images will
               be reduced in size, but not enlarged. The default for this parameter is
               <code>yes</code>.
             </td>
           </tr>
         </table>
         <p>
           The following pipeline snippet
           uses the <code>ImageReader</code> 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.
         </p>
         <source><![CDATA[
 <map:match pattern="*.jpg">
   <map:reader type="image"
     <map:parameter name="expires" value="86400000"/>
     <map:parameter name="width" value="300"/>
   </map:reader>
 ...
         ]]></source>
       </s2>
       <s2 title="Effect on Object Model and Sitemap Parameters">
         <p>
           The <code>ImageReader</code> does not change object model and sitemap parameters.
           It only access parameter values for reading.
         </p>
       </s2>
     </s1>
     <s1 title="Bugs/Caveats">
       <p>
         The <code>ImageReader</code> is able to transform
         <em>JPEG</em> images only.
         Nevertheless it can serve any image data in a non transforming mode.
       </p>
       <p>
         The <code>ImageReader</code> does NOT support HTTP ranges, thus
         it sets <code>Accept-Ranges</code> to <code>none</code>.
       </p>
       <p>
         The java Bug Id 4502892 (which is found in *all* JVM implementations from
         1.2.x and 1.3.x on all OS!), <code>ImageReader</code> must buffer
         the JPEG generation to avoid that connection resetting by the peer
         (user pressing the stop button, for example) crashes the entire JVM.
       </p>
     </s1>
     <s1 title="History">
       <p>
         12-25-02: Initial document creation by Bernhard Huber
         <br/>
         01-06-03: Renamed the expire-time -> expires parameter,
                   Fixed the statement about the byte range support, Torsten Curdt
         <br/>
         03-07-03: Added allow-enlarging parameter, Upayavira
       </p>
     </s1>
     <s1 title="Copyright">
       <p>
         Copyright (C) 1999-2003 The Apache Software Foundation. All rights reserved.
       </p>
     </s1>
     <s1 title="See also">
       <p>
         <!-- Links to related components pages -->
       </p>
     </s1>
   </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">

	<document>
	<header>
	<title>ImageReader in Cocoon</title>
	<version>0.9</version>
	<type>Technical document</type>
	<authors>
	<person name="Bernhard Huber" email="huber@apache.org"/>
	<person name="Upayavira" email="upayavira@apache.org"/>
	</authors>
	<abstract>This document describes the ImageReader of Cocoon.</abstract>
	</header>
	<body>
	<s1 title="ImageReader">
	<table>
	<tr>
	<td>NAME</td><td>image</td>
	</tr>
	<tr>
	<td>WHAT</td><td>The <code>ImageReader</code> component is used
	to serve binary image data in a sitemap pipeline.
	</td>
	</tr>
	<tr>
	<td>TYPE</td><td>Reader, Sitemap Component</td>
	</tr>
	<tr>
	<td>BLOCK</td><td>Core</td>
	</tr>
	<tr>
	<td>CLASS</td><td>org.apache.cocoon.reading.ImageReader</td>
	</tr>
	<!--tr>
	<td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
	</tr-->
	<tr>
	<td>SINCE</td><td>Cocoon 2.1</td>
	</tr>
	<tr>
	<td>CACHEABLE</td><td>yes</td>
	</tr>
	</table>
	</s1>
	<s1 title="Description">
	<p>
	The <code>ImageReader</code> component is used to serve binary image data
	in a sitemap pipeline.
	</p>
	</s1>
	<s1 title="Usage">
	<p>
	</p>
	<s2 title="Sitemap pipeline examples">
	<p>
	The <code>ImageReader</code> is used in a pipline as shown in the
	pipeline snippet below:
	</p>
	<source><![CDATA[
	<map:match pattern="*.png">
	<map:read type="image"
	src="resources/styles/{1}.css"
	mime-type="image/jpeg">
	<!-- optional setup parameters -->
	</map:read>
	</map:match>
	]]></source>
	<p>
	It is important to specify the <code>mime-type</code> attribute,
	as it is passed to the browser as the <code>Content-Type</code>
	in the <code>HTTP</code> response.
	</p>
	</s2>
	<s2 title="Sitemap component configuration example">
	<p>
	A <code>ImageReader</code> is declared in the sitemap readers
	section, as shown in the sitemap readers snippet below:
	</p>
	<source><![CDATA[
	<map:readers default="resource">
	...
	<map:reader name="image"
	src="org.apache.cocoon.reading.ImageReader"
	logger="sitemap.reader.image"
	pool-max="32" pool-min="1" pool-grow="4"/>
	<!-- optional reader configuration -->
	...
	</map:readers>
	...
	]]></source>
	</s2>
	<s2 title="Configuration">
	<p>
	The <code>ImageReader</code> has no configuration options.
	</p>
	</s2>
	<s2 title="Sitemap Parameters">
	<p>
	The <code>ImageReader</code> accepts following sitemap
	setup parameters
	</p>
	<table>
	<tr><th>Parameter Name</th><th>Type</th><th>Comment</th></tr>
	<tr><td>expires</td><td>Time in milliseconds</td>
	<td>
	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.
	</td>
	</tr>
	<tr><td>width</td><td>Image width in pixels</td>
	<td>
	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.
	</td>
	</tr>
	<tr><td>height</td><td>Image height in pixels</td>
	<td>
	This parameter is optional. When specified it determines the width
	of the binary image.
	If no width parameter is specified the aspect ratio
	of the image is kept.
	</td>
	</tr>
	<tr><td>allow-enlarging</td><td>Allow or prevent the enlarging of images</td>
	<td>
	This parameter is optional. The <code>width</code> and <code>height</code> 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 <code>no</code>. With this parameter set to <code>no</code>, images will
	be reduced in size, but not enlarged. The default for this parameter is
	<code>yes</code>.
	</td>
	</tr>
	</table>
	<p>
	The following pipeline snippet
	uses the <code>ImageReader</code> 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.
	</p>
	<source><![CDATA[
	<map:match pattern="*.jpg">
	<map:reader type="image"
	<map:parameter name="expires" value="86400000"/>
	<map:parameter name="width" value="300"/>
	</map:reader>
	...
	]]></source>
	</s2>
	<s2 title="Effect on Object Model and Sitemap Parameters">
	<p>
	The <code>ImageReader</code> does not change object model and sitemap parameters.
	It only access parameter values for reading.
	</p>
	</s2>
	</s1>
	<s1 title="Bugs/Caveats">
	<p>
	The <code>ImageReader</code> is able to transform
	<em>JPEG</em> images only.
	Nevertheless it can serve any image data in a non transforming mode.
	</p>
	<p>
	The <code>ImageReader</code> does NOT support HTTP ranges, thus
	it sets <code>Accept-Ranges</code> to <code>none</code>.
	</p>
	<p>
	The java Bug Id 4502892 (which is found in all JVM implementations from
	1.2.x and 1.3.x on all OS!), <code>ImageReader</code> must buffer
	the JPEG generation to avoid that connection resetting by the peer
	(user pressing the stop button, for example) crashes the entire JVM.
	</p>
	</s1>
	<s1 title="History">
	<p>
	12-25-02: Initial document creation by Bernhard Huber
	<br/>
	01-06-03: Renamed the expire-time -> expires parameter,
	Fixed the statement about the byte range support, Torsten Curdt
	<br/>
	03-07-03: Added allow-enlarging parameter, Upayavira
	</p>
	</s1>
	<s1 title="Copyright">
	<p>
	Copyright (C) 1999-2003 The Apache Software Foundation. All rights reserved.
	</p>
	</s1>
	<s1 title="See also">
	<p>
	<!-- Links to related components pages -->
	</p>
	</s1>
	</body>
	</document>