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 / xml-serializer.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  10.8 KB  |  279 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>XML Serializer</title>
  22.     <version>0.9</version>
  23.     <type>Technical document</type>
  24.     <authors>
  25.       <person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
  26.       <person name="Bernhard Huber" email="huber@apache.org"/>
  27.     </authors>
  28.     <abstract>This document describes the xml serializer of Cocoon.</abstract>
  29.   </header>
  30.   <body>
  31.     <s1 title="XML Serializer">
  32.       <p>
  33.         The xml serializer is the simplest possible serializer. 
  34.         It generates an xml document from the sax events.
  35.         This serializer is used for serializing to any XML document
  36.         format, ie. SVG, WML, VRML, et. al.
  37.       </p>
  38.       <ul>
  39.         <li>Name : xml</li>
  40.         <li>Class: org.apache.cocoon.serialization.XMLSerializer</li>
  41.         <li>Cacheable: yes.</li>
  42.       </ul>
  43.       <s2 title="Sitemap Configuration">
  44.         <p>
  45.           The XML Serializer is declared in the sitemap serializers section.
  46.         </p>
  47.         <source><![CDATA[
  48. <map:serializers ...
  49. ...
  50.   <map:serializer name="xml"
  51.     src="org.apache.cocoon.serialization.XMLSerializer"
  52.     mime-type="text/xml"  
  53.     logger="sitemap.serializer.xml" 
  54.     pool-grow="4" pool-max="32" pool-min="4">
  55.     <!-- serializer configurations -->
  56. ...    
  57.   </map:serializer>
  58. ...
  59.         ]]></source>
  60.         <p>
  61.           XML Serializer can be configured, specifying elements inside of
  62.           the <map:serializer> body.
  63.         </p>
  64.         <s3 title="Configuration Example">
  65.           <p>
  66.             The following XML Serializer snippet is setting
  67.             encoding configuration for the XML Serializer
  68.           </p>
  69.           <source><![CDATA[
  70. <map:serializer name="xml"         
  71.   src="org.apache.cocoon.serialization.XMLSerializer"
  72.   mime-type="text/xml">
  73.   <encoding>ISO-8859-1</encoding>
  74. </map:serializer>
  75.           ]]></source>
  76.           <p>
  77.             This configuration will result in xml output of the form
  78.           </p>
  79.           <source><![CDATA[
  80. <?xml version="1.0" encoding="ISO-8859-1"?>
  81. ...
  82.           ]]></source>
  83.         </s3>
  84.         <p>
  85.           The XML Serializer accepts following configuration parameters.
  86.           These configurations are not Xalan specific.
  87.         </p>
  88. <!--
  89. #
  90. # Specify defaults when method="xml".  These defaults serve as a base for 
  91. # other defaults, such as output_html and output_text.
  92. #
  93.  
  94. # XSLT properties do not need namespace qualification.
  95. method=xml
  96. version=1.0
  97. encoding=UTF-8
  98. indent=no
  99. omit-xml-declaration=no
  100. standalone=no
  101. media-type=text/xml
  102.  
  103. # Xalan-specific output properties.  These can be overridden in the stylesheet 
  104. # assigning a xalan namespace.  For example:
  105. # <xsl:stylesheet version="1.0"
  106. #          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  107. #          xmlns:xalan="http://xml.apache.org/xslt">
  108. #  <xsl:output method="html" encoding="UTF-8"
  109. #              xalan:content-handler="MyContentHandler"/>
  110. #  ...
  111. # Note that the colon after the protocol needs to be escaped.
  112. {http\u003a//xml.apache.org/xslt}indent-amount=0
  113. {http\u003a//xml.apache.org/xslt}content-handler=org.apache.xalan.serialize.SerializerToXML
  114.  
  115. -->
  116.         <table>
  117.           <tr><th>Name</th><th>Xalan Default Value</th><th>Comment</th></tr>
  118.           <tr><td>cdata-section-elements</td>
  119.             <td>none</td>
  120.             <td><code>cdata-section-elements</code> specifies a whitespace delimited
  121.                list of the names of elements whose text node children should be output
  122.                using CDATA sections.
  123.                See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation.</link>
  124.             </td>
  125.           </tr>
  126.           <tr><td>doctype-public</td>
  127.             <td>none</td>
  128.             <td><code>doctype-public</code> specifies the public identifier
  129.               to be used in the document type declaration.
  130.             </td>
  131.           </tr>
  132.           <tr><td>doctype-system</td>
  133.             <td>none</td>
  134.             <td>
  135.               <code>doctype-system</code> specifies the system identifier
  136.               to be used in the document type declaration.
  137.               See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link>
  138.             </td>
  139.           </tr>
  140.           <tr><td>encoding</td>
  141.             <td>none</td>
  142.             <td><code>encoding</code> specifies the preferred character
  143.               encoding that the Transformer should use to encode sequences of
  144.               characters as sequences of bytes. The value of the attribute should be
  145.               treated case-insensitively. The value must only contain characters in
  146.               the range #x21 to #x7E (i.e., printable ASCII characters). The value
  147.               should either be a <code>charset</code> registered with the Internet
  148.               Assigned Numbers Authority <link href="#IANA">[IANA]</link>,
  149.               <link href="#RFC2278">[RFC2278]</link> or start with <code>X-</code>.
  150.               See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link>
  151.             </td>
  152.           </tr>
  153.           <tr><td>indent</td>
  154.             <td>
  155.               yes
  156.             </td>
  157.             <td>
  158.               A Flag for toggling indent. This flag toggles only if some elements
  159.               should trigger a line break.
  160.             </td>
  161.           </tr>
  162.           <tr><td>media-type</td>
  163.             <td>
  164.             </td>
  165.             <td>
  166.               <code>media-type</code> specifies the media type (MIME
  167.               content type) of the data that results from outputting the result
  168.               tree. The <code>charset</code> parameter should not be specified
  169.               explicitly; instead, when the top-level media type is
  170.               <code>text</code>, a <code>charset</code> parameter should be added
  171.               according to the character encoding actually used by the output
  172.               method.
  173.               See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link>
  174.             </td>
  175.           </tr>
  176.           <tr><td>method</td>
  177.             <td>
  178.             </td>
  179.             <td>
  180.               The method attribute identifies the overall method that
  181.               should be used for outputting the result tree.  Other non-namespaced
  182.               values may be used, such as "xhtml", but, if accepted, the handling
  183.               of such values is implementation defined.  If any of the method values
  184.               are not accepted and are not namespace qualified,
  185.               then {@link javax.xml.transform.Transformer#setOutputProperty}
  186.               or {@link javax.xml.transform.Transformer#setOutputProperties} will
  187.               throw a {@link java.lang.IllegalArgumentException}.
  188.               See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link>
  189.             </td>
  190.           </tr>
  191.           <tr><td>omit-xml-declaration</td>
  192.             <td></td>
  193.             <td>
  194.               <code>omit-xml-declaration</code> specifies whether the XSLT
  195.               processor should output an XML declaration; the value must be
  196.               <code>yes</code> or <code>no</code>.
  197.               See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link>
  198.             </td>
  199.           </tr>
  200.           <tr><td>standalone</td>
  201.             <td></td>
  202.             <td>
  203.               <code>standalone</code> specifies whether the Transformer
  204.               should output a standalone document declaration; the value must be
  205.               <code>yes</code> or <code>no</code>.
  206.               See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link>
  207.             </td>
  208.           </tr>
  209.           <tr><td>version</td>
  210.             <td>
  211.             </td>
  212.             <td>
  213.               <code>version</code> specifies the version of the output
  214.               method.
  215.               When the output method is "xml", the version value specifies the
  216.               version of XML to be used for outputting the result tree. The default
  217.               value for the xml output method is 1.0. When the output method is
  218.               "html", the version value indicates the version of the HTML.
  219.               The default value for the xml output method is 4.0, which specifies
  220.               that the result should be output as HTML conforming to the HTML 4.0
  221.               Recommendation [HTML].  If the output method is "text", the version
  222.               property is ignored.
  223.               See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link>
  224.             </td>
  225.           </tr>
  226.         </table>
  227.         <note>
  228.           Former property <code>buffer-size</code> is deprecated, and is ignored.
  229.         </note>
  230.         <p>
  231.           The XML Serializer sets the <code>method</code> property
  232.           to <code>xml</code>.
  233.         </p>
  234.       </s2>
  235.       <s2 title="Pipeline Usage">
  236.       <p>
  237.         Using the XML Serializer in a pipeline is just setting the 
  238.         serializer type to xml. 
  239.         The following code snippet uses the XML Serializer:
  240.       </p>
  241.       <source><![CDATA[
  242. ...
  243. <map:match pattern="*.xml">
  244. <map:generate...
  245. ...
  246. <map:serialize type="xml"/>
  247. ...
  248.       ]]></source>
  249.       </s2>
  250.       <s2 title="Further Reading">
  251.         <p>
  252.           The XML serializer is usable for serializing any SAX events
  253.           to a plain xml output. The various xml documents 
  254.           requires in most cases a proper configuration of following
  255.           parameters
  256.         </p>
  257.         <ul>
  258.           <li>doctype-public</li>
  259.           <li>doctype-system</li>
  260.         </ul>
  261.         <p>
  262.           Moreover the mime-type, and name attribute of the serializer definition
  263.           shall be set propertly.
  264.         </p>
  265.         <p>
  266.           Read the XML serializer configuration user documentation
  267.           for
  268.           <link href="svgxml-serializer.html">SVG/XML</link>,
  269.           and
  270.           <link href="wap-serializer.html">WML</link> in order
  271.           to understand using the XML serialiazer for 
  272.           serializing to some specific XML content type.
  273.         </p>
  274.       </s2>
  275.     </s1>
  276.   </body>
  277. </document>
  278.  
  279.