286N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 286N/A * This code is free software; you can redistribute it and/or modify it 286N/A * under the terms of the GNU General Public License version 2 only, as 286N/A * published by the Free Software Foundation. Oracle designates this 286N/A * particular file as subject to the "Classpath" exception as provided 286N/A * by Oracle in the LICENSE file that accompanied this code. 286N/A * This code is distributed in the hope that it will be useful, but WITHOUT 286N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 286N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 286N/A * version 2 for more details (a copy is included in the LICENSE file that 286N/A * accompanied this code). 286N/A * You should have received a copy of the GNU General Public License version 286N/A * 2 along with this work; if not, write to the Free Software Foundation, 286N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 286N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 286N/A * or visit www.oracle.com if you need additional information or have any 286N/A * This file is available under and governed by the GNU General Public 286N/A * License version 2 only, as published by the Free Software Foundation. 286N/A * However, the following notice accompanied the original version of this 286N/A * file and, per its terms, should not be removed: 286N/A * Copyright (c) 2004 World Wide Web Consortium, 286N/A * (Massachusetts Institute of Technology, European Research Consortium for 286N/A * Informatics and Mathematics, Keio University). All Rights Reserved. This 286N/A * work is distributed under the W3C(r) Software License [1] in the hope that 286N/A * it will be useful, but WITHOUT ANY WARRANTY; without even the implied 286N/A * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 286N/A * A <code>LSSerializer</code> provides an API for serializing (writing) a 286N/A * DOM document out into XML. The XML data is written to a string or an 286N/A * output stream. Any changes or fixups made during the serialization affect 286N/A * only the serialized data. The <code>Document</code> object and its 286N/A * children are never altered by the serialization operation. 286N/A * allows empty strings as a real namespace URI. If the 286N/A * <code>namespaceURI</code> of a <code>Node</code> is empty string, the 286N/A * serialization will treat them as <code>null</code>, ignoring the prefix 286N/A * <p> <code>LSSerializer</code> accepts any node type for serialization. For 286N/A * nodes of type <code>Document</code> or <code>Entity</code>, well-formed 286N/A * XML will be created when possible (well-formedness is guaranteed if the 286N/A * document or entity comes from a parse operation and is unchanged since it 286N/A * was created). The serialized output for these node types is either as a 286N/A * XML document or an External XML Entity, respectively, and is acceptable 286N/A * input for an XML parser. For all other types of nodes the serialized form 286N/A * is implementation dependent. 286N/A * <p>Within a <code>Document</code>, <code>DocumentFragment</code>, or 286N/A * <code>Entity</code> being serialized, <code>Nodes</code> are processed as 286N/A * <li> <code>Document</code> nodes are written, including the XML 286N/A * declaration (unless the parameter "xml-declaration" is set to 286N/A * <code>false</code>) and a DTD subset, if one exists in the DOM. Writing a 286N/A * <code>Document</code> node serializes the entire document. 286N/A * <code>Entity</code> nodes, when written directly by 286N/A * <code>LSSerializer.write</code>, outputs the entity expansion but no 286N/A * namespace fixup is done. The resulting output will be valid as an 286N/A * entities</a>" is set to <code>true</code>, <code>EntityReference</code> nodes are 286N/A * serialized as an entity reference of the form " 286N/A * <code>&entityName;</code>" in the output. Child nodes (the expansion) 286N/A * entities</a>" is set to <code>false</code>, only the children of the entity reference 286N/A * are serialized. <code>EntityReference</code> nodes with no children (no 286N/A * corresponding <code>Entity</code> node or the corresponding 286N/A * <code>Entity</code> nodes have no children) are always serialized. 286N/A * <code>CDATAsections</code> containing content characters that cannot be 286N/A * represented in the specified output encoding are handled according to the 286N/A * split-cdata-sections</a>" parameter. If the parameter is set to <code>true</code>, 286N/A * <code>CDATAsections</code> are split, and the unrepresentable characters 286N/A * are serialized as numeric character references in ordinary content. The 286N/A * exact position and number of splits is not specified. If the parameter 286N/A * is set to <code>false</code>, unrepresentable characters in a 286N/A * <code>CDATAsection</code> are reported as 286N/A * well-formed</a>" is set to <code>true</code>. The error is not recoverable - there is no 286N/A * mechanism for supplying alternative characters and continuing with the 286N/A * <li> <code>DocumentFragment</code> nodes are serialized by 286N/A * serializing the children of the document fragment in the order they 286N/A * appear in the document fragment. 286N/A * <li> All other node types (Element, Text, 286N/A * etc.) are serialized to their corresponding XML source form. 286N/A * <p ><b>Note:</b> The serialization of a <code>Node</code> does not always 286N/A * generate a well-formed XML document, i.e. a <code>LSParser</code> might 286N/A * throw fatal errors when parsing the resulting serialization. 286N/A * <p> Within the character data of a document (outside of markup), any 286N/A * characters that cannot be represented directly are replaced with 286N/A * character references. Occurrences of '<' and '&' are replaced by 286N/A * the predefined entities &lt; and &amp;. The other predefined 286N/A * entities (&gt;, &apos;, and &quot;) might not be used, except 286N/A * where needed (e.g. using &gt; in cases such as ']]>'). Any 286N/A * characters that cannot be represented directly in the output character 286N/A * encoding are serialized as numeric character references (and since 286N/A * character encoding standards commonly use hexadecimal representations of 286N/A * characters, using the hexadecimal representation when serializing 286N/A * character references is encouraged). 286N/A * <p> To allow attribute values to contain both single and double quotes, the 286N/A * apostrophe or single-quote character (') may be represented as 286N/A * "&apos;", and the double-quote character (") as "&quot;". New 286N/A * line characters and other characters that cannot be represented directly 286N/A * in attribute values in the output character encoding are serialized as a 286N/A * numeric character reference. 286N/A * <p> Within markup, but outside of attributes, any occurrence of a character 286N/A * that cannot be represented in the output character encoding is reported 286N/A * as a <code>DOMError</code> fatal error. An example would be serializing 286N/A * the element <LaCa\u00f1ada/> with <code>encoding="us-ascii"</code>. 286N/A * This will result with a generation of a <code>DOMError</code> 286N/A * normalize-characters</a>" on <code>LSSerializer</code> to true, character normalization is 286N/A * data to be serialized, both markup and character data. The character 286N/A * normalization process affects only the data as it is being written; it 286N/A * does not alter the DOM's view of the document after serialization has 286N/A * <p> Implementations are required to support the encodings "UTF-8", 286N/A * "UTF-16", "UTF-16BE", and "UTF-16LE" to guarantee that data is 286N/A * serializable in all encodings that are required to be supported by all 286N/A * XML parsers. When the encoding is UTF-8, whether or not a byte order mark 286N/A * is serialized, or if the output is big-endian or little-endian, is 286N/A * implementation dependent. When the encoding is UTF-16, whether or not the 286N/A * output is big-endian or little-endian is implementation dependent, but a 286N/A * Byte Order Mark must be generated for non-character outputs, such as 286N/A * <code>LSOutput.byteStream</code> or <code>LSOutput.systemId</code>. If 286N/A * the Byte Order Mark is not generated, a "byte-order-mark-needed" warning 286N/A * is reported. When the encoding is UTF-16LE or UTF-16BE, the output is 286N/A * big-endian (UTF-16BE) or little-endian (UTF-16LE) and the Byte Order Mark 286N/A * is not be generated. In all cases, the encoding declaration, if 286N/A * generated, will correspond to the encoding used during the serialization 286N/A * (e.g. <code>encoding="UTF-16"</code> will appear if UTF-16 was 286N/A * <p> Namespaces are fixed up during serialization, the serialization process 286N/A * will verify that namespace declarations, namespace prefixes and the 286N/A * namespace URI associated with elements and attributes are consistent. If 286N/A * inconsistencies are found, the serialized form of the document will be 286N/A * altered to remove them. The method used for doing the namespace fixup 286N/A * while serializing a document is the algorithm defined in Appendix B.1, 286N/A * <p> While serializing a document, the parameter "discard-default-content" 286N/A * controls whether or not non-specified data is serialized. 286N/A * <p> While serializing, errors and warnings are reported to the application 286N/A * error-handler</a>" parameter). This specification does in no way try to define all possible 286N/A * errors and warnings that can occur while serializing a DOM node, but some 286N/A * common error and warning cases are defined. The types ( 286N/A * <code>DOMError.type</code>) of errors and warnings defined by this 286N/A * <dt><code>"no-output-specified" [fatal]</code></dt> 286N/A * writing to a <code>LSOutput</code> if no output is specified in the 286N/A * <code>LSOutput</code>. </dd> 286N/A * <code>"unbound-prefix-in-entity-reference" [fatal]</code> </dt> 286N/A * namespaces</a>" is set to <code>true</code> and an entity whose replacement text 286N/A * contains unbound namespace prefixes is referenced in a location where 286N/A * there are no bindings for the namespace prefixes. </dd> 286N/A * <code>"unsupported-encoding" [fatal]</code></dt> 286N/A * <dd> Raised if an unsupported 286N/A * encoding is encountered. </dd> 286N/A * <p> In addition to raising the defined errors and warnings, implementations 286N/A * are expected to raise implementation specific errors and warnings for any 286N/A * other error and warning cases such as IO errors (file not found, 286N/A * permission denied,...) and so on. 286N/Aand Save Specification</a>. 286N/A * The <code>DOMConfiguration</code> object used by the 286N/A * <code>LSSerializer</code> when serializing a DOM node. 286N/A * , the <code>DOMConfiguration</code> objects for 286N/A * <code>LSSerializer</code> adds, or modifies, the following 286N/A * <dt><code>"canonical-form"</code></dt> 286N/A * <dt><code>true</code></dt> 286N/A * , setting this parameter to <code>true</code> will set the parameters 286N/A * "format-pretty-print", "discard-default-content", and "xml-declaration 286N/A * ", to <code>false</code>. Setting one of those parameters to 286N/A * <code>true</code> will set this parameter to <code>false</code>. 286N/A * Serializing an XML 1.1 document when "canonical-form" is 286N/A * <code>true</code> will generate a fatal error. </dd> 286N/A * <dt><code>false</code></dt> 286N/A * <dd>[<em>required</em>] (<em>default</em>) Do not canonicalize the output. </dd> 286N/A * <dt><code>"discard-default-content"</code></dt> 286N/A * <code>true</code></dt> 286N/A * <dd>[<em>required</em>] (<em>default</em>) Use the <code>Attr.specified</code> attribute to decide what attributes 286N/A * should be discarded. Note that some implementations might use 286N/A * whatever information available to the implementation (i.e. XML 286N/A * schema, DTD, the <code>Attr.specified</code> attribute, and so on) to 286N/A * determine what attributes and content to discard if this parameter is 286N/A * set to <code>true</code>. </dd> 286N/A * <dt><code>false</code></dt> 286N/A * <dd>[<em>required</em>]Keep all attributes and all content.</dd> 286N/A * <dt><code>"format-pretty-print"</code></dt> 286N/A * <code>true</code></dt> 286N/A * <dd>[<em>optional</em>] Formatting the output by adding whitespace to produce a pretty-printed, 286N/A * indented, human-readable form. The exact form of the transformations 286N/A * is not specified by this specification. Pretty-printing changes the 286N/A * content of the document and may affect the validity of the document, 286N/A * validating implementations should preserve validity. </dd> 286N/A * <code>false</code></dt> 286N/A * <dd>[<em>required</em>] (<em>default</em>) Don't pretty-print the result. </dd> 286N/A * <code>"ignore-unknown-character-denormalizations"</code> </dt> 286N/A * <code>true</code></dt> 286N/A * supported, a character is encountered for which the normalization 286N/A * properties cannot be determined, then raise a 286N/A * <code>"unknown-character-denormalization"</code> warning (instead of 286N/A * raising an error, if this parameter is not set) and ignore any 286N/A * possible denormalizations caused by these characters. </dd> 286N/A * <code>false</code></dt> 286N/A * <dd>[<em>optional</em>] Report a fatal error if a character is encountered for which the 286N/A * processor cannot determine the normalization properties. </dd> 286N/A * <code>"normalize-characters"</code></dt> 286N/A * <dd> This parameter is equivalent to 286N/A * . Unlike in the Core, the default value for this parameter is 286N/A * <code>true</code>. While DOM implementations are not required to 286N/A * parameter must be activated by default if supported. </dd> 286N/A * <code>"xml-declaration"</code></dt> 286N/A * <dt><code>true</code></dt> 286N/A * <dd>[<em>required</em>] (<em>default</em>) If a <code>Document</code>, <code>Element</code>, or <code>Entity</code> 286N/A * node is serialized, the XML declaration, or text declaration, should 286N/A * document is a Level 3 document and the version is non-null, otherwise 286N/A * use the value "1.0"), and the output encoding (see 286N/A * <code>LSSerializer.write</code> for details on how to find the output 286N/A * encoding) are specified in the serialized XML declaration. </dd> 286N/A * <code>false</code></dt> 286N/A * <dd>[<em>required</em>] Do not serialize the XML and text declarations. Report a 286N/A * <code>"xml-declaration-needed"</code> warning if this will cause 286N/A * encoding would be needed to be able to re-parse the serialized data). </dd> 286N/A * The end-of-line sequence of characters to be used in the XML being 286N/A * written out. Any string is supported, but XML treats only a certain 286N/A * set of characters sequence as end-of-line (See section 2.11, 286N/A * serialized content is XML 1.0 or section 2.11, "End-of-Line Handling" 286N/A * serialized content is XML 1.1). Using other character sequences than 286N/A * the recommended ones can result in a document that is either not 286N/A * serializable or not well-formed). 286N/A * <br> On retrieval, the default value of this attribute is the 286N/A * implementation specific default end-of-line sequence. DOM 286N/A * implementations should choose the default to match the usual 286N/A * convention for text files in the environment being used. 286N/A * Implementations must choose a default sequence that matches one of 286N/A * those allowed by XML 1.0 or XML 1.1, depending on the serialized 286N/A * content. Setting this attribute to <code>null</code> will reset its 286N/A * value to the default value. 286N/A * The end-of-line sequence of characters to be used in the XML being 286N/A * written out. Any string is supported, but XML treats only a certain 286N/A * set of characters sequence as end-of-line (See section 2.11, 286N/A * serialized content is XML 1.0 or section 2.11, "End-of-Line Handling" 286N/A * serialized content is XML 1.1). Using other character sequences than 286N/A * the recommended ones can result in a document that is either not 286N/A * serializable or not well-formed). 286N/A * <br> On retrieval, the default value of this attribute is the 286N/A * implementation specific default end-of-line sequence. DOM 286N/A * implementations should choose the default to match the usual 286N/A * convention for text files in the environment being used. 286N/A * Implementations must choose a default sequence that matches one of 286N/A * those allowed by XML 1.0 or XML 1.1, depending on the serialized 286N/A * content. Setting this attribute to <code>null</code> will reset its 286N/A * value to the default value. 286N/A * When the application provides a filter, the serializer will call out 286N/A * to the filter before serializing each Node. The filter implementation 286N/A * can choose to remove the node from the stream or to terminate the 286N/A * <br> The filter is invoked after the operations requested by the 286N/A * <code>DOMConfiguration</code> parameters have been applied. For 286N/A * cdata-sections</a>" is set to <code>false</code>. 286N/A * When the application provides a filter, the serializer will call out 286N/A * to the filter before serializing each Node. The filter implementation 286N/A * can choose to remove the node from the stream or to terminate the 286N/A * <br> The filter is invoked after the operations requested by the 286N/A * <code>DOMConfiguration</code> parameters have been applied. For 286N/A * cdata-sections</a>" is set to <code>false</code>. 286N/A * Serialize the specified node as described above in the general 286N/A * description of the <code>LSSerializer</code> interface. The output is 286N/A * written to the supplied <code>LSOutput</code>. 286N/A * <br> When writing to a <code>LSOutput</code>, the encoding is found by 286N/A * looking at the encoding information that is reachable through the 286N/A * <code>LSOutput</code> and the item to be written (or its owner 286N/A * document) in this order: 286N/A * <li> <code>LSOutput.encoding</code>, 286N/A * <code>Document.inputEncoding</code>, 286N/A * <br> If no encoding is reachable through the above properties, a 286N/A * default encoding of "UTF-8" will be used. If the specified encoding 286N/A * is not supported an "unsupported-encoding" fatal error is raised. 286N/A * <br> If no output is specified in the <code>LSOutput</code>, a 286N/A * "no-output-specified" fatal error is raised. 286N/A * <br> The implementation is responsible of associating the appropriate 286N/A * media type with the serialized data. 286N/A * <br> When writing to a HTTP URI, a HTTP PUT is performed. When writing 286N/A * to other types of URIs, the mechanism for writing the data to the URI 286N/A * is implementation dependent. 286N/A * @param nodeArg The node to serialize. 286N/A * @param destination The destination for the serialized DOM. 286N/A * @return Returns <code>true</code> if <code>node</code> was 286N/A * successfully serialized. Return <code>false</code> in case the 286N/A * normal processing stopped but the implementation kept serializing 286N/A * the document; the result of the serialization being implementation 286N/A * @exception LSException 286N/A * SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to 286N/A * serialize the node. DOM applications should attach a 286N/A * error-handler</a>" if they wish to get details on the error. 286N/A * A convenience method that acts as if <code>LSSerializer.write</code> 286N/A * was called with a <code>LSOutput</code> with no encoding specified 286N/A * and <code>LSOutput.systemId</code> set to the <code>uri</code> 286N/A * @param nodeArg The node to serialize. 286N/A * @param uri The URI to write to. 286N/A * @return Returns <code>true</code> if <code>node</code> was 286N/A * successfully serialized. Return <code>false</code> in case the 286N/A * normal processing stopped but the implementation kept serializing 286N/A * the document; the result of the serialization being implementation 286N/A * @exception LSException 286N/A * SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to 286N/A * serialize the node. DOM applications should attach a 286N/A * error-handler</a>" if they wish to get details on the error. 286N/A * Serialize the specified node as described above in the general 286N/A * description of the <code>LSSerializer</code> interface. The output is 286N/A * written to a <code>DOMString</code> that is returned to the caller. 286N/A * The encoding used is the encoding of the <code>DOMString</code> type, 286N/A * i.e. UTF-16. Note that no Byte Order Mark is generated in a 286N/A * <code>DOMString</code> object. 286N/A * @param nodeArg The node to serialize. 286N/A * @return Returns the serialized data. 286N/A * @exception DOMException 286N/A * DOMSTRING_SIZE_ERR: Raised if the resulting string is too long to 286N/A * fit in a <code>DOMString</code>. 286N/A * @exception LSException 286N/A * SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to 286N/A * serialize the node. DOM applications should attach a 286N/A * error-handler</a>" if they wish to get details on the error.