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-ref.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  10.4 KB  |  300 lines
  1. <?xml version="1.0"?>
  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.2//EN" "document-v12.dtd">
  18. <document> 
  19.  
  20.     <header> 
  21.         <title>Input Modules Reference</title> 
  22.         <authors>
  23.             <person name="Tony Collen" email="tony@apache.org"/> 
  24.         </authors>
  25.         <abstract>A concise reference to Cocoon's InputModules.</abstract> 
  26.     </header> 
  27.  
  28.     <body> 
  29.  
  30.     <section>
  31.         <title>Introduction</title>
  32.         <p>This is meant to be a concise reference to Cocoon's InputModules, 
  33.         what they do, and how to use them.  InputModules are available in 
  34.         Cocoon 2.0.4 and above.  Many descriptions are taken directly from 
  35.         the respective modules' source code, or from trial and error 
  36.         experimentation.</p>
  37.         
  38.         <note>See also: the 
  39.         <link href="http://wiki.cocoondev.org/Wiki.jsp?page=InputModules">InputModules 
  40.         Wiki Page</link>.</note>
  41.     </section>
  42.  
  43.  
  44.     <section>
  45.         <title>Modules Reference</title>
  46.  
  47.         <section>
  48.             <title>AbstractInputModule</title>
  49.  
  50.             <p>AbstractInputModule gives you the infrastructure for easily 
  51.             deploying more InputModules.</p>
  52.         </section>
  53.  
  54.         <section>
  55.             <title>AbstractJXPathModule</title>
  56.  
  57.             <p>JXPathModule allows to access properties of any object in generic way. 
  58.             JXPath provides APIs for the traversal of graphs of JavaBeans, DOM and other 
  59.             types of objects using the XPath syntax. JXPathMetaModule is based on this 
  60.             class and duplicates the code since multiple inheritance is not possible. 
  61.             Please keep both classes in sync.</p>
  62.  
  63.             <p><strong>Configuration Example:</strong></p>
  64.  
  65.             <p>The following imports the class "String" as extension class to the 
  66.             JXPathContext using the prefix "str". Thus "str:length(xpath)" would apply 
  67.             the method "length" to the string object obtained from the xpath expression. 
  68.             Please note that the class needs to be fully qualified.</p>
  69.  
  70.             <source><![CDATA[<function name="java.lang.String" prefix="str"/>]]></source>
  71.  
  72.             <p>The following imports all classes in the package "java.util" as extension 
  73.             classes to the JXPathContext using the prefix "util". Thus "util:Date.new()" 
  74.             would create a new java.util.Date object.</p>
  75.  
  76.             <source><![CDATA[<package name="java.util" prefix="util"/>]]></source>
  77.         </section>
  78.  
  79.  
  80.         <section>
  81.             <title>AbstractMetaModule</title>
  82.  
  83.             <p>AbstractMetaModule gives you the infrastructure for easily deploying 
  84.             more "meta" InputModules i.e. InputModules that are composed of other 
  85.             InputModules. In order to get at the Logger, use getLogger().</p>
  86.         </section>
  87.  
  88.         <section>
  89.             <title>CollectionMetaModule</title>
  90.  
  91.             <p>Constructs an array of values suitable for a JDBC collection type from 
  92.             parameters obtained from another input module. Application is not limited 
  93.             to JDBC collections but can be used wherever similar named attributes 
  94.             shall be collected to an array of a given type. Currently, long, int, and 
  95.             string are known, more to come.</p>
  96.  
  97.             <p><strong>Global and Local Configuration:</strong></p>
  98.  
  99.             <fixme author="TC">Finish the reference for this Module.</fixme>
  100.         </section>
  101.  
  102.         <section>
  103.             <title>DateInputModule</title>
  104.  
  105.             <p>This module returns the current date, optionally formated 
  106.             as string. Format given through attribute "format" of 
  107.             configuration root node or nested <format/> tag on module 
  108.             declaration.</p>
  109.  
  110.             <note>The 'format' attribute doesn't seem to work. Nested 
  111.             <code><format/></code> tags work fine.</note>
  112.  
  113.             <note>See also: 
  114.             <link href="http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html">Java 
  115.             Date Format</link>.</note>
  116.         </section>
  117.  
  118.         <section>
  119.             <title>GlobalInputModule</title>
  120.             <p>This module allows you to access "global" variables which are defined in 
  121.             a sitemap's pipelines definition.</p>
  122.  
  123.  
  124.             <p><strong>cocoon.xconf usage:</strong></p>
  125.             <source><![CDATA[
  126. <input-modules>
  127.   ...
  128.   <component-instance 
  129.      class="org.apache.cocoon.components.modules.input.GlobalInputModule" 
  130.      logger="core.modules.input" 
  131.      name="global"/>
  132.   ...
  133. </input-modules> 
  134. ]]></source>
  135.  
  136.             <p><strong>Sitemap Usage:</strong></p>
  137.  
  138.             <source><![CDATA[
  139. <map:component-configurations>
  140.   <global-variables>
  141.       <doc>doc.xml</doc>
  142.   </global-variables>
  143. </map:component-configurations>
  144. ]]></source>
  145.  
  146.             <p><strong>Example Pipeline Fragment:</strong></p>
  147.  
  148.             <source><![CDATA[
  149. <map:match pattern="foo">
  150.   <map:generate type="file" src="documents/{global:doc}"/>
  151.   <map:transform src="stylesheets/foo2html.xsl"/>
  152.   <map:serialize/>
  153. </map:match>
  154. ]]></source>
  155.         </section>
  156.  
  157.  
  158.         <anchor id="raw-request-parameter-module"/>
  159.  
  160.         <section>
  161.             <title>RawRequestParameterModule</title>
  162.  
  163.             <p>This module allows access to "raw" request parameters and their 
  164.             values.</p>
  165.             <p>Values returned are "URL Encoded", meaning if a parameter is 
  166.             submitted as "foo+bar", you will get the string "foo+bar".</p>
  167.  
  168.             <note>For access to URL-Decoded request parameters, see the <link href=
  169.             "#request-parameter-module">RequestParameterModule</link>.</note>
  170.  
  171.             <p><strong>cocoon.xconf usage:</strong></p>
  172.  
  173.             <source><![CDATA[
  174. <input-modules>
  175.   ...
  176.   <component-instance 
  177.      class="org.apache.cocoon.components.modules.input.RawRequestParameterModule" 
  178.      logger="core.modules.input" 
  179.      name="raw-request-param"/>
  180.   ...
  181. </input-modules> 
  182. ]]></source>
  183.  
  184.             <p><strong>Example Pipeline Fragment:</strong></p>
  185.  
  186.             <source><![CDATA[
  187. <map:match pattern="amazonProxy">
  188.   <map:generate type="file" 
  189.       src="http://localhost:8888/search?qry={raw-request-param:actor}"/>
  190.   <map:serialize type="xml"/>
  191. </map:match>
  192. ]]></source>
  193.  
  194.             <p>
  195.                 This input module is useful when you are querying a remote service, 
  196.                 and you need to be able to send a search string with spaces or other 
  197.                 special characters intact. If you were to simply use 
  198.                 <code>{request-param:actor}</code>, you would end up sending a space 
  199.                 character to the remote service, which would be an error, since 
  200.                 <link href="http://www.faqs.org/rfcs/rfc1738.html">RFC 1738</link> 
  201.                 requires spaces and other special characters to be correctly encoded.
  202.             </p>
  203.         </section>
  204.  
  205.         <anchor id="request-parameter-module"/>
  206.  
  207.         <section>
  208.             <title>RequestParameterModule</title>
  209.  
  210.             <p>This module allows access to request parameters. Values returned are 
  211.             "URL Decoded". That is, if a request parameter is submitted as 
  212.             <code>foo+bar</code>, you will get the string "foo bar".</p>
  213.  
  214.             <note>For URL-Encoded request parameters, see the 
  215.             <link href="#raw-request-parameter-module">RawRequestParameterModule</link>.</note>
  216.  
  217.             <p><strong>cocoon.xconf usage:</strong></p>
  218.  
  219.             <source><![CDATA[
  220. <input-modules>
  221.   ...
  222.   <component-instance 
  223.      class="org.apache.cocoon.components.modules.input.RequestParameterModule" 
  224.      logger="core.modules.input" 
  225.      name="request-param"/>
  226.   ...
  227. </input-modules>
  228. ]]></source>
  229.  
  230.             <p><strong>Example Pipeline Fragment:</strong></p>
  231.  
  232.             <source><![CDATA[
  233. <map:match pattern="bar">
  234.    <map:generate type="file" src="documents/{request-param:file}"/>
  235.    <map:transform src="stylesheets/{request-param:stylesheet}"/>
  236.    <map:serialize/>
  237. </map:match>
  238. ]]></source>
  239.  
  240.             <p>This pipeline will match a request for "bar" and pass the request 
  241.             parameters "file" and "stylesheet" to the generator and transformer, 
  242.             respectively. (e.g. 
  243.             http://localhost:8080/cocoon/bar?file=doc.xml&stylesheet=main.xsl).</p>
  244.  
  245.             <warning>
  246.                 Directly passing request parameters for file access can be 
  247.                 dangerous. Remember to follow basic webapp safety rules when 
  248.                 designing your pipelines, and when passing around request 
  249.                 parameters.
  250.             </warning>
  251.         </section>
  252.  
  253.         <section>
  254.             <title>RequestURIModule</title>
  255.  
  256.             <p>Returns the URI of the request.</p>
  257.  
  258.             <p>If you are familliar with Avalon and Cocoon's component architecture, 
  259.             the following will explain what is specifically returned:</p>
  260.  
  261.             <source>String uri = ObjectModelHelper.getRequest(objectModel).getSitemapURI();</source>
  262.  
  263.             <p><strong>cocoon.xconf usage:</strong></p>
  264.  
  265.             <source><![CDATA[
  266. <input-modules>
  267.   ...
  268.   <component-instance 
  269.      class="org.apache.cocoon.components.modules.input.RequestURIModule" 
  270.      logger="core.modules.input" 
  271.      name="request-uri"/>
  272.   ...
  273. </input-modules>
  274. ]]></source>
  275.  
  276.             <p><strong>Example Sitemap Usage:</strong></p>
  277.  
  278.             <source>{request-uri:requestURI}</source>
  279.  
  280.             <p>This is how you would use the module most of the time, since the 
  281.             module only returns one item, the Request URI.</p>
  282.  
  283.             <note>
  284.                 The same effect can be achieved by passing the parameter name 
  285.                 "sitemapURI" to the request module. Therefore this component is not 
  286.                 declared in cocoon.xconf by default. You must manually add it.
  287.             </note>
  288.  
  289.         </section>
  290.         
  291.     </section>
  292.  
  293.     </body> 
  294.     
  295.     <footer> 
  296.         <legal>┬⌐ 2002 Apache Forrest</legal> 
  297.     </footer>
  298.  
  299. </document>
  300.