| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd"> |
| |
| <document> |
| <header> |
| <title>XML Serializer</title> |
| <version>0.9</version> |
| <type>Technical document</type> |
| <authors> |
| <person name="Carsten Ziegeler" email="cziegeler@apache.org"/> |
| <person name="Bernhard Huber" email="huber@apache.org"/> |
| </authors> |
| <abstract>This document describes the xml serializer of Cocoon.</abstract> |
| </header> |
| <body> |
| <s1 title="XML Serializer"> |
| <p> |
| The xml serializer is the simplest possible serializer. |
| It generates an xml document from the sax events. |
| This serializer is used for serializing to any XML document |
| format, ie. SVG, WML, VRML, et. al. |
| </p> |
| <ul> |
| <li>Name : xml</li> |
| <li>Class: org.apache.cocoon.serialization.XMLSerializer</li> |
| <li>Cacheable: yes.</li> |
| </ul> |
| <s2 title="Sitemap Configuration"> |
| <p> |
| The XML Serializer is declared in the sitemap serializers section. |
| </p> |
| <source><![CDATA[ |
| <map:serializers ... |
| ... |
| <map:serializer name="xml" |
| src="org.apache.cocoon.serialization.XMLSerializer" |
| mime-type="text/xml" |
| logger="sitemap.serializer.xml" |
| pool-grow="4" pool-max="32" pool-min="4"> |
| <!-- serializer configurations --> |
| ... |
| </map:serializer> |
| ... |
| ]]></source> |
| <p> |
| XML Serializer can be configured, specifying elements inside of |
| the <map:serializer> body. |
| </p> |
| <s3 title="Configuration Example"> |
| <p> |
| The following XML Serializer snippet is setting |
| encoding configuration for the XML Serializer |
| </p> |
| <source><![CDATA[ |
| <map:serializer name="xml" |
| src="org.apache.cocoon.serialization.XMLSerializer" |
| mime-type="text/xml"> |
| <encoding>ISO-8859-1</encoding> |
| </map:serializer> |
| ]]></source> |
| <p> |
| This configuration will result in xml output of the form |
| </p> |
| <source><![CDATA[ |
| <?xml version="1.0" encoding="ISO-8859-1"?> |
| ... |
| ]]></source> |
| </s3> |
| <p> |
| The XML Serializer accepts following configuration parameters. |
| These configurations are not Xalan specific. |
| </p> |
| <!-- |
| # |
| # Specify defaults when method="xml". These defaults serve as a base for |
| # other defaults, such as output_html and output_text. |
| # |
| |
| # XSLT properties do not need namespace qualification. |
| method=xml |
| version=1.0 |
| encoding=UTF-8 |
| indent=no |
| omit-xml-declaration=no |
| standalone=no |
| media-type=text/xml |
| |
| # Xalan-specific output properties. These can be overridden in the stylesheet |
| # assigning a xalan namespace. For example: |
| # <xsl:stylesheet version="1.0" |
| # xmlns:xsl="http://www.w3.org/1999/XSL/Transform" |
| # xmlns:xalan="http://xml.apache.org/xslt"> |
| # <xsl:output method="html" encoding="UTF-8" |
| # xalan:content-handler="MyContentHandler"/> |
| # ... |
| # Note that the colon after the protocol needs to be escaped. |
| {http\u003a//xml.apache.org/xslt}indent-amount=0 |
| {http\u003a//xml.apache.org/xslt}content-handler=org.apache.xalan.serialize.SerializerToXML |
| |
| --> |
| <table> |
| <tr><th>Name</th><th>Xalan Default Value</th><th>Comment</th></tr> |
| <tr><td>cdata-section-elements</td> |
| <td>none</td> |
| <td><code>cdata-section-elements</code> specifies a whitespace delimited |
| list of the names of elements whose text node children should be output |
| using CDATA sections. |
| See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation.</link> |
| </td> |
| </tr> |
| <tr><td>doctype-public</td> |
| <td>none</td> |
| <td><code>doctype-public</code> specifies the public identifier |
| to be used in the document type declaration. |
| </td> |
| </tr> |
| <tr><td>doctype-system</td> |
| <td>none</td> |
| <td> |
| <code>doctype-system</code> specifies the system identifier |
| to be used in the document type declaration. |
| See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link> |
| </td> |
| </tr> |
| <tr><td>encoding</td> |
| <td>none</td> |
| <td><code>encoding</code> specifies the preferred character |
| encoding that the Transformer should use to encode sequences of |
| characters as sequences of bytes. The value of the attribute should be |
| treated case-insensitively. The value must only contain characters in |
| the range #x21 to #x7E (i.e., printable ASCII characters). The value |
| should either be a <code>charset</code> registered with the Internet |
| Assigned Numbers Authority <link href="#IANA">[IANA]</link>, |
| <link href="#RFC2278">[RFC2278]</link> or start with <code>X-</code>. |
| See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link> |
| </td> |
| </tr> |
| <tr><td>indent</td> |
| <td> |
| yes |
| </td> |
| <td> |
| A Flag for toggling indent. This flag toggles only if some elements |
| should trigger a line break. |
| </td> |
| </tr> |
| <tr><td>media-type</td> |
| <td> |
| </td> |
| <td> |
| <code>media-type</code> specifies the media type (MIME |
| content type) of the data that results from outputting the result |
| tree. The <code>charset</code> parameter should not be specified |
| explicitly; instead, when the top-level media type is |
| <code>text</code>, a <code>charset</code> parameter should be added |
| according to the character encoding actually used by the output |
| method. |
| See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link> |
| </td> |
| </tr> |
| <tr><td>method</td> |
| <td> |
| </td> |
| <td> |
| The method attribute identifies the overall method that |
| should be used for outputting the result tree. Other non-namespaced |
| values may be used, such as "xhtml", but, if accepted, the handling |
| of such values is implementation defined. If any of the method values |
| are not accepted and are not namespace qualified, |
| then {@link javax.xml.transform.Transformer#setOutputProperty} |
| or {@link javax.xml.transform.Transformer#setOutputProperties} will |
| throw a {@link java.lang.IllegalArgumentException}. |
| See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link> |
| </td> |
| </tr> |
| <tr><td>omit-xml-declaration</td> |
| <td></td> |
| <td> |
| <code>omit-xml-declaration</code> specifies whether the XSLT |
| processor should output an XML declaration; the value must be |
| <code>yes</code> or <code>no</code>. |
| See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link> |
| </td> |
| </tr> |
| <tr><td>standalone</td> |
| <td></td> |
| <td> |
| <code>standalone</code> specifies whether the Transformer |
| should output a standalone document declaration; the value must be |
| <code>yes</code> or <code>no</code>. |
| See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link> |
| </td> |
| </tr> |
| <tr><td>version</td> |
| <td> |
| </td> |
| <td> |
| <code>version</code> specifies the version of the output |
| method. |
| When the output method is "xml", the version value specifies the |
| version of XML to be used for outputting the result tree. The default |
| value for the xml output method is 1.0. When the output method is |
| "html", the version value indicates the version of the HTML. |
| The default value for the xml output method is 4.0, which specifies |
| that the result should be output as HTML conforming to the HTML 4.0 |
| Recommendation [HTML]. If the output method is "text", the version |
| property is ignored. |
| See <link href="http://www.w3.org/TR/xslt#output">section 16 of the XSL Transformations (XSLT) W3C Recommendation</link> |
| </td> |
| </tr> |
| </table> |
| <note> |
| Former property <code>buffer-size</code> is deprecated, and is ignored. |
| </note> |
| <p> |
| The XML Serializer sets the <code>method</code> property |
| to <code>xml</code>. |
| </p> |
| </s2> |
| <s2 title="Pipeline Usage"> |
| <p> |
| Using the XML Serializer in a pipeline is just setting the |
| serializer type to xml. |
| The following code snippet uses the XML Serializer: |
| </p> |
| <source><![CDATA[ |
| ... |
| <map:match pattern="*.xml"> |
| <map:generate... |
| ... |
| <map:serialize type="xml"/> |
| ... |
| ]]></source> |
| </s2> |
| <s2 title="Further Reading"> |
| <p> |
| The XML serializer is usable for serializing any SAX events |
| to a plain xml output. The various xml documents |
| requires in most cases a proper configuration of following |
| parameters |
| </p> |
| <ul> |
| <li>doctype-public</li> |
| <li>doctype-system</li> |
| </ul> |
| <p> |
| Moreover the mime-type, and name attribute of the serializer definition |
| shall be set propertly. |
| </p> |
| <p> |
| Read the XML serializer configuration user documentation |
| for |
| <link href="svgxml-serializer.html">SVG/XML</link>, |
| and |
| <link href="wap-serializer.html">WML</link> in order |
| to understand using the XML serialiazer for |
| serializing to some specific XML content type. |
| </p> |
| </s2> |
| </s1> |
| </body> |
| </document> |
| |