home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-cocoon-addon-1.4.9-installer.exe / database-reader.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  7.9 KB  |  225 lines
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!--
  3.   Copyright 1999-2004 The Apache Software Foundation
  4.  
  5.   Licensed under the Apache License, Version 2.0 (the "License");
  6.   you may not use this file except in compliance with the License.
  7.   You may obtain a copy of the License at
  8.  
  9.       http://www.apache.org/licenses/LICENSE-2.0
  10.  
  11.   Unless required by applicable law or agreed to in writing, software
  12.   distributed under the License is distributed on an "AS IS" BASIS,
  13.   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.   See the License for the specific language governing permissions and
  15.   limitations under the License.
  16. -->
  17. <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
  18.  
  19. <document>
  20.   <header>
  21.     <title>DatabaseReader</title>
  22.     <version>0.9</version>
  23.     <type>Technical document</type>
  24.     <authors>
  25.       <person name="Bernhard Huber" email="huber@apache.org"/>
  26.     </authors>
  27.     <abstract>This document describes the DatabaseReader of Cocoon.</abstract>
  28.   </header>
  29.   <body>
  30.     <s1 title="DatabaseReader">
  31.       <table>
  32.         <tr>
  33.           <td>NAME</td><td>databasereader</td>
  34.         </tr>
  35.         <tr>
  36.           <td>WHAT</td><td>The <code>DatabaseReader</code> component is used 
  37.             to serve data from a database
  38.           </td>
  39.         </tr>
  40.         <tr>
  41.           <td>TYPE</td><td>Reader, Sitemap Component</td>
  42.         </tr>
  43.         <tr>
  44.           <td>BLOCK</td><td>Database</td>
  45.         </tr>
  46.         <tr>
  47.           <td>CLASS</td><td>org.apache.cocoon.reading.DatabaseReader</td>
  48.         </tr>
  49.         <!--tr>
  50.           <td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
  51.         </tr-->
  52.         <tr>
  53.           <td>SINCE</td><td>Cocoon 2.1</td>
  54.         </tr>
  55.         <tr>
  56.           <td>CACHEABLE</td><td>yes</td>
  57.         </tr>
  58.       </table>
  59.     </s1>
  60.     <s1 title="Description">
  61.       <p>
  62.         This Reader pulls a resource from a database.  It is configured with
  63.         the Connection to use, parameters specify the table and column
  64.         to pull the image from, and source specifies the source key information.
  65.       </p>
  66.     </s1>
  67.     <s1 title="Usage">
  68.       <p>
  69.       </p>
  70.       <s2 title="Sitemap pipeline examples">
  71.         <p>
  72.           The following pipeline snippet uses a <code>Database Reader</code> 
  73.           for serving <em>PNG</em> images from a database.
  74.         </p>
  75.         <source><![CDATA[
  76. <map:match pattern="images/*.png">
  77.   <map:read type="databasereader" 
  78.     src="{1}" 
  79.     mime-type="image/png">
  80.     <!-- option sitemap parameters -->
  81.     <map:parameter name="table" value="images"/>
  82.     <map:parameter name="image" value="image"/>
  83.     <map:parameter name="key" value="name"/>
  84.     <map:parameter name="where" value="publishing = 1"/>
  85.     <map:parameter name="order-by" value="created"/>
  86.     <map:parameter name="last-modified" value="last-modified"/>
  87.   </map:read>
  88. </map:match>
  89.         ]]></source>
  90.         <p>
  91.           The snippet above make following assumption about the database
  92.         </p>
  93.         <ul>
  94.           <li>A database table <code>images</code> holds the <em>PNG</em> image data.</li>
  95.           <li>The database table has <code>image</code> column storing the image data as <code>BLOB</code>.
  96.           </li>
  97.           <li>The database table has <code>key</code> column which must match the value of 
  98.             of <code>{1}</code>.
  99.           </li>
  100.           <li>The database table has <code>publishing</code> column indicating by value <code>1</code>
  101.             that the image data is allowed to get published.
  102.           </li>
  103.           <li>The database table has <code>created</code> column, indicating the creation date of
  104.             the image data, and used if the <code>key</code> is not a primary key, serving
  105.             images in a LIFO fashion.
  106.           </li>
  107.           <li>The database table has <code>last-modified</code> column of type <code>TIMESTAMP</code>
  108.             indicating the last modification date of the image data.
  109.           </li>
  110.         </ul>
  111.       </s2>
  112.       <s2 title="Sitemap component configuration example">
  113.         <p></p>
  114.         <source><![CDATA[
  115. <map:readers...
  116.   <map:reader name="databasereader" 
  117.     src="org.apache.cocoon.reading.DatabaseReader"
  118.     logger="sitemap.reader.databasereader" 
  119.     pool-max="32" pool-min="1" pool-grow="4"/>
  120.     <!-- optional reader configuration -->
  121.     ...
  122.   </map:readers>
  123. ...
  124. ]]></source>
  125.       </s2>
  126.       <s2 title="Configuration">
  127.         <p>
  128.           In the <code>Database Reader</code> declaration section following configuration 
  129.           options are available
  130.         </p>
  131.         <table>
  132.           <tr><th>Configurationname</th><th>Type</th><th>Comment</th></tr>
  133.           <tr><td>use-connection</td><td>Data source name</td>
  134.             <td>The name of a database selector, configured in the
  135.               <code>cocoon.xconf</code> file.
  136.             </td>
  137.           </tr>
  138.           <tr><td>invalidate</td><td> never | always </td>
  139.             <td>
  140.               This option configures the caching behaviour if lastModifed
  141.               has value of <code>-1</code>.
  142.             </td>
  143.           </tr>
  144.         </table>
  145.       </s2>
  146.       <s2 title="Setup">
  147.         <p>
  148.           The <code>DatabaseReader</code> accepts following setup parameters
  149.         </p>
  150.         <table>
  151.           <tr><th>Parametername</th><th>Type</th><th>Comment</th></tr>
  152.           <tr><td>table</td><td>database table name</td>
  153.             <td>The database table name</td>
  154.           </tr>
  155.           <tr><td>image</td><td>database column name</td>
  156.             <td>The column name of the image data</td>
  157.           </tr>
  158.           <tr><td>key</td><td>database key column name</td>
  159.             <td>The key column name of the image data matching the src attribute of
  160.               the <map:read> sitemap usage.
  161.             </td>
  162.           </tr>
  163.           <tr><td>where</td><td>database where expression</td>
  164.             <td>Optional parameter specifying SQL where expression.</td>
  165.           </tr>
  166.           <tr><td>order-by</td><td>database order-by expression</td>
  167.             <td>Optional parameter specifying an SQL order-by expression.
  168.             </td>
  169.           </tr>
  170.           <tr><td>last-modified</td><td>timestamp column name</td>
  171.             <td>Optional parameter a <code>TIMESTAMP</code> column name, added
  172.               to the <code>SELECT</code> clause of the SQL query. 
  173.             </td>
  174.           </tr>
  175.           <tr><td>content-type</td><td>database column name</td>
  176.             <td>Optional parameter a column name, if specified the column
  177.               value overrides the <code>mime-type</code> attribute of the
  178.               <map:read> sitemap usage.
  179.             </td>
  180.             </tr>
  181.         </table>
  182.         <p>
  183.           The key value is derived from the <code>src</code> attribute
  184.           of the <code>Database Reader</code> usage..
  185.         </p>
  186.         <p>
  187.           The <code>Database Reader</code> builds internally following SQL query:
  188.         </p>
  189.         <source><![CDATA[
  190. SELECT {image} [, last-modified] [, {order-by-column} ] from {table}
  191.   WHERE {key} = {src} [ AND {where} ]
  192.   [ORDER BY {order-by}]
  193.         ]]></source>
  194.       </s2>
  195.       <s2 title="Effect on Object Model and Sitemap Parameters">
  196.         <p>
  197.         </p>
  198.       </s2>
  199.     </s1>
  200.     <s1 title="Bugs/Caveats">
  201.       <p>
  202.         The <code>Database Reader</code> needs a datasource name, it is referenced
  203.         by the configuration element <code>use-connection</code>. The datasource name
  204.         has to be configured in the Cocoon database configuration <code>cocoon.xconf</code>.
  205.       </p>
  206.       <p>
  207.         If the parameter <code>last-modified</code> ends with <code>" DESC"</code> this
  208.         suffix is truncated as it is appended to the SQL clause, noted as {order-by-column}
  209.         in the SQL query snippet above.
  210.       </p>
  211.     </s1>
  212.     <s1 title="History">
  213.       <p>
  214.         12-25-02: created initial version by Bernhard Huber
  215.       </p>
  216.     </s1>
  217.     <s1 title="See also">
  218.       <p>
  219.         <!-- Links to related components pages -->
  220.       </p>
  221.     </s1>
  222.   </body>
  223. </document>
  224.  
  225.