View Javadoc
1   /*
2    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3    *
4    * This code is free software; you can redistribute it and/or modify it
5    * under the terms of the GNU General Public License version 2 only, as
6    * published by the Free Software Foundation.  Oracle designates this
7    * particular file as subject to the "Classpath" exception as provided
8    * by Oracle in the LICENSE file that accompanied this code.
9    *
10   * This code is distributed in the hope that it will be useful, but WITHOUT
11   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
13   * version 2 for more details (a copy is included in the LICENSE file that
14   * accompanied this code).
15   *
16   * You should have received a copy of the GNU General Public License version
17   * 2 along with this work; if not, write to the Free Software Foundation,
18   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19   *
20   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21   * or visit www.oracle.com if you need additional information or have any
22   * questions.
23   */
24  
25  /*
26   * This file is available under and governed by the GNU General Public
27   * License version 2 only, as published by the Free Software Foundation.
28   * However, the following notice accompanied the original version of this
29   * file and, per its terms, should not be removed:
30   *
31   * Copyright (c) 2004 World Wide Web Consortium,
32   *
33   * (Massachusetts Institute of Technology, European Research Consortium for
34   * Informatics and Mathematics, Keio University). All Rights Reserved. This
35   * work is distributed under the W3C(r) Software License [1] in the hope that
36   * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
37   * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
38   *
39   * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
40   */
41  
42  package org.w3c.dom.ls;
43  
44  import org.w3c.dom.DOMConfiguration;
45  import org.w3c.dom.Node;
46  import org.w3c.dom.DOMException;
47  
48  /**
49   *  A <code>LSSerializer</code> provides an API for serializing (writing) a
50   * DOM document out into XML. The XML data is written to a string or an
51   * output stream. Any changes or fixups made during the serialization affect
52   * only the serialized data. The <code>Document</code> object and its
53   * children are never altered by the serialization operation.
54   * <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>]
55   * , Appendix B. [<a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>DOM Level 2 Core</a>]
56   *  allows empty strings as a real namespace URI. If the
57   * <code>namespaceURI</code> of a <code>Node</code> is empty string, the
58   * serialization will treat them as <code>null</code>, ignoring the prefix
59   * if any.
60   * <p> <code>LSSerializer</code> accepts any node type for serialization. For
61   * nodes of type <code>Document</code> or <code>Entity</code>, well-formed
62   * XML will be created when possible (well-formedness is guaranteed if the
63   * document or entity comes from a parse operation and is unchanged since it
64   * was created). The serialized output for these node types is either as a
65   * XML document or an External XML Entity, respectively, and is acceptable
66   * input for an XML parser. For all other types of nodes the serialized form
67   * is implementation dependent.
68   * <p>Within a <code>Document</code>, <code>DocumentFragment</code>, or
69   * <code>Entity</code> being serialized, <code>Nodes</code> are processed as
70   * follows
71   * <ul>
72   * <li> <code>Document</code> nodes are written, including the XML
73   * declaration (unless the parameter "xml-declaration" is set to
74   * <code>false</code>) and a DTD subset, if one exists in the DOM. Writing a
75   * <code>Document</code> node serializes the entire document.
76   * </li>
77   * <li>
78   * <code>Entity</code> nodes, when written directly by
79   * <code>LSSerializer.write</code>, outputs the entity expansion but no
80   * namespace fixup is done. The resulting output will be valid as an
81   * external entity.
82   * </li>
83   * <li> If the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'>
84   * entities</a>" is set to <code>true</code>, <code>EntityReference</code> nodes are
85   * serialized as an entity reference of the form "
86   * <code>&amp;entityName;</code>" in the output. Child nodes (the expansion)
87   * of the entity reference are ignored. If the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'>
88   * entities</a>" is set to <code>false</code>, only the children of the entity reference
89   * are serialized. <code>EntityReference</code> nodes with no children (no
90   * corresponding <code>Entity</code> node or the corresponding
91   * <code>Entity</code> nodes have no children) are always serialized.
92   * </li>
93   * <li>
94   * <code>CDATAsections</code> containing content characters that cannot be
95   * represented in the specified output encoding are handled according to the
96   * "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-split-cdata-sections'>
97   * split-cdata-sections</a>" parameter.  If the parameter is set to <code>true</code>,
98   * <code>CDATAsections</code> are split, and the unrepresentable characters
99   * are serialized as numeric character references in ordinary content. The
100  * exact position and number of splits is not specified.  If the parameter
101  * is set to <code>false</code>, unrepresentable characters in a
102  * <code>CDATAsection</code> are reported as
103  * <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'>
104  * well-formed</a>" is set to <code>true</code>. The error is not recoverable - there is no
105  * mechanism for supplying alternative characters and continuing with the
106  * serialization.
107  * </li>
108  * <li> <code>DocumentFragment</code> nodes are serialized by
109  * serializing the children of the document fragment in the order they
110  * appear in the document fragment.
111  * </li>
112  * <li> All other node types (Element, Text,
113  * etc.) are serialized to their corresponding XML source form.
114  * </li>
115  * </ul>
116  * <p ><b>Note:</b>  The serialization of a <code>Node</code> does not always
117  * generate a well-formed XML document, i.e. a <code>LSParser</code> might
118  * throw fatal errors when parsing the resulting serialization.
119  * <p> Within the character data of a document (outside of markup), any
120  * characters that cannot be represented directly are replaced with
121  * character references. Occurrences of '&lt;' and '&amp;' are replaced by
122  * the predefined entities &amp;lt; and &amp;amp;. The other predefined
123  * entities (&amp;gt;, &amp;apos;, and &amp;quot;) might not be used, except
124  * where needed (e.g. using &amp;gt; in cases such as ']]&gt;'). Any
125  * characters that cannot be represented directly in the output character
126  * encoding are serialized as numeric character references (and since
127  * character encoding standards commonly use hexadecimal representations of
128  * characters, using the hexadecimal representation when serializing
129  * character references is encouraged).
130  * <p> To allow attribute values to contain both single and double quotes, the
131  * apostrophe or single-quote character (') may be represented as
132  * "&amp;apos;", and the double-quote character (")  as "&amp;quot;". New
133  * line characters and other characters that cannot be represented directly
134  * in attribute values in the output character encoding are serialized as a
135  * numeric character reference.
136  * <p> Within markup, but outside of attributes, any occurrence of a character
137  * that cannot be represented in the output character encoding is reported
138  * as a <code>DOMError</code> fatal error. An example would be serializing
139  * the element &lt;LaCa\u00f1ada/&gt; with <code>encoding="us-ascii"</code>.
140  * This will result with a generation of a <code>DOMError</code>
141  * "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'>
142  * well-formed</a>").
143  * <p> When requested by setting the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-normalize-characters'>
144  * normalize-characters</a>" on <code>LSSerializer</code> to true, character normalization is
145  * performed according to the definition of <a href='http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-fullnorm'>fully
146  * 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
147  * data to be serialized, both markup and character data. The character
148  * normalization process affects only the data as it is being written; it
149  * does not alter the DOM's view of the document after serialization has
150  * completed.
151  * <p> Implementations are required to support the encodings "UTF-8",
152  * "UTF-16", "UTF-16BE", and "UTF-16LE" to guarantee that data is
153  * serializable in all encodings that are required to be supported by all
154  * XML parsers. When the encoding is UTF-8, whether or not a byte order mark
155  * is serialized, or if the output is big-endian or little-endian, is
156  * implementation dependent. When the encoding is UTF-16, whether or not the
157  * output is big-endian or little-endian is implementation dependent, but a
158  * Byte Order Mark must be generated for non-character outputs, such as
159  * <code>LSOutput.byteStream</code> or <code>LSOutput.systemId</code>. If
160  * the Byte Order Mark is not generated, a "byte-order-mark-needed" warning
161  * is reported. When the encoding is UTF-16LE or UTF-16BE, the output is
162  * big-endian (UTF-16BE) or little-endian (UTF-16LE) and the Byte Order Mark
163  * is not be generated. In all cases, the encoding declaration, if
164  * generated, will correspond to the encoding used during the serialization
165  * (e.g. <code>encoding="UTF-16"</code> will appear if UTF-16 was
166  * requested).
167  * <p> Namespaces are fixed up during serialization, the serialization process
168  * will verify that namespace declarations, namespace prefixes and the
169  * namespace URI associated with elements and attributes are consistent. If
170  * inconsistencies are found, the serialized form of the document will be
171  * altered to remove them. The method used for doing the namespace fixup
172  * while serializing a document is the algorithm defined in Appendix B.1,
173  * "Namespace normalization", of [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
174  * .
175  * <p> While serializing a document, the parameter "discard-default-content"
176  * controls whether or not non-specified data is serialized.
177  * <p> While serializing, errors and warnings are reported to the application
178  * 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'>
179  * error-handler</a>" parameter). This specification does in no way try to define all possible
180  * errors and warnings that can occur while serializing a DOM node, but some
181  * common error and warning cases are defined. The types (
182  * <code>DOMError.type</code>) of errors and warnings defined by this
183  * specification are:
184  * <dl>
185  * <dt><code>"no-output-specified" [fatal]</code></dt>
186  * <dd> Raised when
187  * writing to a <code>LSOutput</code> if no output is specified in the
188  * <code>LSOutput</code>. </dd>
189  * <dt>
190  * <code>"unbound-prefix-in-entity-reference" [fatal]</code> </dt>
191  * <dd> Raised if the
192  * configuration parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespaces'>
193  * namespaces</a>" is set to <code>true</code> and an entity whose replacement text
194  * contains unbound namespace prefixes is referenced in a location where
195  * there are no bindings for the namespace prefixes. </dd>
196  * <dt>
197  * <code>"unsupported-encoding" [fatal]</code></dt>
198  * <dd> Raised if an unsupported
199  * encoding is encountered. </dd>
200  * </dl>
201  * <p> In addition to raising the defined errors and warnings, implementations
202  * are expected to raise implementation specific errors and warnings for any
203  * other error and warning cases such as IO errors (file not found,
204  * permission denied,...) and so on.
205  * <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
206 and Save Specification</a>.
207  */
208 public interface LSSerializer {
209     /**
210      *  The <code>DOMConfiguration</code> object used by the
211      * <code>LSSerializer</code> when serializing a DOM node.
212      * <br> In addition to the parameters recognized by the <a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMConfiguration'>
213      * DOMConfiguration</a> interface defined in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
214      * , the <code>DOMConfiguration</code> objects for
215      * <code>LSSerializer</code> adds, or modifies, the following
216      * parameters:
217      * <dl>
218      * <dt><code>"canonical-form"</code></dt>
219      * <dd>
220      * <dl>
221      * <dt><code>true</code></dt>
222      * <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>].
223      * In addition to the behavior described in "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-canonical-form'>
224      * canonical-form</a>" [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
225      * , setting this parameter to <code>true</code> will set the parameters
226      * "format-pretty-print", "discard-default-content", and "xml-declaration
227      * ", to <code>false</code>. Setting one of those parameters to
228      * <code>true</code> will set this parameter to <code>false</code>.
229      * Serializing an XML 1.1 document when "canonical-form" is
230      * <code>true</code> will generate a fatal error. </dd>
231      * <dt><code>false</code></dt>
232      * <dd>[<em>required</em>] (<em>default</em>) Do not canonicalize the output. </dd>
233      * </dl></dd>
234      * <dt><code>"discard-default-content"</code></dt>
235      * <dd>
236      * <dl>
237      * <dt>
238      * <code>true</code></dt>
239      * <dd>[<em>required</em>] (<em>default</em>) Use the <code>Attr.specified</code> attribute to decide what attributes
240      * should be discarded. Note that some implementations might use
241      * whatever information available to the implementation (i.e. XML
242      * schema, DTD, the <code>Attr.specified</code> attribute, and so on) to
243      * determine what attributes and content to discard if this parameter is
244      * set to <code>true</code>. </dd>
245      * <dt><code>false</code></dt>
246      * <dd>[<em>required</em>]Keep all attributes and all content.</dd>
247      * </dl></dd>
248      * <dt><code>"format-pretty-print"</code></dt>
249      * <dd>
250      * <dl>
251      * <dt>
252      * <code>true</code></dt>
253      * <dd>[<em>optional</em>] Formatting the output by adding whitespace to produce a pretty-printed,
254      * indented, human-readable form. The exact form of the transformations
255      * is not specified by this specification. Pretty-printing changes the
256      * content of the document and may affect the validity of the document,
257      * validating implementations should preserve validity. </dd>
258      * <dt>
259      * <code>false</code></dt>
260      * <dd>[<em>required</em>] (<em>default</em>) Don't pretty-print the result. </dd>
261      * </dl></dd>
262      * <dt>
263      * <code>"ignore-unknown-character-denormalizations"</code> </dt>
264      * <dd>
265      * <dl>
266      * <dt>
267      * <code>true</code></dt>
268      * <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
269      * supported, a character is encountered for which the normalization
270      * properties cannot be determined, then raise a
271      * <code>"unknown-character-denormalization"</code> warning (instead of
272      * raising an error, if this parameter is not set) and ignore any
273      * possible denormalizations caused by these characters. </dd>
274      * <dt>
275      * <code>false</code></dt>
276      * <dd>[<em>optional</em>] Report a fatal error if a character is encountered for which the
277      * processor cannot determine the normalization properties. </dd>
278      * </dl></dd>
279      * <dt>
280      * <code>"normalize-characters"</code></dt>
281      * <dd> This parameter is equivalent to
282      * 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>]
283      * . Unlike in the Core, the default value for this parameter is
284      * <code>true</code>. While DOM implementations are not required to
285      * support <a href='http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-fullnorm'>fully
286      * 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
287      * parameter must be activated by default if supported. </dd>
288      * <dt>
289      * <code>"xml-declaration"</code></dt>
290      * <dd>
291      * <dl>
292      * <dt><code>true</code></dt>
293      * <dd>[<em>required</em>] (<em>default</em>) If a <code>Document</code>, <code>Element</code>, or <code>Entity</code>
294      *  node is serialized, the XML declaration, or text declaration, should
295      * be included. The version (<code>Document.xmlVersion</code> if the
296      * document is a Level 3 document and the version is non-null, otherwise
297      * use the value "1.0"), and the output encoding (see
298      * <code>LSSerializer.write</code> for details on how to find the output
299      * encoding) are specified in the serialized XML declaration. </dd>
300      * <dt>
301      * <code>false</code></dt>
302      * <dd>[<em>required</em>] Do not serialize the XML and text declarations. Report a
303      * <code>"xml-declaration-needed"</code> warning if this will cause
304      * 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
305      * encoding would be needed to be able to re-parse the serialized data). </dd>
306      * </dl></dd>
307      * </dl>
308      */
309     public DOMConfiguration getDomConfig();
310 
311     /**
312      *  The end-of-line sequence of characters to be used in the XML being
313      * written out. Any string is supported, but XML treats only a certain
314      * set of characters sequence as end-of-line (See section 2.11,
315      * "End-of-Line Handling" in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>], if the
316      * serialized content is XML 1.0 or section 2.11, "End-of-Line Handling"
317      * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>], if the
318      * serialized content is XML 1.1). Using other character sequences than
319      * the recommended ones can result in a document that is either not
320      * serializable or not well-formed).
321      * <br> On retrieval, the default value of this attribute is the
322      * implementation specific default end-of-line sequence. DOM
323      * implementations should choose the default to match the usual
324      * convention for text files in the environment being used.
325      * Implementations must choose a default sequence that matches one of
326      * those allowed by XML 1.0 or XML 1.1, depending on the serialized
327      * content. Setting this attribute to <code>null</code> will reset its
328      * value to the default value.
329      * <br>
330      */
331     public String getNewLine();
332     /**
333      *  The end-of-line sequence of characters to be used in the XML being
334      * written out. Any string is supported, but XML treats only a certain
335      * set of characters sequence as end-of-line (See section 2.11,
336      * "End-of-Line Handling" in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>], if the
337      * serialized content is XML 1.0 or section 2.11, "End-of-Line Handling"
338      * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>], if the
339      * serialized content is XML 1.1). Using other character sequences than
340      * the recommended ones can result in a document that is either not
341      * serializable or not well-formed).
342      * <br> On retrieval, the default value of this attribute is the
343      * implementation specific default end-of-line sequence. DOM
344      * implementations should choose the default to match the usual
345      * convention for text files in the environment being used.
346      * Implementations must choose a default sequence that matches one of
347      * those allowed by XML 1.0 or XML 1.1, depending on the serialized
348      * content. Setting this attribute to <code>null</code> will reset its
349      * value to the default value.
350      * <br>
351      */
352     public void setNewLine(String newLine);
353 
354     /**
355      *  When the application provides a filter, the serializer will call out
356      * to the filter before serializing each Node. The filter implementation
357      * can choose to remove the node from the stream or to terminate the
358      * serialization early.
359      * <br> The filter is invoked after the operations requested by the
360      * <code>DOMConfiguration</code> parameters have been applied. For
361      * 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'>
362      * cdata-sections</a>" is set to <code>false</code>.
363      */
364     public LSSerializerFilter getFilter();
365     /**
366      *  When the application provides a filter, the serializer will call out
367      * to the filter before serializing each Node. The filter implementation
368      * can choose to remove the node from the stream or to terminate the
369      * serialization early.
370      * <br> The filter is invoked after the operations requested by the
371      * <code>DOMConfiguration</code> parameters have been applied. For
372      * 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'>
373      * cdata-sections</a>" is set to <code>false</code>.
374      */
375     public void setFilter(LSSerializerFilter filter);
376 
377     /**
378      *  Serialize the specified node as described above in the general
379      * description of the <code>LSSerializer</code> interface. The output is
380      * written to the supplied <code>LSOutput</code>.
381      * <br> When writing to a <code>LSOutput</code>, the encoding is found by
382      * looking at the encoding information that is reachable through the
383      * <code>LSOutput</code> and the item to be written (or its owner
384      * document) in this order:
385      * <ol>
386      * <li> <code>LSOutput.encoding</code>,
387      * </li>
388      * <li>
389      * <code>Document.inputEncoding</code>,
390      * </li>
391      * <li>
392      * <code>Document.xmlEncoding</code>.
393      * </li>
394      * </ol>
395      * <br> If no encoding is reachable through the above properties, a
396      * default encoding of "UTF-8" will be used. If the specified encoding
397      * is not supported an "unsupported-encoding" fatal error is raised.
398      * <br> If no output is specified in the <code>LSOutput</code>, a
399      * "no-output-specified" fatal error is raised.
400      * <br> The implementation is responsible of associating the appropriate
401      * media type with the serialized data.
402      * <br> When writing to a HTTP URI, a HTTP PUT is performed. When writing
403      * to other types of URIs, the mechanism for writing the data to the URI
404      * is implementation dependent.
405      * @param nodeArg  The node to serialize.
406      * @param destination The destination for the serialized DOM.
407      * @return  Returns <code>true</code> if <code>node</code> was
408      *   successfully serialized. Return <code>false</code> in case the
409      *   normal processing stopped but the implementation kept serializing
410      *   the document; the result of the serialization being implementation
411      *   dependent then.
412      * @exception LSException
413      *    SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to
414      *   serialize the node. DOM applications should attach a
415      *   <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
416      *   error-handler</a>" if they wish to get details on the error.
417      */
418     public boolean write(Node nodeArg,
419                          LSOutput destination)
420                          throws LSException;
421 
422     /**
423      *  A convenience method that acts as if <code>LSSerializer.write</code>
424      * was called with a <code>LSOutput</code> with no encoding specified
425      * and <code>LSOutput.systemId</code> set to the <code>uri</code>
426      * argument.
427      * @param nodeArg  The node to serialize.
428      * @param uri The URI to write to.
429      * @return  Returns <code>true</code> if <code>node</code> was
430      *   successfully serialized. Return <code>false</code> in case the
431      *   normal processing stopped but the implementation kept serializing
432      *   the document; the result of the serialization being implementation
433      *   dependent then.
434      * @exception LSException
435      *    SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to
436      *   serialize the node. DOM applications should attach a
437      *   <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
438      *   error-handler</a>" if they wish to get details on the error.
439      */
440     public boolean writeToURI(Node nodeArg,
441                               String uri)
442                               throws LSException;
443 
444     /**
445      *  Serialize the specified node as described above in the general
446      * description of the <code>LSSerializer</code> interface. The output is
447      * written to a <code>DOMString</code> that is returned to the caller.
448      * The encoding used is the encoding of the <code>DOMString</code> type,
449      * i.e. UTF-16. Note that no Byte Order Mark is generated in a
450      * <code>DOMString</code> object.
451      * @param nodeArg  The node to serialize.
452      * @return  Returns the serialized data.
453      * @exception DOMException
454      *    DOMSTRING_SIZE_ERR: Raised if the resulting string is too long to
455      *   fit in a <code>DOMString</code>.
456      * @exception LSException
457      *    SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to
458      *   serialize the node. DOM applications should attach a
459      *   <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
460      *   error-handler</a>" if they wish to get details on the error.
461      */
462     public String writeToString(Node nodeArg)
463                                 throws DOMException, LSException;
464 
465 }