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 / cinclude-transformer.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  14.3 KB  |  363 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>CInclude Transformer</title>
  22.   <subtitle>in @doctitle@</subtitle>
  23.   <version>0.9</version>
  24.   <type>Technical document</type>
  25.   <authors>
  26.    <person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
  27.   </authors>
  28.   <abstract>This document describes the CInclude transformer.</abstract>
  29.  </header>
  30.  <body>
  31.   <s1 title="CInclude Transformer">
  32.    <p>This transformer includes XML in the current stream and acts therefore
  33.       as a kind of (dynamic) content aggregation. Two forms are supported by
  34.       the transformer: one verbose and flexible approach, and a simple approach.
  35.       We will first discuss the simple approach and
  36.       the more flexible is mentioned in the next chapter. In addition
  37.       the cinclude transformer provides a caching mechanism (for the
  38.       simple include form).</p>
  39.    <p>
  40.     This transformer triggers for the element <code>include</code> in the
  41.     namespace "http://apache.org/cocoon/include/1.0".
  42.     The <code>src</code> attribute contains the url which points to
  43.     an xml resource which is included instead of the element.
  44.     With the attributes <code>element</code>, <code>ns</code> and
  45.     <code>prefix</code> it is possible to specify an element
  46.     which surrounds the included content.
  47.    </p>
  48.    <ul>
  49.     <li>Name : cinclude</li>
  50.     <li>Class: org.apache.cocoon.transformation.CIncludeTransformer</li>
  51.     <li>Cacheable: no.</li>
  52.    </ul>
  53.    <p>
  54.     A simple example might help to use the CIncludeTransfomer effectively:
  55.    </p>
  56.    <p>
  57.     Add the CIncludeTransformer to the components in your sitemap.xmap
  58.    </p>
  59. <source><![CDATA[
  60. ...
  61. <map:components>
  62. ...
  63.   <map:transformers default="xslt">
  64.   ...
  65.     <map:transformer name="cinclude"
  66.       src="org.apache.cocoon.transformation.CIncludeTransformer"/>
  67.   ...
  68. ]]></source>
  69.    <p>
  70.      Next define in your pipeline to use the CIncludeTransformer
  71.    </p>
  72. <source><![CDATA[
  73. <map:match pattern="cinc/simple-cinc">
  74.   <map:generate src="cinc/simple-cinc.xml"/>
  75.   <map:transform type="cinclude"/>
  76.   <map:transform src="stylesheets/page/simple-page2html.xsl"/>
  77.   <map:serialize/>
  78. </map:match>
  79. ]]></source>
  80.  
  81.    <p>
  82.     In this example pipeline it assumed that simple-cinc.xml contains
  83.     the include element. Beside defining the include element
  84.     it defines the namespace URI "http://apache.org/cocoon/include/1.0".
  85.     This helps the CIncludeTransformer to find the tag to get replaced by
  86.     the xml content referenced via the src attribute.
  87.     The simple-cinc.xml may look like this:
  88.    </p>
  89. <source><![CDATA[
  90. <?xml version="1.0" encoding="UTF-8"?>
  91. <page 
  92.   xmlns:cinclude="http://apache.org/cocoon/include/1.0">
  93.   <title>Hello</title>
  94.   <content>
  95.     <para>This is my first Cocoon page!</para>
  96.     <cinclude:include src="include.xml" element="included"/>
  97.   </content>
  98. </page>
  99. ]]></source>
  100.  
  101.    <p>
  102.     Next you should define the include.xml file which is included.
  103.     A simple include.xml might look like this:
  104.    </p>
  105. <source><![CDATA[
  106. <?xml version="1.0"?>
  107. <p>
  108.  I am <strong>included</strong> by CIncludeTransformer.
  109.  I come from "include.xml".
  110. </p>
  111. ]]></source>
  112.  
  113.    <p>
  114.     Now finally we have everything put together the xml content after the
  115.     CIncludeTransformer processing will look like this:
  116.    </p>
  117. <source><![CDATA[
  118. <?xml version="1.0" encoding="UTF-8"?>
  119. <page 
  120.   xmlns:cinclude="http://apache.org/cocoon/include/1.0">
  121.   <title>Hello</title>
  122.   <content>
  123.     <para>This is my first Cocoon page!</para>
  124.     <included>
  125.       <p>
  126.         I am <strong>included</strong> by CIncludeTransformer.
  127.         I come from "include.xml".
  128.       </p>
  129.     </included>
  130.   </content>
  131. </page>
  132. ]]></source>
  133.   </s1>
  134. <s1 title="Including External XML (simple)">
  135.           <p>One feature of the cinclude transformer (this is currently not
  136.              supported by the caching cinclude transformer) is including XML from
  137.              external sources, e.g. files or from an HTTP server. 
  138.              The <code>cinclude:includexml</code> tag starts including of XML:</p> 
  139.           <source>
  140. <cinclude:includexml>  <!-- Include XML from HTTP server -->
  141.      <cinclude:src>http://external.news.com/flashnews.xml</cinclude:src>
  142. </cinclude:includexml>
  143. </source> 
  144.           <p> This would be a simple way of "get"ting XML data from an
  145.              external site. Using this method it is also possible to pass parameters in the
  146.              url - just as you would in a "get" sent from a browser.</p> 
  147.           <source>
  148. <cinclude:includexml>  <!-- Include XML from HTTP server -->
  149.     <cinclude:src>http://external.news.com/flashnews.xml?id=1234&myname=matthew</cinclude:src>
  150. </cinclude:includexml>
  151. </source> 
  152.           <p>If the external XML is not valid or not available, the 
  153.              transformer signals an error to the pipeline and the document containing the
  154.              include command is not available.</p> 
  155.           <p>For this purpose the <code>ignoreErrors</code> attribute can be
  156.              used:</p> 
  157.           <source>
  158. <cinclude:includexml ignoreErrors="true">
  159. ...
  160. </cinclude:includexml></source> 
  161.         </s1> 
  162.         <s1 title="Including External XML (advanced)">
  163.           <p>The above section shows you how to include XML data from an
  164.              external source such as an HTTP server using the simple "get" method supplied
  165.              in the HTTP protocol. For more advanced uses you will wish to be able to send
  166.              "Post" or other HTTP methods to the server. In addition you may want to
  167.              actually send XML data to the server - just as you would using an HTML form.
  168.              The format of this resource is slightly more complicated:</p> 
  169.           <source>
  170. <?xml version="1.0"?>
  171. <data xmlns:cinclude="http://apache.org/cocoon/include/1.0">
  172. <cinclude:includexml>
  173.     <cinclude:src>http://itsunshine/tamino/blah</cinclude:src>
  174.     <cinclude:configuration>
  175.     <cinclude:parameter>
  176.       <cinclude:name>method</cinclude:name>
  177.       <cinclude:value>POST</cinclude:value>
  178.     </cinclude:parameter>
  179.     </cinclude:configuration>
  180.     <cinclude:parameters>
  181.       <cinclude:parameter>
  182.       <cinclude:name>message</cinclude:name>
  183.       <cinclude:value>Hi there</cinclude:value>
  184.     </cinclude:parameter>
  185.     <cinclude:parameter>
  186.       <cinclude:name>_Process</cinclude:name>
  187.       <cinclude:value><name>matti</name><age>36</age></cinclude:value>
  188.     </cinclude:parameter>
  189.     </cinclude:parameters>
  190. </cinclude:includexml>
  191. </data>
  192.         </source> 
  193.           <p>Lets look at the tags. The tag <code>cinclude:src</code> defines the address of the
  194.              resource we want to access and then comes a list of (optional)
  195.              connection-specific parameters (enclosed in the <code>cinclude:configuration</code> tag).
  196.              In this example the HTTP-method ("POST") is passed into the connection. The
  197.              format of these parameters is discussed next.</p> 
  198.           <p>Then comes the list of parameters we wish to pass into the
  199.              function. Each parameter defined has a name and a value. The value can either
  200.              be text or XML.</p> 
  201.           <p>The format of the parameters is the same as for the connection
  202.              configuration.</p> 
  203.         </s1> 
  204.   <s1 title="Caching">
  205.    <p>This transformer includes XML in the current stream and acts therefore
  206.       as a kind of (dynamic) content aggregation. However, the included content
  207.       might be very big or either it might take a lot of time to fetch
  208.       the content. If, in those cases, your content does not change too
  209.       frequently, you can turn on caching for these contents.</p>
  210.    <p>
  211.     To turn on caching, this transformer triggers for the element <code>cached-include</code> 
  212.     in the namespace "http://apache.org/cocoon/include/1.0/caching".
  213.     The <code>src</code> attribute contains the url which points to
  214.     an xml resource that is included instead of the element.
  215.     It is possible to mix the <code>cached-include</code> and the <code>include</code>
  216.     element, so only parts are cached and others are not.
  217.    </p>
  218.    <p>
  219.     A simple example might help to use the caching effectively:
  220.    </p>
  221.    <p>
  222.      First define your pipeline to use the CIncludeTransformer with
  223.      caching turned on; you turn on caching by setting the <code>expires</code>
  224.      parameter to a value greater than 0. The exact meaning of this
  225.      parameter is explained below.
  226.    </p>
  227. <source><![CDATA[
  228. <map:match pattern="cinc/simple-cinc">
  229.   <map:generate src="cinc/simple-cinc.xml"/>
  230.   <map:transform type="cinclude">
  231.       <map:parameter name="expires" value="600"/>
  232.   </map:transform>
  233.   <map:transform src="stylesheets/page/simple-page2html.xsl"/>
  234.   <map:serialize/>
  235. </map:match>
  236. ]]></source>
  237.  
  238.    <p>
  239.     In this example-pipeline it is assumed that simple-cinc.xml contains
  240.     the <code>cached-include</code> element. Beside defining the element
  241.     it uses the namespace URI "http://apache.org/cocoon/include/1.0".
  242.     This helps the transformer to find the tag to get replaced by
  243.     the xml content referenced via the src attribute.
  244.     The simple-cinc.xml may look like this:
  245.    </p>
  246. <source><![CDATA[
  247. <?xml version="1.0" encoding="UTF-8"?>
  248. <page 
  249.   xmlns:cinclude="http://apache.org/cocoon/include/1.0">
  250.   <title>Hello</title>
  251.   <content>
  252.     <para>This is my first Cocoon page!</para>
  253.     <cinclude:cached-include src="http://server/document1.xml"/>
  254.     <cinclude:cached-include src="http://server/document2.xml"/>
  255.   </content>
  256. </page>
  257. ]]></source>
  258.  
  259.    <p>
  260.     Now finally we have everything put together the xml content after the
  261.     CIncludeTransformer processing will look like this:
  262.    </p>
  263. <source><![CDATA[
  264. <?xml version="1.0" encoding="UTF-8"?>
  265. <page 
  266.   xmlns:cinclude="http://apache.org/cocoon/include/1.0">
  267.   <title>Hello</title>
  268.   <content>
  269.     <para>This is my first Cocoon page!</para>
  270.     <document1>
  271.         CONTENT OF document 1
  272.     </document1>
  273.     <document2>
  274.         CONTENT OF document 2
  275.     </document2>
  276.   </content>
  277. </page>
  278. ]]></source>
  279.   <p>So, of course even with caching turned on, this transformer acts like the 
  280.   usual cinclude transformer. But as you can see from the example above, you 
  281.   can define an expires value. The fetched content is cached for the duration of 
  282.   this value; in the example above the content is cached for 10 minutes. So, if 
  283.   during the next 10 minutes after the first time this pipeline was processed, 
  284.   someone else requests this pipeline, the content is not fetched again from a 
  285.   distant server (or whereever the content is stored). It is directly delivered 
  286.   from the cache. When the 10 minutes have expired, the next time the pipeline 
  287.   is requested, the content is fetched again and stored in the cache for the 
  288.   next 10 minutes.</p>
  289.   <p>You can fine tune the behaviour of the transformer with several parameters.</p>
  290.   <p>The <code>expires</code> parameter defines the expiration date of the
  291.     content in seconds from the time the pipeline is requested.</p>
  292.  <p>Usually the content is cached in the common store, but you
  293.    can also define a writeable/modifiable source with the "source" parameter,
  294.  e.g. "file:/c:/temp". Then the cached content is written into this
  295.  directory.</p>
  296.  <p>With the optional <code>purge</code> set to <code>true</code>
  297.   the cache is purged which means the cached content is regarded as
  298.   invalid nevertheless if it has expired or not.</p>
  299.  <p>With the optional parameter <code>parallel</code> the various
  300.   included contents are processed (included) in parallel rather than
  301.   in a series.</p>
  302.  <p>With the optional parameter <code>preemptive</code> set to <code>true</code>
  303.   a pre-emptive caching is activated. When a resource is requested with
  304.   pre-emptive caching, this transformer always attempts to get the 
  305.   content from the cache. If the content is not in the cache, it is
  306.   of course retrieved from the original source and cached.
  307.   If the cached resource has expired, it is still provided. The cache
  308.   is updated by a background task. This task has to be started
  309.   beforehand.</p>
  310.    <p>
  311.      Complete Example:
  312.    </p>
  313. <source><![CDATA[
  314. <map:match pattern="cinc/simple-cinc">
  315.   <map:generate src="cinc/simple-cinc.xml"/>
  316.   <map:transform type="cinclude">
  317.       <map:parameter name="expires" value="600"/>
  318.       <map:parameter name="purge" value="false"/>
  319.       <map:parameter name="parallel" value="true"/>
  320.       <map:parameter name="preemptive" value="false"/>
  321.       <map:parameter name="source" value="file:/c:/temp"/>
  322.   </map:transform>
  323.   <map:transform src="stylesheets/page/simple-page2html.xsl"/>
  324.   <map:serialize/>
  325. </map:match>
  326. ]]></source>
  327.   </s1>
  328.   <s1 title="Configuration">
  329. <p>Besides the usual transformer configuration, this transformer requires some components.
  330. You have to add the following lines to the cocoon.xconf:</p>
  331. <source><![CDATA[
  332.  <component class="org.apache.cocoon.transformation.helpers.DefaultIncludeCacheManager" 
  333.             role="org.apache.cocoon.transformation.helpers.IncludeCacheManager"
  334.             logger="test">
  335.     <!-- Specify this only if you use preemptive-caching -->
  336.     <parameter name="preemptive-loader-url" value="http://localhost:8080/cocoon/loader"/>
  337.  </component>
  338. ]]></source>
  339.   <p>If you want to use preemptive caching, you have to specify a URI inside Cocoon that contains 
  340.      the preemptive-loader action. This pipeline is automatically called, when
  341.      preemptive loading is actived and requried. It loads the content in the background.</p>
  342.      <p>First you have to define the action:</p>
  343. <source><![CDATA[
  344. ...
  345. <map:components>
  346. ...
  347.   <map:actions>
  348.   ...
  349.       <map:action name="preemptive"
  350.                   src="org.apache.cocoon.transformation.helpers.PreemptiveLoaderAction"/>
  351.   ...
  352. ]]></source>  
  353.    <p>Then you must define a pipeline containing the action. This is the pipeline that
  354.    has to be configured in the cocoon.xconf:</p>
  355. <source><![CDATA[
  356.    <map:match pattern="loader">
  357.        <map:act type="preemptive"></map:act>
  358.    </map:match>
  359. ]]></source>  
  360. </s1>
  361.  </body>
  362. </document>
  363.