lsserializer.java

gcc的组建

/*
 * Copyright (c) 2004 World Wide Web Consortium,
 *
 * (Massachusetts Institute of Technology, European Research Consortium for
 * Informatics and Mathematics, Keio University). All Rights Reserved. This
 * work is distributed under the W3C(r) Software License [1] in the hope that
 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
 */

package org.w3c.dom.ls;

import org.w3c.dom.DOMConfiguration;
import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

/**
 *  A <code>LSSerializer</code> provides an API for serializing (writing) a 
 * DOM document out into XML. The XML data is written to a string or an 
 * output stream. Any changes or fixups made during the serialization affect 
 * only the serialized data. The <code>Document</code> object and its 
 * children are never altered by the serialization operation. 
 * <p> During serialization of XML data, namespace fixup is done as defined in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
 * , Appendix B. [<a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>DOM Level 2 Core</a>]
 *  allows empty strings as a real namespace URI. If the 
 * <code>namespaceURI</code> of a <code>Node</code> is empty string, the 
 * serialization will treat them as <code>null</code>, ignoring the prefix 
 * if any. 
 * <p> <code>LSSerializer</code> accepts any node type for serialization. For 
 * nodes of type <code>Document</code> or <code>Entity</code>, well-formed 
 * XML will be created when possible (well-formedness is guaranteed if the 
 * document or entity comes from a parse operation and is unchanged since it 
 * was created). The serialized output for these node types is either as a 
 * XML document or an External XML Entity, respectively, and is acceptable 
 * input for an XML parser. For all other types of nodes the serialized form 
 * is implementation dependent. 
 * <p>Within a <code>Document</code>, <code>DocumentFragment</code>, or 
 * <code>Entity</code> being serialized, <code>Nodes</code> are processed as 
 * follows
 * <ul>
 * <li> <code>Document</code> nodes are written, including the XML 
 * declaration (unless the parameter "xml-declaration" is set to 
 * <code>false</code>) and a DTD subset, if one exists in the DOM. Writing a 
 * <code>Document</code> node serializes the entire document. 
 * </li>
 * <li> 
 * <code>Entity</code> nodes, when written directly by 
 * <code>LSSerializer.write</code>, outputs the entity expansion but no 
 * namespace fixup is done. The resulting output will be valid as an 
 * external entity. 
 * </li>
 * <li> If the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'>
 * entities</a>" is set to <code>true</code>, <code>EntityReference</code> nodes are 
 * serialized as an entity reference of the form "
 * <code>&amp;entityName;</code>" in the output. Child nodes (the expansion) 
 * of the entity reference are ignored. If the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'>
 * entities</a>" is set to <code>false</code>, only the children of the entity reference 
 * are serialized. <code>EntityReference</code> nodes with no children (no 
 * corresponding <code>Entity</code> node or the corresponding 
 * <code>Entity</code> nodes have no children) are always serialized. 
 * </li>
 * <li> 
 * <code>CDATAsections</code> containing content characters that cannot be 
 * represented in the specified output encoding are handled according to the 
 * "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-split-cdata-sections'>
 * split-cdata-sections</a>" parameter.  If the parameter is set to <code>true</code>, 
 * <code>CDATAsections</code> are split, and the unrepresentable characters 
 * are serialized as numeric character references in ordinary content. The 
 * exact position and number of splits is not specified.  If the parameter 
 * is set to <code>false</code>, unrepresentable characters in a 
 * <code>CDATAsection</code> are reported as 
 * <code>"wf-invalid-character"</code> errors if the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-well-formed'>
 * well-formed</a>" is set to <code>true</code>. The error is not recoverable - there is no 
 * mechanism for supplying alternative characters and continuing with the 
 * serialization. 
 * </li>
 * <li> <code>DocumentFragment</code> nodes are serialized by 
 * serializing the children of the document fragment in the order they 
 * appear in the document fragment. 
 * </li>
 * <li> All other node types (Element, Text, 
 * etc.) are serialized to their corresponding XML source form. 
 * </li>
 * </ul>
 * <p ><b>Note:</b>  The serialization of a <code>Node</code> does not always 
 * generate a well-formed XML document, i.e. a <code>LSParser</code> might 
 * throw fatal errors when parsing the resulting serialization. 
 * <p> Within the character data of a document (outside of markup), any 
 * characters that cannot be represented directly are replaced with 
 * character references. Occurrences of '&lt;' and '&amp;' are replaced by 
 * the predefined entities &amp;lt; and &amp;amp;. The other predefined 
 * entities (&amp;gt;, &amp;apos;, and &amp;quot;) might not be used, except 
 * where needed (e.g. using &amp;gt; in cases such as ']]&gt;'). Any 
 * characters that cannot be represented directly in the output character 
 * encoding are serialized as numeric character references (and since 
 * character encoding standards commonly use hexadecimal representations of 
 * characters, using the hexadecimal representation when serializing 
 * character references is encouraged). 
 * <p> To allow attribute values to contain both single and double quotes, the 
 * apostrophe or single-quote character (') may be represented as 
 * "&amp;apos;", and the double-quote character (")  as "&amp;quot;". New 
 * line characters and other characters that cannot be represented directly 
 * in attribute values in the output character encoding are serialized as a 
 * numeric character reference. 
 * <p> Within markup, but outside of attributes, any occurrence of a character 
 * that cannot be represented in the output character encoding is reported 
 * as a <code>DOMError</code> fatal error. An example would be serializing 
 * the element &lt;LaCa\u00f1ada/&gt; with <code>encoding="us-ascii"</code>. 
 * This will result with a generation of a <code>DOMError</code> 
 * "wf-invalid-character-in-node-name" (as proposed in "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-well-formed'>
 * well-formed</a>"). 
 * <p> When requested by setting the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-normalize-characters'>
 * normalize-characters</a>" on <code>LSSerializer</code> to true, character normalization is 
 * performed according to the definition of <a href='http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-fullnorm'>fully 
 * normalized</a> characters included in appendix E of [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>] on all 
 * data to be serialized, both markup and character data. The character 
 * normalization process affects only the data as it is being written; it 
 * does not alter the DOM's view of the document after serialization has 
 * completed. 
 * <p> Implementations are required to support the encodings "UTF-8", 
 * "UTF-16", "UTF-16BE", and "UTF-16LE" to guarantee that data is 
 * serializable in all encodings that are required to be supported by all 
 * XML parsers. When the encoding is UTF-8, whether or not a byte order mark 
 * is serialized, or if the output is big-endian or little-endian, is 
 * implementation dependent. When the encoding is UTF-16, whether or not the 
 * output is big-endian or little-endian is implementation dependent, but a 
 * Byte Order Mark must be generated for non-character outputs, such as 
 * <code>LSOutput.byteStream</code> or <code>LSOutput.systemId</code>. If 
 * the Byte Order Mark is not generated, a "byte-order-mark-needed" warning 
 * is reported. When the encoding is UTF-16LE or UTF-16BE, the output is 
 * big-endian (UTF-16BE) or little-endian (UTF-16LE) and the Byte Order Mark 
 * is not be generated. In all cases, the encoding declaration, if 
 * generated, will correspond to the encoding used during the serialization 
 * (e.g. <code>encoding="UTF-16"</code> will appear if UTF-16 was 
 * requested). 
 * <p> Namespaces are fixed up during serialization, the serialization process 
 * will verify that namespace declarations, namespace prefixes and the 
 * namespace URI associated with elements and attributes are consistent. If 
 * inconsistencies are found, the serialized form of the document will be 
 * altered to remove them. The method used for doing the namespace fixup 
 * while serializing a document is the algorithm defined in Appendix B.1, 
 * "Namespace normalization", of [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
 * . 
 * <p> While serializing a document, the parameter "discard-default-content" 
 * controls whether or not non-specified data is serialized. 
 * <p> While serializing, errors and warnings are reported to the application 
 * through the error handler (<code>LSSerializer.domConfig</code>'s "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
 * error-handler</a>" parameter). This specification does in no way try to define all possible 
 * errors and warnings that can occur while serializing a DOM node, but some 
 * common error and warning cases are defined. The types (
 * <code>DOMError.type</code>) of errors and warnings defined by this 
 * specification are: 
 * <dl>
 * <dt><code>"no-output-specified" [fatal]</code></dt>
 * <dd> Raised when 
 * writing to a <code>LSOutput</code> if no output is specified in the 
 * <code>LSOutput</code>. </dd>
 * <dt> 
 * <code>"unbound-prefix-in-entity-reference" [fatal]</code> </dt>
 * <dd> Raised if the 
 * configuration parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespaces'>
 * namespaces</a>" is set to <code>true</code> and an entity whose replacement text 
 * contains unbound namespace prefixes is referenced in a location where 
 * there are no bindings for the namespace prefixes. </dd>
 * <dt>
 * <code>"unsupported-encoding" [fatal]</code></dt>
 * <dd> Raised if an unsupported 
 * encoding is encountered. </dd>
 * </dl> 
 * <p> In addition to raising the defined errors and warnings, implementations 
 * are expected to raise implementation specific errors and warnings for any 
 * other error and warning cases such as IO errors (file not found, 
 * permission denied,...) and so on. 
 * <p>See also the <a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407'>Document Object Model (DOM) Level 3 Load
and Save Specification</a>.
 */
public interface LSSerializer {
    /**
     *  The <code>DOMConfiguration</code> object used by the 
     * <code>LSSerializer</code> when serializing a DOM node. 
     * <br> In addition to the parameters recognized by the <a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMConfiguration'>
     * DOMConfiguration</a> interface defined in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
     * , the <code>DOMConfiguration</code> objects for 
     * <code>LSSerializer</code> adds, or modifies, the following 
     * parameters: 
     * <dl>
     * <dt><code>"canonical-form"</code></dt>
     * <dd>
     * <dl>
     * <dt><code>true</code></dt>
     * <dd>[<em>optional</em>] Writes the document according to the rules specified in [<a href='http://www.w3.org/TR/2001/REC-xml-c14n-20010315'>Canonical XML</a>]. 
     * In addition to the behavior described in "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-canonical-form'>
     * canonical-form</a>" [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
     * , setting this parameter to <code>true</code> will set the parameters 
     * "format-pretty-print", "discard-default-content", and "xml-declaration
     * ", to <code>false</code>. Setting one of those parameters to 
     * <code>true</code> will set this parameter to <code>false</code>. 
     * Serializing an XML 1.1 document when "canonical-form" is 
     * <code>true</code> will generate a fatal error. </dd>
     * <dt><code>false</code></dt>
     * <dd>[<em>required</em>] (<em>default</em>) Do not canonicalize the output. </dd>
     * </dl></dd>
     * <dt><code>"discard-default-content"</code></dt>
     * <dd>
     * <dl>
     * <dt>
     * <code>true</code></dt>
     * <dd>[<em>required</em>] (<em>default</em>) Use the <code>Attr.specified</code> attribute to decide what attributes 
     * should be discarded. Note that some implementations might use 
     * whatever information available to the implementation (i.e. XML 
     * schema, DTD, the <code>Attr.specified</code> attribute, and so on) to 
     * determine what attributes and content to discard if this parameter is 
     * set to <code>true</code>. </dd>
     * <dt><code>false</code></dt>
     * <dd>[<em>required</em>]Keep all attributes and all content.</dd>
     * </dl></dd>
     * <dt><code>"format-pretty-print"</code></dt>