You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by hu...@apache.org on 2002/12/25 13:56:07 UTC
cvs commit: xml-cocoon2/src/documentation/xdocs/userdocs/readers axisrpc-reader.xml book.xml byterangeresource-reader.xml database-reader.xml directoryziparchiver-reader.xml image-reader.xml jsp-reader.xml readers.xml resource-reader.xml template-reader.xml
huber 2002/12/25 04:56:07
Added: src/documentation/xdocs/userdocs/readers axisrpc-reader.xml
book.xml byterangeresource-reader.xml
database-reader.xml directoryziparchiver-reader.xml
image-reader.xml jsp-reader.xml readers.xml
resource-reader.xml template-reader.xml
Log:
intial version of reader userdocs
Revision Changes Path
1.1 xml-cocoon2/src/documentation/xdocs/userdocs/readers/axisrpc-reader.xml
Index: axisrpc-reader.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Template-Reader in Cocoon</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Bernhard Huber" email="huber@apache.org"/>
</authors>
<abstract>This document describes the AxisRPCReader of Cocoon.</abstract>
</header>
<body>
<s1 title="AxisRPCReader">
<table>
<tr>
<td>NAME</td><td>template</td>
</tr>
<tr>
<td>WHAT</td><td>The <code>AxisRPCReader</code> allows to serve SOAP requests from
your Cocoon application.
</td>
</tr>
<tr>
<td>TYPE</td><td>Reader, Sitemap Component</td>
</tr>
<tr>
<!-- choose Core, the block name, or Scratchpad
depending on where AxisRPCReader sources live
-->
<td>BLOCK</td><td>Scratchpad</td>
</tr>
<tr>
<td>CLASS</td><td>org.apache.cocoon.reading.AxisRPCReader</td>
</tr>
<!-- uncomment folling tr iff AxisRPCReader is deprecated -->
<!--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>no</td>
</tr>
</table>
</s1>
<s1 title="Description">
<p>
A general description of AxisRPCReader
</p>
</s1>
<s1 title="Usage">
<p>
A usage scenario of AxisRPCReader
</p>
<s2 title="Sitemap pipeline examples">
<p></p>
<source><![CDATA[
<map:match pattern="rpcrouter">
<map:read type="soap-rpc" mime-type="text/xml"/>
</map:match>
]]></source>
</s2>
<s2 title="Sitemap component configuration example">
<p></p>
<source><![CDATA[
<map:readers...
<map:reader name="soap-rpc"
src="org.apache.cocoon.reading.AxisRPCReader"
logger="sitemap.reader.soap-rpc"
>
<!-- optional reader configuration -->
...
</map:readers>
...
]]></source>
</s2>
<s2 title="Configuration">
<p>
Explain the sitemap reader configuration, options when declaring template reader
</p>
</s2>
<s2 title="Setup">
<p>
Explain the sitemap reader setup, ie options when using template reader
</p>
</s2>
<s2 title="Effect on Object Model and Sitemap Parameters">
<p>
</p>
</s2>
</s1>
<s1 title="Bugs/Caveats">
<p>
As a prerequisite for AxisRPCReader to work properly, the Avalon
component SoapServer has to be configured in
the <code>cocoon.xconf</code> file.
</p>
</s1>
<s1 title="History">
<p>
12-25-02: initial creation by Bernhard Huber
</p>
</s1>
<s1 title="Copyright">
<p>
Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
</p>
</s1>
<s1 title="See also">
<p>
Links to related components pages.
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/userdocs/readers/book.xml
Index: book.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../../dtd/book-cocoon-v10.dtd">
<book software="Apache Cocoon" title="Apache Cocoon Generators" copyright="@year@ The Apache Software Foundation">
<menu label="Navigation">
<menu-item label="Main" href="../../index.html"/>
<menu-item label="User Documentation" href="../index.html"/>
</menu>
<menu label="Readers">
<menu-item label="Overview" href="readers.html"/>
</menu>
<menu label="Default">
<menu-item label="Resource Reader" href="resource-reader.html"/>
</menu>
<menu label="Core">
</menu>
<menu label="Optional">
<menu-item label="Database Reader" href="database-reader.html"/>
<menu-item label="JSP Reader" href="jsp-reader.html"/>
</menu>
<menu label="Scratchpad">
<menu-item label="AxisRPC Reader" href="axisrpc-reader.html"/>
<menu-item label="Byte Range Resource Reader" href="byterangeresource-reader.html"/>
<menu-item label="Directory ZIP Archiver" href="directoryziparchiver-reader.html"/>
<menu-item label="Image Reader" href="image-reader.html"/>
</menu>
</book>
1.1 xml-cocoon2/src/documentation/xdocs/userdocs/readers/byterangeresource-reader.xml
Index: byterangeresource-reader.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>ByteRangeResourceReader in Cocoon</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Bernhard Huber" email="huber@apache.org"/>
</authors>
<abstract>This document describes the ByteRangeResourceReader of Cocoon.</abstract>
</header>
<body>
<s1 title="ByteRangeResourceReader">
<table>
<tr>
<td>NAME</td><td>resource</td>
</tr>
<tr>
<td>WHAT</td><td>The <code>ByteRangeResourceReader</code> component is used
to serve binary data in a sitemap pipeline.
</td>
</tr>
<tr>
<td>TYPE</td><td>Reader, Sitemap Component</td>
</tr>
<tr>
<td>BLOCK</td><td>Scratchpad</td>
</tr>
<tr>
<td>CLASS</td><td>org.apache.cocoon.reading.ByteRangeResourceReader</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>ByteRangeResourceReader</code> component is used to serve binary data
in a sitemap pipeline.
</p>
</s1>
<s1 title="Usage">
<p>
</p>
<s2 title="Sitemap pipeline examples">
<p>
The <code>ByteRangeResourceReader</code> is used in a pipline as shown in the
pipeline snippet below:
</p>
<source><![CDATA[
<map:match pattern="*.css">
<map:read type="byterange-resource"
src="resources/styles/{1}.css"
mime-type="text/css">
<!-- option sitemap 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>ByteRangeResourceReader</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="byterange-resource"
src="org.apache.cocoon.reading.ByteRangeResourceReader"
logger="sitemap.reader.byterang-resource"
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="Setup">
<p>
The <code>ByteRangeResourceReader</code> accepts following sitemap
setup parameters
</p>
<table>
<tr><th>Parametername</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>quick-modified-test</td><td>boolean</td>
<td>
This parameter is optional. This boolean parameter controlls the
last modified test. If set to true (default is false), only the
last modified of the current source is tested, but not if the
same source is used as last time.
</td>
</tr>
</table>
<p>
The following <code>ByteRangeResourceReader</code> declaration snippet
configures the default reader for having an expiration of
1 day (ie. 24 * 60 * 60 * 1000 ms = 86400000 ms)
</p>
<source><![CDATA[
<map:readers default="byterange-resource">
<map:reader name="byterange-resource"
src="org.apache.cocoon.reading.ByteRangeResourceReader"
logger="sitemap.reader.resource"
pool-max="32" pool-min="1" pool-grow="4"/>
<!-- optional reader configuration -->
<map:parameter name="expires" value="86400000"/>
</map:readers>
...
]]></source>
</s2>
<s2 title="Effect on Object Model and Sitemap Parameters">
<p>
The <code>ByteRangeResourceReader</code> does not change object model and sitemap parameters.
It only access values for reading.
</p>
</s2>
</s1>
<s1 title="Bugs/Caveats">
<p>
The <code>ByteRangeResourceReader</code> does support HTTP ranges.
</p>
</s1>
<s1 title="History">
<p>
12-25-02: Initial document creation by Bernhard Huber
</p>
</s1>
<s1 title="Copyright">
<p>
Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
</p>
</s1>
<s1 title="See also">
<p>
<!-- Links to related components pages -->
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/userdocs/readers/database-reader.xml
Index: database-reader.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>DatabaseReader</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Bernhard Huber" email="huber@apache.org"/>
</authors>
<abstract>This document describes the xml serializer of Cocoon.</abstract>
</header>
<body>
<s1 title="DatabaseReader">
<table>
<tr>
<td>NAME</td><td>databasereader</td>
</tr>
<tr>
<td>WHAT</td><td>The <code>DatabaseReader</code> component is used
to serve data from a database
</td>
</tr>
<tr>
<td>TYPE</td><td>Reader, Sitemap Component</td>
</tr>
<tr>
<td>BLOCK</td><td>Database</td>
</tr>
<tr>
<td>CLASS</td><td>org.apache.cocoon.reading.DatabaseReader</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>
This Reader pulls a resource from a database. It is configured with
the Connection to use, parameters specify the table and column
to pull the image from, and source specifies the source key information.
</p>
</s1>
<s1 title="Usage">
<p>
</p>
<s2 title="Sitemap pipeline examples">
<p>
The following pipeline snippet uses a <code>Database Reader</code>
for serving <em>PNG</em> images from a database.
</p>
<source><![CDATA[
<map:match pattern="images/*.png">
<map:read type="databasereader"
src="{1}"
mime-type="image/png">
<!-- option sitemap parameters -->
<map:parameter name="table" value="images"/>
<map:parameter name="image" value="image"/>
<map:parameter name="key" value="name"/>
<map:parameter name="where" value="publishing = 1"/>
<map:parameter name="order-by" value="created"/>
<map:parameter name="last-modified" value="last-modified"/>
</map:read>
</map:match>
]]></source>
<p>
The snippet above make following assumption about the database
</p>
<ul>
<li>A database table <code>images</code> holds the <em>PNG</em> image data.</li>
<li>The database table has <code>image</code> column storing the image data as <code>BLOB</code>.
</li>
<li>The database table has <code>key</code> column which must match the value of
of <code>{1}</code>.
</li>
<li>The database table has <code>publishing</code> column indicating by value <code>1</code>
that the image data is allowed to get published.
</li>
<li>The database table has <code>created</code> column, indicating the creation date of
the image data, and used if the <code>key</code> is not a primary key, serving
images in a LIFO fashion.
</li>
<li>The database table has <code>last-modified</code> column of type <code>TIMESTAMP</code>
indicating the last modification date of the image data.
</li>
</ul>
</s2>
<s2 title="Sitemap component configuration example">
<p></p>
<source><![CDATA[
<map:readers...
<map:reader name="databasereader"
src="org.apache.cocoon.reading.DatabaseReader"
logger="sitemap.reader.databasereader"
pool-max="32" pool-min="1" pool-grow="4"/>
<!-- optional reader configuration -->
...
</map:readers>
...
]]></source>
</s2>
<s2 title="Configuration">
<p>
In the <code>Database Reader</code> declaration section following configuration
options are available
</p>
<table>
<tr><th>Configurationname</th><th>Type</th><th>Comment</th></tr>
<tr><td>use-connection</td><td>Data source name</td>
<td>The name of a database selector, configured in the
<code>cocoon.xconf</code> file.
</td>
</tr>
<tr><td>invalidate</td><td> never | always </td>
<td>
This option configures the caching behaviour if lastModifed
has value of <code>-1</code>.
</td>
</tr>
</table>
</s2>
<s2 title="Setup">
<p>
The <code>DatabaseReader</code> accepts following setup parameters
</p>
<table>
<tr><th>Parametername</th><th>Type</th><th>Comment</th></tr>
<tr><td>table</td><td>database table name</td>
<td>The database table name</td>
</tr>
<tr><td>image</td><td>database column name</td>
<td>The column name of the image data</td>
</tr>
<tr><td>key</td><td>database key column name</td>
<td>The key column name of the image data matching the src attribute of
the <map:read> sitemap usage.
</td>
</tr>
<tr><td>where</td><td>database where expression</td>
<td>Optional parameter specifying SQL where expression.</td>
</tr>
<tr><td>order-by</td><td>database order-by expression</td>
<td>Optional parameter specifying an SQL order-by expression.
</td>
</tr>
<tr><td>last-modified</td><td>timestamp column name</td>
<td>Optional parameter a <code>TIMESTAMP</code> column name, added
to the <code>SELECT</code> clause of the SQL query.
</td>
</tr>
<tr><td>content-type</td><td>database column name</td>
<td>Optional parameter a column name, if specified the column
value overrides the <code>mime-type</code> attribute of the
<map:read> sitemap usage.
</td>
</tr>
</table>
<p>
The key value is derived from the <code>src</code> attribute
of the <code>Database Reader</code> usage..
</p>
<p>
The <code>Database Reader</code> builds internally following SQL query:
</p>
<source><![CDATA[
SELECT {image} [, last-modified] [, {order-by-column} ] from {table}
WHERE {key} = {src} [ AND {where} ]
[ORDER BY {order-by}]
]]></source>
</s2>
<s2 title="Effect on Object Model and Sitemap Parameters">
<p>
</p>
</s2>
</s1>
<s1 title="Bugs/Caveats">
<p>
The <code>Database Reader</code> needs a datasource name, it is referenced
by the configuration element <code>use-connection</code>. The datasource name
has to be configured in the Cocoon database configuration <code>cocoon.xconf</code>.
</p>
<p>
If the parameter <code>last-modified</code> ends with <code>" DESC"</code> this
suffix is truncated as it is appended to the SQL clause, noted as {order-by-column}
in the SQL query snippet above.
</p>
</s1>
<s1 title="History">
<p>
12-25-02: created initial version by Bernhard Huber
</p>
</s1>
<s1 title="Copyright">
<p>
Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
</p>
</s1>
<s1 title="See also">
<p>
<!-- Links to related components pages -->
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/userdocs/readers/directoryziparchiver-reader.xml
Index: directoryziparchiver-reader.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>DirectoryZipArchiver</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Bernhard Huber" email="huber@apache.org"/>
</authors>
<abstract>This document describes the xml serializer of Cocoon.</abstract>
</header>
<body>
<s1 title="DirectoryZipArchiver">
<table>
<tr>
<td>NAME</td><td>resource</td>
</tr>
<tr>
<td>WHAT</td><td>The <code>DirectoryZipArchiver</code>
The <code>DirectoryZipArchiver</code> component creates a compressed zip
archive of directory files on the fly.
</td>
</tr>
<tr>
<td>TYPE</td><td>Reader, Sitemap Component</td>
</tr>
<tr>
<td>BLOCK</td><td>Scratchpad</td>
</tr>
<tr>
<td>CLASS</td><td>org.apache.cocoon.reading.DirectoryZipArchiver</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>no</td>
</tr>
</table>
</s1>
<s1 title="Description">
</s1>
<s1 title="Usage">
<p>
</p>
<s2 title="Sitemap pipeline examples">
<p></p>
</s2>
<s2 title="Sitemap component configuration example">
<p></p>
</s2>
<s2 title="Configuration">
<p>
</p>
</s2>
<s2 title="Setup">
<p></p>
</s2>
<s2 title="Effect on Object Model and Sitemap Parameters">
<p></p>
</s2>
</s1>
<s1 title="Bugs/Caveats">
<p></p>
</s1>
<s1 title="History">
<p>
MM-DD-YY: comment
</p>
</s1>
<s1 title="Copyright">
<p>
Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
</p>
</s1>
<s1 title="See also">
<p>
<!-- Links to related components pages -->
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/userdocs/readers/image-reader.xml
Index: image-reader.xml
===================================================================
<?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"/>
</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>Scratchpad</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>Parametername</th><th>Type</th><th>Comment</th></tr>
<tr><td>expire-time</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 ascpect 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 ascpect ratio
of the image is kept.
</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="expire-time" 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 support HTTP ranges, thus
it sets <code>Accept-Ranges</code> to <code>bytes</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
</p>
</s1>
<s1 title="Copyright">
<p>
Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
</p>
</s1>
<s1 title="See also">
<p>
<!-- Links to related components pages -->
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/userdocs/readers/jsp-reader.xml
Index: jsp-reader.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>XML Serializer</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Bernhard Huber" email="huber@apache.org"/>
</authors>
<abstract>This document describes the xml serializer of Cocoon.</abstract>
</header>
<body>
<s1 title="JSPReader">
<table>
<tr>
<td>NAME</td><td>jsp</td>
</tr>
<tr>
<td>WHAT</td><td>The <code>JSPReader</code> component is used to serve JSP page output data
in a sitemap pipeline.
</td>
</tr>
<tr>
<td>TYPE</td><td>Reader, Sitemap Component</td>
</tr>
<tr>
<td>BLOCK</td><td>Jsp</td>
</tr>
<tr>
<td>CLASS</td><td>org.apache.cocoon.reading.JSPReader</td>
</tr>
<!--tr>
<td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
</tr-->
<tr>
<td>SINCE</td><td>Cocoon 2.0</td>
</tr>
<tr>
<td>CACHEABLE</td><td>yes</td>
</tr>
</table>
</s1>
<s1 title="Description">
<p>
The <code>JSPReader</code> forwards requests to a <em>JSP</em> engine, and
passing the <em>JSP</em> response immediatly as is.
</p>
</s1>
<s1 title="Usage">
<p>
The <code>JSPReader</code> is useful iff you want to serve the <em>JSP</em>
response without any further Cocoon processing steps.
</p>
<s2 title="Sitemap pipeline examples">
<p>
The following sitemap snippet uses the <code>JSPReader</code> to feed
<code>htm</code> requests by <em>JSP</em> files.
</p>
<source><![CDATA[
...
<map:match pattern="*.htm">
<map:read type="jsp" src="{1}.jsp" mime-type="text/html" />
</map:match>
...
]]></source>
</s2>
<s2 title="Sitemap component configuration example">
<p></p>
<source><![CDATA[
<map:readers...
<map:reader name="jsp"
src="org.apache.cocoon.reading.JSPReader"
logger="sitemap.reader.jsp"
/>
...
]]></source>
</s2>
<s2 title="Configuration">
<p>
The <code>JSP Reader</code> has no configuration options.
</p>
</s2>
<s2 title="Setup">
<p>
The <code>JSP Reader</code> has no setup options.
</p>
</s2>
<s2 title="Effect on Object Model and Sitemap Parameters">
<p>
</p>
</s2>
</s1>
<s1 title="Bugs/Caveats">
<p>
The <code>JSP Reader</code> depends on the accessibilty of a
<code>JSP</code> engine from within the Cocoon servlet.
A <em>JSP</em> must be properly configured for using the
<code>JSP Reader</code>.
</p>
</s1>
<s1 title="History">
<p>
12-25-02: created initial version by Bernhard Huber
</p>
</s1>
<s1 title="Copyright">
<p>
Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
</p>
</s1>
<s1 title="See also">
<p>
Feeding <em>JSP</em> and passing the content into further Cocoon processing
the <em>JSPGenerator</em> is appropriate for this task.
</p>
<p>
Moreover setting up a preprocessing <em>Servlet Filter</em> would be the most
general solution to feeding <em>JSP</em> content.
</p>
<!-- Links to related components pages -->
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/userdocs/readers/readers.xml
Index: readers.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Readers in Cocoon</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
<person name="Bernhard Huber" email="huber@apache.org"/>
</authors>
<abstract>This document describes all of the available readers of Cocoon.</abstract>
</header>
<body>
<s1 title="Goal">
<p>
This document lists all of the available readers of Apache Cocoon and
describes their purpose.
</p>
</s1>
<s1 title="Overview">
<p>
A reader is the starting, and end point of an xml pipeline.
It collapses the features of a generator, transformer, and serializer.
Readers are useful for delivering binary content like images; more
general readers deliver content as-is.
</p>
<p>
In the sitemap file, each reader has a unique name which is mapped
to a java class.
One reader name must be declared as the default reader.
Each reader may have additional configuration information specified in
child elements.
</p>
<p>
For conceptual information on readers see the user's guide document
<link href="../concepts/sitemap.html">The Sitemap</link>.
</p>
</s1>
<s1 title="The Readers in Apache Cocoon">
<ul>
<li><link href="resource-reader.html">Resource Reader</link> (The default reader)</li>
<li><link href="database-reader.html">Database Reader</link></li>
<li><link href="jsp-reader.html">JSP Reader</link></li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/userdocs/readers/resource-reader.xml
Index: resource-reader.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>ResourceReader in Cocoon</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Bernhard Huber" email="huber@apache.org"/>
</authors>
<abstract>This document describes the ResourceReader of Cocoon.</abstract>
</header>
<body>
<s1 title="ResourceReader">
<table>
<tr>
<td>NAME</td><td>resource</td>
</tr>
<tr>
<td>WHAT</td><td>The <code>ResourceReader</code> component is used
to serve binary 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.ResourceReader</td>
</tr>
<!--tr>
<td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
</tr-->
<tr>
<td>SINCE</td><td>Cocoon 2.0</td>
</tr>
<tr>
<td>CACHEABLE</td><td>yes</td>
</tr>
</table>
</s1>
<s1 title="Description">
<p>
The <code>ResourceReader</code> component is used to serve binary data
in a sitemap pipeline.
</p>
</s1>
<s1 title="Usage">
<p>
</p>
<s2 title="Sitemap pipeline examples">
<p>
The <code>ResourceReader</code> is used in a pipline as shown in the
pipeline snippet below:
</p>
<source><![CDATA[
<map:match pattern="*.css">
<map:read type="resource"
src="resources/styles/{1}.css"
mime-type="text/css">
<!-- option sitemap 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>ResourceReader</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="resource"
src="org.apache.cocoon.reading.ResourceReader"
logger="sitemap.reader.resource"
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="Setup">
<p>
The <code>ResourceReader</code> accepts following sitemap
setup parameters
</p>
<table>
<tr><th>Parametername</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>quick-modified-test</td><td>boolean</td>
<td>
This parameter is optional. This boolean parameter controlls the
last modified test. If set to true (default is false), only the
last modified of the current source is tested, but not if the
same source is used as last time.
</td>
</tr>
</table>
<p>
The following <code>ResourceReader</code> declaration snippet
configures the default reader for having an expiration of
1 day (ie. 24 * 60 * 60 * 1000 ms = 86400000 ms)
</p>
<source><![CDATA[
<map:readers default="resource">
<map:reader name="resource"
src="org.apache.cocoon.reading.ResourceReader"
logger="sitemap.reader.resource"
pool-max="32" pool-min="1" pool-grow="4"/>
<!-- optional reader configuration -->
<map:parameter name="expires" value="86400000"/>
</map:readers>
...
]]></source>
</s2>
<s2 title="Effect on Object Model and Sitemap Parameters">
<p>
The <code>ResourceReader</code> does not change object model and sitemap parameters.
It only access values for reading.
</p>
</s2>
</s1>
<s1 title="Bugs/Caveats">
<p>
The <code>ResourceReader</code> does not support HTTP ranges, thus
it sets <code>Accept-Ranges</code> to <code>none</code>.
</p>
</s1>
<s1 title="History">
<p>
12-25-02: Initial document creation by Bernhard Huber
</p>
</s1>
<s1 title="Copyright">
<p>
Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
</p>
</s1>
<s1 title="See also">
<p>
<!-- Links to related components pages -->
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/userdocs/readers/template-reader.xml
Index: template-reader.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Template-Reader in Cocoon</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Your Name" email="your-email"/>
</authors>
<abstract>This document describes the TemplateReader of Cocoon.</abstract>
</header>
<body>
<s1 title="TemplateReader">
<table>
<tr>
<td>NAME</td><td>template</td>
</tr>
<tr>
<td>WHAT</td><td>The <code>TemplateReader</code> component is used
to serve data in a sitemap pipeline.
</td>
</tr>
<tr>
<td>TYPE</td><td>Reader, Sitemap Component</td>
</tr>
<tr>
<!-- choose Core, the block name, or Scratchpad
depending on where TemplateReader sources live
-->
<td>BLOCK</td><td>Core/Block-Name/Scratchpad</td>
</tr>
<tr>
<td>CLASS</td><td>org.apache.cocoon.reading.TemplateReader</td>
</tr>
<!-- uncomment folling tr iff TemplateReader is deprecated -->
<!--tr>
<td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
</tr-->
<tr>
<td>SINCE</td><td>Cocoon X.Y</td>
</tr>
<tr>
<td>CACHEABLE</td><td>yes</td>
</tr>
</table>
</s1>
<s1 title="Description">
<p>
A general description of TemplateReader
</p>
</s1>
<s1 title="Usage">
<p>
A usage scenario of TemplateReader
</p>
<s2 title="Sitemap pipeline examples">
<p></p>
<source><![CDATA[
<map:match pattern="*.xyz">
<map:read type="template"
src="{1}"
mime-type="type/sub-type">
<!-- option sitemap parameters -->
</map:read>
</map:match>
]]></source>
</s2>
<s2 title="Sitemap component configuration example">
<p></p>
<source><![CDATA[
<map:readers...
<map:reader name="template"
src="org.apache.cocoon.reading.TemplateReader"
logger="sitemap.reader.template"
pool-max="32" pool-min="1" pool-grow="4"/>
<!-- optional reader configuration -->
...
</map:readers>
...
]]></source>
</s2>
<s2 title="Configuration">
<p>
Explain the sitemap reader configuration, options when declaring template reader
</p>
</s2>
<s2 title="Setup">
<p>
Explain the sitemap reader setup, ie options when using template reader
</p>
</s2>
<s2 title="Effect on Object Model and Sitemap Parameters">
<p>
</p>
</s2>
</s1>
<s1 title="Bugs/Caveats">
<p>
Describe limitation, bugs of TemplateReader
</p>
</s1>
<s1 title="History">
<p>
MM-DD-YY: initial creation by You
</p>
</s1>
<s1 title="Copyright">
<p>
Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
</p>
</s1>
<s1 title="See also">
<p>
Links to related components pages.
</p>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org