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 / modules.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  10.2 KB  |  258 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>Modules</title>
  22.     <authors>
  23.       <person name="Christian Haul" email="haul@apache.org"/>
  24.     </authors>
  25.   </header>
  26.  
  27.   <body>
  28.     <s1 title="Introduction">
  29.       <p>
  30.         Many sitemap components serve a purpose regardless how the input is
  31.         obtained. Still, to provide a wide range of components to quickly get
  32.         you up to speed, variants for different inputs exist. Modules allow to
  33.         create generic components and plug-in input or output later.
  34.       </p>
  35.       <p>
  36.         This document will explain how modules work and how to make use of
  37.         them. If you plan on writing your own modules, it is highly recommended
  38.         to read <fork
  39.           href="http://jakarta.apache.org/avalon/developing/index.html">
  40.           Developing With Apache Avalon</fork>. It is a very good description
  41.         of the underlying rationale and principles.
  42.       </p>
  43.     </s1>
  44.     <s1 title="Types of Modules">
  45.       <p>
  46.         Currently, three different types of modules exist: Input modules
  47.         provide means to enumerate attributes and to retrieve them, output
  48.         modules allow storing of data and exhibit transaction like semantics,
  49.         database modules encapsulate different mechanisms for auto increment
  50.         columns of various database management systems. Please refer to the
  51.         javadoc documentation of these interfaces.
  52.       </p>
  53.       <p>
  54.         Input modules are modelled after request attributes. The main
  55.         difference is, that every method takes two additional arguments, the
  56.         request object and a configuration object. The configuration object is
  57.         used to allow arbitrarily complex instructions for the input module.
  58.         Apart from that, input modules are more or less a drop-in replacement.
  59.       </p>
  60.       <p>
  61.         Output modules are again very similar to using request
  62.         attributes. Basically, they provide a method to set an attribute to a
  63.         value. Again, a request and a configuration object is the only change
  64.         to request attributes. A fundamental difference is, however, that
  65.         output modules should exhibit transactional behaviour. Thus setting an
  66.         attributes implicitly starts a transaction that must be ended by
  67.         calling rollback or commit. Only if the transaction is completed by
  68.         calling commit, the values set should be visible. This is needed
  69.         e.g. by the database actions.
  70.       </p>
  71.       <p>
  72.         Database modules, actually named AutoIncrementModule, contains
  73.         configuration information how to retrieve a value for an auto increment
  74.         column. It is possible to obtain the value before inserting a row,
  75.         while inserting as part of the SQL or after successful insert. If the
  76.         value is obtained before inserting, it can be generated
  77.         externally. Currently, supported database management systems include
  78.         HSQL, Informix, MySQL, and querying the database for the current max
  79.         value. 
  80.       </p>
  81.     </s1>
  82.     <s1 title="Using modules">
  83.       <p>
  84.         Using any of these modules requires a two step setup process. Step one
  85.         has already been done for your for all modules that come with Apache
  86.         Cocoon. Exception to this rule are the auto increment modules: only the
  87.         HSQL module is already setup.
  88.       </p>
  89.       <s2 title="Step 1: Making a new module known to Apache Cocoon">
  90.         <p>
  91.           Like other core components of Apache Cocoon, modules are declared in
  92.           <code>cocoon.xconf</code>. There are already too many to list here.
  93.         </p>
  94.         <source>
  95. <![CDATA[
  96. <input-modules>
  97.   <component-instance name="request"   
  98.   class="org.apache.cocoon.components.modules.input.RequestParameterModule"/>
  99.  
  100.   <component-instance name="attribute" 
  101.   class="org.apache.cocoon.components.modules.input.RequestAttributeModule"/>
  102.  
  103.   <component-instance name="URI"       
  104.   class="org.apache.cocoon.components.modules.input.RequestURIModule"/>
  105.  
  106.   <component-instance name="context"       
  107.   class="org.apache.cocoon.components.modules.input.RequestContextPathModule"/>
  108.  
  109.   <component-instance name="header"    
  110.   class="org.apache.cocoon.components.modules.input.HeaderAttributeModule"/>
  111.  
  112.   <component-instance name="session"   
  113.   class="org.apache.cocoon.components.modules.input.SessionAttributeModule"/>
  114.  
  115.   <component-instance name="date"      
  116.   class="org.apache.cocoon.components.modules.input.DateInputModule"/>
  117.  
  118.   <component-instance name="defaults"  
  119.   class="org.apache.cocoon.components.modules.input.DefaultsModule">
  120.     <input-module name="request"/>
  121.     <values>
  122.       <skin>defaultSkin</skin>
  123.       <base-url>http://localhost:8080/cocoon</base-url>
  124.     </values>
  125.   </component-instance>
  126. </input-modules>
  127.  
  128. <output-modules>
  129.   <component-instance name="attribute" 
  130.   class="org.apache.cocoon.components.modules.output.RequestAttributeOutputModule"/>
  131.  
  132.   <component-instance name="session"   
  133.   class="org.apache.cocoon.components.modules.output.SessionAttributeOutputModule"/>
  134. </output-modules>
  135.  
  136. <autoincrement-modules>
  137.   <component-instance name="auto" 
  138.   class="org.apache.cocoon.components.modules.database.HsqlIdentityAutoIncrementModule"/>
  139.  
  140.   <!--
  141.   <component-instance name="auto" 
  142.   class="org.apache.cocoon.components.modules.database.ManualAutoIncrementModule"/>
  143.   <component-instance name="auto" 
  144.   class="org.apache.cocoon.components.modules.database.IfxSerialAutoIncrementModule"/>
  145.   <component-instance name="auto" 
  146.   class="org.apache.cocoon.components.modules.database.MysqlAutoIncrementModule"/>
  147.   -->
  148. </autoincrement-modules>]]>
  149.         </source>
  150.         <p>
  151.           The above snippet declares a number of modules. After this, the
  152.           modules are accessible through the given name. Thus, when an
  153.           <code>input-module</code> is expected, it is sufficient to give the
  154.           name of a module, like <code>header</code>.
  155.         </p>
  156.         <p>
  157.           For the auto increment modules only one is declared as the name
  158.           <code>"auto"</code> has special meaning to the modular database
  159.           actions. If more than one is needed at the same time, the
  160.           configuration of the database actions needs to explicitly specify
  161.           which one to use.
  162.         </p>
  163.       </s2>
  164.       <s2 title="Step 2: Use it">
  165.         <p>
  166.           The following alternatives for using modules exist:
  167.         </p>
  168.         <s3 title="Step 2a: Use it as sitemap variable">
  169.           <p>
  170.             Input modules can be used in a sitemap almost like a sitemap
  171.             variable. If the variable name contains a colon (":"), the
  172.             preceeding string is used as the name of the module to use and the
  173.             trailing string is passed to the module. The expression is replaced
  174.             with the string value returned from the module.
  175.           </p>
  176.           <source>
  177. <![CDATA[
  178. <map:transform src="resources/stylesheets/{../skin}.xsl"/>]]>
  179.           </source>
  180.           <p>
  181.             The above example uses the variable <code>skin</code> declared
  182.             e.g. by an action for the stylesheet to apply to the page. The
  183.             example below uses an input module instead. The way this module was
  184.             declared above allows to override the skin with a request parameter
  185.             named "skin".
  186.           </p>
  187.           <source>
  188. <![CDATA[
  189. <map:transform src="resources/stylesheets/{default:skin}.xsl"/>]]>
  190.           </source>
  191.           <p>
  192.             Some of the input modules are JXPath-enabled, so you can use
  193.             XPath expressions to access values (see Input Modules sample for details).
  194.             The following example demonstrates the use of XPath function 
  195.             with <code>system-property</code> module.
  196.           </p>
  197.       <source>
  198. <![CDATA[
  199. <map:parameter name="users-home-base"
  200.   value="{system-property:substring-before(user.home, user.name)}"/>]]>
  201.       </source>
  202.         </s3>
  203.         <s3 title="Step 2b: Use it on an XSP">
  204.           <p>
  205.             The input logicsheet allows easy use of InputModules from an
  206.             XSP. Currently, it provides tags for getting one value, an
  207.             array of values, and an Iterator for a Collection of
  208.             parameter names.
  209.           </p>
  210.           <source>
  211. <![CDATA[
  212. <?xml version="1.0" encoding="ISO-8859-1"?>
  213.  
  214. <xsp:page language="java"
  215.     xmlns:xsp="http://apache.org/xsp"  
  216.     xmlns:input="http://apache.org/cocoon/xsp/input/1.0">
  217.  
  218.   <page>
  219.     <title>Testing InputModules</title>
  220.  
  221.     <p>
  222.       Parameter name=<input:get-attribute module="request-param"
  223.                        as="string" name="module" default="John Doe"/>;
  224.     </p>
  225.     <p>
  226.       Parameter cars=<input:get-attribute-values module="request-param" 
  227.                        as="xml" name="car"/>;
  228.     </p>
  229.   </page>
  230. </xsp:page>]]>
  231.           </source>
  232.         </s3>
  233.         <s3 title="Step 2c: Have sitemap components use a module">
  234.           <p>
  235.             This depends on the component that is to be used. As an example the
  236.             <code>CachingWildcardMatcher</code> requires to set the
  237.             <code>input-module</code> on declaration.
  238.           </p>
  239.           <source>
  240. <![CDATA[
  241. <map:matchers default="wildcard">
  242.   <map:matcher name="cached-uri" 
  243.       src="org.apache.cocoon.matching.modular.CachingWildcardMatcher">
  244.     <input-module name="URI"/>
  245.   </map:matcher>
  246. </map:matchers>]]>
  247.           </source>
  248.           <p>
  249.             By replacing the input module name with any of the other declared
  250.             input modules, this matcher can be used to match e.g. on session
  251.             attributes, request headers or even dates!
  252.           </p>
  253.         </s3>
  254.       </s2>
  255.     </s1>
  256.   </body>
  257. </document>
  258.