1320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/* 2320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Copyright (c) 2004 World Wide Web Consortium, 3320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 4320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * (Massachusetts Institute of Technology, European Research Consortium for 5320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Informatics and Mathematics, Keio University). All Rights Reserved. This 6320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * work is distributed under the W3C(r) Software License [1] in the hope that 7320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * it will be useful, but WITHOUT ANY WARRANTY; without even the implied 8320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 9320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 10320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 11320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 12320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 13320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpackage org.w3c.dom.ls; 14320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 15320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport org.w3c.dom.DOMConfiguration; 16320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport org.w3c.dom.DOMException; 177365de1056414750d0a7d1fdd26025fd247f0d04Jesse Wilsonimport org.w3c.dom.Node; 18320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 19320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/** 20f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * A <code>LSSerializer</code> provides an API for serializing (writing) a 21f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * DOM document out into XML. The XML data is written to a string or an 22f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * output stream. Any changes or fixups made during the serialization affect 23f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * only the serialized data. The <code>Document</code> object and its 24f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * children are never altered by the serialization operation. 25320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <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>] 26320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * , Appendix B. [<a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>DOM Level 2 Core</a>] 27f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * allows empty strings as a real namespace URI. If the 28f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>namespaceURI</code> of a <code>Node</code> is empty string, the 29f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serialization will treat them as <code>null</code>, ignoring the prefix 30f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * if any. 31f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> <code>LSSerializer</code> accepts any node type for serialization. For 32f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * nodes of type <code>Document</code> or <code>Entity</code>, well-formed 33f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * XML will be created when possible (well-formedness is guaranteed if the 34f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * document or entity comes from a parse operation and is unchanged since it 35f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * was created). The serialized output for these node types is either as a 36f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * XML document or an External XML Entity, respectively, and is acceptable 37f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * input for an XML parser. For all other types of nodes the serialized form 38f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is implementation dependent. 39f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p>Within a <code>Document</code>, <code>DocumentFragment</code>, or 40f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Entity</code> being serialized, <code>Nodes</code> are processed as 41320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * follows 42320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <ul> 43f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <li> <code>Document</code> nodes are written, including the XML 44f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * declaration (unless the parameter "xml-declaration" is set to 45f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>false</code>) and a DTD subset, if one exists in the DOM. Writing a 46f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Document</code> node serializes the entire document. 47320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 48f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <li> 49f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Entity</code> nodes, when written directly by 50f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSSerializer.write</code>, outputs the entity expansion but no 51f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * namespace fixup is done. The resulting output will be valid as an 52f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * external entity. 53320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 54320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <li> If the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'> 55f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * entities</a>" is set to <code>true</code>, <code>EntityReference</code> nodes are 56320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * serialized as an entity reference of the form " 57f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>&entityName;</code>" in the output. Child nodes (the expansion) 58320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * of the entity reference are ignored. If the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'> 59f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * entities</a>" is set to <code>false</code>, only the children of the entity reference 60f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * are serialized. <code>EntityReference</code> nodes with no children (no 61f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * corresponding <code>Entity</code> node or the corresponding 62f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Entity</code> nodes have no children) are always serialized. 63320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 64f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <li> 65f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>CDATAsections</code> containing content characters that cannot be 66f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * represented in the specified output encoding are handled according to the 67320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-split-cdata-sections'> 68f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * split-cdata-sections</a>" parameter. If the parameter is set to <code>true</code>, 69f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>CDATAsections</code> are split, and the unrepresentable characters 70f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * are serialized as numeric character references in ordinary content. The 71f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * exact position and number of splits is not specified. If the parameter 72f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is set to <code>false</code>, unrepresentable characters in a 73f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>CDATAsection</code> are reported as 74320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <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'> 75f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * well-formed</a>" is set to <code>true</code>. The error is not recoverable - there is no 76f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * mechanism for supplying alternative characters and continuing with the 77f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serialization. 78320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 79f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <li> <code>DocumentFragment</code> nodes are serialized by 80f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serializing the children of the document fragment in the order they 81f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * appear in the document fragment. 82320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 83f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <li> All other node types (Element, Text, 84f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * etc.) are serialized to their corresponding XML source form. 85320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 86320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </ul> 87f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p ><b>Note:</b> The serialization of a <code>Node</code> does not always 88f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * generate a well-formed XML document, i.e. a <code>LSParser</code> might 89f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * throw fatal errors when parsing the resulting serialization. 90f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> Within the character data of a document (outside of markup), any 91f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * characters that cannot be represented directly are replaced with 92f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * character references. Occurrences of '<' and '&' are replaced by 93f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the predefined entities &lt; and &amp;. The other predefined 94f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * entities (&gt;, &apos;, and &quot;) might not be used, except 95f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * where needed (e.g. using &gt; in cases such as ']]>'). Any 96f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * characters that cannot be represented directly in the output character 97f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * encoding are serialized as numeric character references (and since 98f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * character encoding standards commonly use hexadecimal representations of 99f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * characters, using the hexadecimal representation when serializing 100f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * character references is encouraged). 101f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> To allow attribute values to contain both single and double quotes, the 102f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * apostrophe or single-quote character (') may be represented as 103f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * "&apos;", and the double-quote character (") as "&quot;". New 104f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * line characters and other characters that cannot be represented directly 105f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * in attribute values in the output character encoding are serialized as a 106f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * numeric character reference. 107f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> Within markup, but outside of attributes, any occurrence of a character 108f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * that cannot be represented in the output character encoding is reported 109f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * as a <code>DOMError</code> fatal error. An example would be serializing 110f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the element <LaCa\u00f1ada/> with <code>encoding="us-ascii"</code>. 111f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * This will result with a generation of a <code>DOMError</code> 112320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * "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'> 113f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * well-formed</a>"). 114320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> When requested by setting the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-normalize-characters'> 115f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * normalize-characters</a>" on <code>LSSerializer</code> to true, character normalization is 116f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * performed according to the definition of <a href='http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-fullnorm'>fully 117f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 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 118f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * data to be serialized, both markup and character data. The character 119f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * normalization process affects only the data as it is being written; it 120f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * does not alter the DOM's view of the document after serialization has 121f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * completed. 122f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> Implementations are required to support the encodings "UTF-8", 123f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * "UTF-16", "UTF-16BE", and "UTF-16LE" to guarantee that data is 124f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serializable in all encodings that are required to be supported by all 125f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * XML parsers. When the encoding is UTF-8, whether or not a byte order mark 126f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is serialized, or if the output is big-endian or little-endian, is 127f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implementation dependent. When the encoding is UTF-16, whether or not the 128f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * output is big-endian or little-endian is implementation dependent, but a 129f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Byte Order Mark must be generated for non-character outputs, such as 130f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSOutput.byteStream</code> or <code>LSOutput.systemId</code>. If 131f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the Byte Order Mark is not generated, a "byte-order-mark-needed" warning 132f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is reported. When the encoding is UTF-16LE or UTF-16BE, the output is 133f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * big-endian (UTF-16BE) or little-endian (UTF-16LE) and the Byte Order Mark 134f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is not be generated. In all cases, the encoding declaration, if 135f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * generated, will correspond to the encoding used during the serialization 136f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * (e.g. <code>encoding="UTF-16"</code> will appear if UTF-16 was 137f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * requested). 138f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> Namespaces are fixed up during serialization, the serialization process 139f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * will verify that namespace declarations, namespace prefixes and the 140f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * namespace URI associated with elements and attributes are consistent. If 141f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * inconsistencies are found, the serialized form of the document will be 142f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * altered to remove them. The method used for doing the namespace fixup 143f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * while serializing a document is the algorithm defined in Appendix B.1, 144320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * "Namespace normalization", of [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] 145f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * . 146f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> While serializing a document, the parameter "discard-default-content" 147f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * controls whether or not non-specified data is serialized. 148f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> While serializing, errors and warnings are reported to the application 149320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 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'> 150f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * error-handler</a>" parameter). This specification does in no way try to define all possible 151f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * errors and warnings that can occur while serializing a DOM node, but some 152320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * common error and warning cases are defined. The types ( 153f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DOMError.type</code>) of errors and warnings defined by this 154f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * specification are: 155320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 156320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"no-output-specified" [fatal]</code></dt> 157f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> Raised when 158f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * writing to a <code>LSOutput</code> if no output is specified in the 159320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>LSOutput</code>. </dd> 160f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dt> 161320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"unbound-prefix-in-entity-reference" [fatal]</code> </dt> 162f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> Raised if the 163320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * configuration parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespaces'> 164f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * namespaces</a>" is set to <code>true</code> and an entity whose replacement text 165f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * contains unbound namespace prefixes is referenced in a location where 166320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * there are no bindings for the namespace prefixes. </dd> 167320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 168320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"unsupported-encoding" [fatal]</code></dt> 169f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> Raised if an unsupported 170320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * encoding is encountered. </dd> 171f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * </dl> 172f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> In addition to raising the defined errors and warnings, implementations 173f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * are expected to raise implementation specific errors and warnings for any 174f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * other error and warning cases such as IO errors (file not found, 175f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * permission denied,...) and so on. 176320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <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 177320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonand Save Specification</a>. 178320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 179320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpublic interface LSSerializer { 180320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 181f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * The <code>DOMConfiguration</code> object used by the 182f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSSerializer</code> when serializing a DOM node. 183320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <br> In addition to the parameters recognized by the <a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMConfiguration'> 184320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * DOMConfiguration</a> interface defined in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] 185f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * , the <code>DOMConfiguration</code> objects for 186f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSSerializer</code> adds, or modifies, the following 187f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * parameters: 188320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 189320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"canonical-form"</code></dt> 190320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd> 191320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 192320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>true</code></dt> 193f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <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>]. 194320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * In addition to the behavior described in "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-canonical-form'> 195320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * canonical-form</a>" [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] 196f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * , setting this parameter to <code>true</code> will set the parameters 197320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * "format-pretty-print", "discard-default-content", and "xml-declaration 198f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * ", to <code>false</code>. Setting one of those parameters to 199f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>true</code> will set this parameter to <code>false</code>. 200f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Serializing an XML 1.1 document when "canonical-form" is 201320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>true</code> will generate a fatal error. </dd> 202320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>false</code></dt> 203320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd>[<em>required</em>] (<em>default</em>) Do not canonicalize the output. </dd> 204320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl></dd> 205320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"discard-default-content"</code></dt> 206320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd> 207320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 208320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 209320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>true</code></dt> 210f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd>[<em>required</em>] (<em>default</em>) Use the <code>Attr.specified</code> attribute to decide what attributes 211f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * should be discarded. Note that some implementations might use 212f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * whatever information available to the implementation (i.e. XML 213f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * schema, DTD, the <code>Attr.specified</code> attribute, and so on) to 214f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * determine what attributes and content to discard if this parameter is 215320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * set to <code>true</code>. </dd> 216320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>false</code></dt> 217320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd>[<em>required</em>]Keep all attributes and all content.</dd> 218320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl></dd> 219320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"format-pretty-print"</code></dt> 220320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd> 221320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 222320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 223320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>true</code></dt> 224f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd>[<em>optional</em>] Formatting the output by adding whitespace to produce a pretty-printed, 225f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * indented, human-readable form. The exact form of the transformations 226f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is not specified by this specification. Pretty-printing changes the 227f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * content of the document and may affect the validity of the document, 228320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * validating implementations should preserve validity. </dd> 229320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 230320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>false</code></dt> 231320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd>[<em>required</em>] (<em>default</em>) Don't pretty-print the result. </dd> 232320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl></dd> 233f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dt> 234320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"ignore-unknown-character-denormalizations"</code> </dt> 235320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd> 236320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 237320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 238320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>true</code></dt> 239f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd>[<em>required</em>] (<em>default</em>) If, while verifying full normalization when [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>] is 240f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * supported, a character is encountered for which the normalization 241f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * properties cannot be determined, then raise a 242f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>"unknown-character-denormalization"</code> warning (instead of 243f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * raising an error, if this parameter is not set) and ignore any 244320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * possible denormalizations caused by these characters. </dd> 245320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 246320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>false</code></dt> 247f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd>[<em>optional</em>] Report a fatal error if a character is encountered for which the 248320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * processor cannot determine the normalization properties. </dd> 249320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl></dd> 250320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 251320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"normalize-characters"</code></dt> 252f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> This parameter is equivalent to 253320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the one defined by <code>DOMConfiguration</code> in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] 254f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * . Unlike in the Core, the default value for this parameter is 255f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>true</code>. While DOM implementations are not required to 256f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * support <a href='http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-fullnorm'>fully 257f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * normalizing</a> the characters in the document according to appendix E of [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>], this 258320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * parameter must be activated by default if supported. </dd> 259320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 260320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"xml-declaration"</code></dt> 261320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd> 262320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 263320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>true</code></dt> 264320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd>[<em>required</em>] (<em>default</em>) If a <code>Document</code>, <code>Element</code>, or <code>Entity</code> 265f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * node is serialized, the XML declaration, or text declaration, should 266f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * be included. The version (<code>Document.xmlVersion</code> if the 267f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * document is a Level 3 document and the version is non-null, otherwise 268f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * use the value "1.0"), and the output encoding (see 269f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSSerializer.write</code> for details on how to find the output 270320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * encoding) are specified in the serialized XML declaration. </dd> 271320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 272320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>false</code></dt> 273f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd>[<em>required</em>] Do not serialize the XML and text declarations. Report a 274f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>"xml-declaration-needed"</code> warning if this will cause 275f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * problems (i.e. the serialized data is of an XML version other than [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>], or an 276320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * encoding would be needed to be able to re-parse the serialized data). </dd> 277320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl></dd> 278320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl> 279320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 280320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public DOMConfiguration getDomConfig(); 281320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 282320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 283f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * The end-of-line sequence of characters to be used in the XML being 284f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * written out. Any string is supported, but XML treats only a certain 285f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * set of characters sequence as end-of-line (See section 2.11, 286f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * "End-of-Line Handling" in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>], if the 287f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serialized content is XML 1.0 or section 2.11, "End-of-Line Handling" 288f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>], if the 289f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serialized content is XML 1.1). Using other character sequences than 290f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the recommended ones can result in a document that is either not 291f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serializable or not well-formed). 292f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> On retrieval, the default value of this attribute is the 293f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implementation specific default end-of-line sequence. DOM 294f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implementations should choose the default to match the usual 295f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * convention for text files in the environment being used. 296f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Implementations must choose a default sequence that matches one of 297f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * those allowed by XML 1.0 or XML 1.1, depending on the serialized 298f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * content. Setting this attribute to <code>null</code> will reset its 299f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * value to the default value. 300f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> 301320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 302320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public String getNewLine(); 303320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 304f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * The end-of-line sequence of characters to be used in the XML being 305f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * written out. Any string is supported, but XML treats only a certain 306f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * set of characters sequence as end-of-line (See section 2.11, 307f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * "End-of-Line Handling" in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>], if the 308f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serialized content is XML 1.0 or section 2.11, "End-of-Line Handling" 309f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>], if the 310f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serialized content is XML 1.1). Using other character sequences than 311f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the recommended ones can result in a document that is either not 312f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serializable or not well-formed). 313f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> On retrieval, the default value of this attribute is the 314f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implementation specific default end-of-line sequence. DOM 315f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implementations should choose the default to match the usual 316f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * convention for text files in the environment being used. 317f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Implementations must choose a default sequence that matches one of 318f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * those allowed by XML 1.0 or XML 1.1, depending on the serialized 319f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * content. Setting this attribute to <code>null</code> will reset its 320f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * value to the default value. 321f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> 322320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 323320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public void setNewLine(String newLine); 324320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 325320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 326f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * When the application provides a filter, the serializer will call out 327f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * to the filter before serializing each Node. The filter implementation 328f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * can choose to remove the node from the stream or to terminate the 329f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serialization early. 330f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> The filter is invoked after the operations requested by the 331f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DOMConfiguration</code> parameters have been applied. For 332320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * example, CDATA sections won't be passed to the filter if "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-cdata-sections'> 3330233201f5e7de490d3830ca96e8a18765797ea3aJesse Wilson * cdata-sections</a>" is set to <code>false</code>. 3340233201f5e7de490d3830ca96e8a18765797ea3aJesse Wilson * 3350233201f5e7de490d3830ca96e8a18765797ea3aJesse Wilson * @hide 336320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 337320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public LSSerializerFilter getFilter(); 338320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 339f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * When the application provides a filter, the serializer will call out 340f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * to the filter before serializing each Node. The filter implementation 341f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * can choose to remove the node from the stream or to terminate the 342f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serialization early. 343f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> The filter is invoked after the operations requested by the 344f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DOMConfiguration</code> parameters have been applied. For 345320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * example, CDATA sections won't be passed to the filter if "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-cdata-sections'> 3460233201f5e7de490d3830ca96e8a18765797ea3aJesse Wilson * cdata-sections</a>" is set to <code>false</code>. 3470233201f5e7de490d3830ca96e8a18765797ea3aJesse Wilson * 348f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @hide 349320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 350320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public void setFilter(LSSerializerFilter filter); 351320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 352320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 353f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Serialize the specified node as described above in the general 354f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * description of the <code>LSSerializer</code> interface. The output is 355f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * written to the supplied <code>LSOutput</code>. 356f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> When writing to a <code>LSOutput</code>, the encoding is found by 357f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * looking at the encoding information that is reachable through the 358f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSOutput</code> and the item to be written (or its owner 359f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * document) in this order: 360320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <ol> 361f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <li> <code>LSOutput.encoding</code>, 362320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 363f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <li> 364f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Document.inputEncoding</code>, 365320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 366f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <li> 367f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Document.xmlEncoding</code>. 368320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 369320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </ol> 370f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> If no encoding is reachable through the above properties, a 371f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * default encoding of "UTF-8" will be used. If the specified encoding 372f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is not supported an "unsupported-encoding" fatal error is raised. 373f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> If no output is specified in the <code>LSOutput</code>, a 374f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * "no-output-specified" fatal error is raised. 375f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> The implementation is responsible of associating the appropriate 376f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * media type with the serialized data. 377f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> When writing to a HTTP URI, a HTTP PUT is performed. When writing 378f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * to other types of URIs, the mechanism for writing the data to the URI 379f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is implementation dependent. 380f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param nodeArg The node to serialize. 381320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param destination The destination for the serialized DOM. 382f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @return Returns <code>true</code> if <code>node</code> was 383f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * successfully serialized. Return <code>false</code> in case the 384f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * normal processing stopped but the implementation kept serializing 385f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the document; the result of the serialization being implementation 386f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * dependent then. 387320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception LSException 388f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to 389f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serialize the node. DOM applications should attach a 390320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> 391f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * error-handler</a>" if they wish to get details on the error. 392320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 393f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes public boolean write(Node nodeArg, 394320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson LSOutput destination) 395320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws LSException; 396320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 397320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 398f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * A convenience method that acts as if <code>LSSerializer.write</code> 399f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * was called with a <code>LSOutput</code> with no encoding specified 400f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * and <code>LSOutput.systemId</code> set to the <code>uri</code> 401f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * argument. 402f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param nodeArg The node to serialize. 403320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param uri The URI to write to. 404f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @return Returns <code>true</code> if <code>node</code> was 405f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * successfully serialized. Return <code>false</code> in case the 406f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * normal processing stopped but the implementation kept serializing 407f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the document; the result of the serialization being implementation 408f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * dependent then. 409320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception LSException 410f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to 411f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serialize the node. DOM applications should attach a 412320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> 413f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * error-handler</a>" if they wish to get details on the error. 414320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 415f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes public boolean writeToURI(Node nodeArg, 416320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson String uri) 417320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws LSException; 418320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 419320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 420f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Serialize the specified node as described above in the general 421f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * description of the <code>LSSerializer</code> interface. The output is 422f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * written to a <code>DOMString</code> that is returned to the caller. 423f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * The encoding used is the encoding of the <code>DOMString</code> type, 424f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * i.e. UTF-16. Note that no Byte Order Mark is generated in a 425f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DOMString</code> object. 426f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param nodeArg The node to serialize. 427f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @return Returns the serialized data. 428320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception DOMException 429f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * DOMSTRING_SIZE_ERR: Raised if the resulting string is too long to 430f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * fit in a <code>DOMString</code>. 431320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception LSException 432f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to 433f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * serialize the node. DOM applications should attach a 434320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> 435f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * error-handler</a>" if they wish to get details on the error. 436320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 437320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public String writeToString(Node nodeArg) 438320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws DOMException, LSException; 439320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 440320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson} 441