001/*
002 * Copyright (c) 2004 World Wide Web Consortium,
003 *
004 * (Massachusetts Institute of Technology, European Research Consortium for
005 * Informatics and Mathematics, Keio University). All Rights Reserved. This
006 * work is distributed under the W3C(r) Software License [1] in the hope that
007 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
008 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
009 *
010 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
011 */
012
013package org.w3c.dom.ls;
014
015import org.w3c.dom.DOMConfiguration;
016import org.w3c.dom.Node;
017import org.w3c.dom.DOMException;
018
019/**
020 *  A <code>LSSerializer</code> provides an API for serializing (writing) a
021 * DOM document out into XML. The XML data is written to a string or an
022 * output stream. Any changes or fixups made during the serialization affect
023 * only the serialized data. The <code>Document</code> object and its
024 * children are never altered by the serialization operation.
025 * <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>]
026 * , Appendix B. [<a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>DOM Level 2 Core</a>]
027 *  allows empty strings as a real namespace URI. If the
028 * <code>namespaceURI</code> of a <code>Node</code> is empty string, the
029 * serialization will treat them as <code>null</code>, ignoring the prefix
030 * if any.
031 * <p> <code>LSSerializer</code> accepts any node type for serialization. For
032 * nodes of type <code>Document</code> or <code>Entity</code>, well-formed
033 * XML will be created when possible (well-formedness is guaranteed if the
034 * document or entity comes from a parse operation and is unchanged since it
035 * was created). The serialized output for these node types is either as a
036 * XML document or an External XML Entity, respectively, and is acceptable
037 * input for an XML parser. For all other types of nodes the serialized form
038 * is implementation dependent.
039 * <p>Within a <code>Document</code>, <code>DocumentFragment</code>, or
040 * <code>Entity</code> being serialized, <code>Nodes</code> are processed as
041 * follows
042 * <ul>
043 * <li> <code>Document</code> nodes are written, including the XML
044 * declaration (unless the parameter "xml-declaration" is set to
045 * <code>false</code>) and a DTD subset, if one exists in the DOM. Writing a
046 * <code>Document</code> node serializes the entire document.
047 * </li>
048 * <li>
049 * <code>Entity</code> nodes, when written directly by
050 * <code>LSSerializer.write</code>, outputs the entity expansion but no
051 * namespace fixup is done. The resulting output will be valid as an
052 * external entity.
053 * </li>
054 * <li> If the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'>
055 * entities</a>" is set to <code>true</code>, <code>EntityReference</code> nodes are
056 * serialized as an entity reference of the form "
057 * <code>&amp;entityName;</code>" in the output. Child nodes (the expansion)
058 * of the entity reference are ignored. If the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'>
059 * entities</a>" is set to <code>false</code>, only the children of the entity reference
060 * are serialized. <code>EntityReference</code> nodes with no children (no
061 * corresponding <code>Entity</code> node or the corresponding
062 * <code>Entity</code> nodes have no children) are always serialized.
063 * </li>
064 * <li>
065 * <code>CDATAsections</code> containing content characters that cannot be
066 * represented in the specified output encoding are handled according to the
067 * "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-split-cdata-sections'>
068 * split-cdata-sections</a>" parameter.  If the parameter is set to <code>true</code>,
069 * <code>CDATAsections</code> are split, and the unrepresentable characters
070 * are serialized as numeric character references in ordinary content. The
071 * exact position and number of splits is not specified.  If the parameter
072 * is set to <code>false</code>, unrepresentable characters in a
073 * <code>CDATAsection</code> are reported as
074 * <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'>
075 * well-formed</a>" is set to <code>true</code>. The error is not recoverable - there is no
076 * mechanism for supplying alternative characters and continuing with the
077 * serialization.
078 * </li>
079 * <li> <code>DocumentFragment</code> nodes are serialized by
080 * serializing the children of the document fragment in the order they
081 * appear in the document fragment.
082 * </li>
083 * <li> All other node types (Element, Text,
084 * etc.) are serialized to their corresponding XML source form.
085 * </li>
086 * </ul>
087 * <p ><b>Note:</b>  The serialization of a <code>Node</code> does not always
088 * generate a well-formed XML document, i.e. a <code>LSParser</code> might
089 * throw fatal errors when parsing the resulting serialization.
090 * <p> Within the character data of a document (outside of markup), any
091 * characters that cannot be represented directly are replaced with
092 * character references. Occurrences of '&lt;' and '&amp;' are replaced by
093 * the predefined entities &amp;lt; and &amp;amp;. The other predefined
094 * entities (&amp;gt;, &amp;apos;, and &amp;quot;) might not be used, except
095 * where needed (e.g. using &amp;gt; in cases such as ']]&gt;'). Any
096 * characters that cannot be represented directly in the output character
097 * encoding are serialized as numeric character references (and since
098 * character encoding standards commonly use hexadecimal representations of
099 * characters, using the hexadecimal representation when serializing
100 * character references is encouraged).
101 * <p> To allow attribute values to contain both single and double quotes, the
102 * apostrophe or single-quote character (') may be represented as
103 * "&amp;apos;", and the double-quote character (")  as "&amp;quot;". New
104 * line characters and other characters that cannot be represented directly
105 * in attribute values in the output character encoding are serialized as a
106 * numeric character reference.
107 * <p> Within markup, but outside of attributes, any occurrence of a character
108 * that cannot be represented in the output character encoding is reported
109 * as a <code>DOMError</code> fatal error. An example would be serializing
110 * the element &lt;LaCa\u00f1ada/&gt; with <code>encoding="us-ascii"</code>.
111 * This will result with a generation of a <code>DOMError</code>
112 * "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'>
113 * well-formed</a>").
114 * <p> When requested by setting the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-normalize-characters'>
115 * normalize-characters</a>" on <code>LSSerializer</code> to true, character normalization is
116 * performed according to the definition of <a href='http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-fullnorm'>fully
117 * 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
118 * data to be serialized, both markup and character data. The character
119 * normalization process affects only the data as it is being written; it
120 * does not alter the DOM's view of the document after serialization has
121 * completed.
122 * <p> Implementations are required to support the encodings "UTF-8",
123 * "UTF-16", "UTF-16BE", and "UTF-16LE" to guarantee that data is
124 * serializable in all encodings that are required to be supported by all
125 * XML parsers. When the encoding is UTF-8, whether or not a byte order mark
126 * is serialized, or if the output is big-endian or little-endian, is
127 * implementation dependent. When the encoding is UTF-16, whether or not the
128 * output is big-endian or little-endian is implementation dependent, but a
129 * Byte Order Mark must be generated for non-character outputs, such as
130 * <code>LSOutput.byteStream</code> or <code>LSOutput.systemId</code>. If
131 * the Byte Order Mark is not generated, a "byte-order-mark-needed" warning
132 * is reported. When the encoding is UTF-16LE or UTF-16BE, the output is
133 * big-endian (UTF-16BE) or little-endian (UTF-16LE) and the Byte Order Mark
134 * is not be generated. In all cases, the encoding declaration, if
135 * generated, will correspond to the encoding used during the serialization
136 * (e.g. <code>encoding="UTF-16"</code> will appear if UTF-16 was
137 * requested).
138 * <p> Namespaces are fixed up during serialization, the serialization process
139 * will verify that namespace declarations, namespace prefixes and the
140 * namespace URI associated with elements and attributes are consistent. If
141 * inconsistencies are found, the serialized form of the document will be
142 * altered to remove them. The method used for doing the namespace fixup
143 * while serializing a document is the algorithm defined in Appendix B.1,
144 * "Namespace normalization", of [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
145 * .
146 * <p> While serializing a document, the parameter "discard-default-content"
147 * controls whether or not non-specified data is serialized.
148 * <p> While serializing, errors and warnings are reported to the application
149 * 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'>
150 * error-handler</a>" parameter). This specification does in no way try to define all possible
151 * errors and warnings that can occur while serializing a DOM node, but some
152 * common error and warning cases are defined. The types (
153 * <code>DOMError.type</code>) of errors and warnings defined by this
154 * specification are:
155 * <dl>
156 * <dt><code>"no-output-specified" [fatal]</code></dt>
157 * <dd> Raised when
158 * writing to a <code>LSOutput</code> if no output is specified in the
159 * <code>LSOutput</code>. </dd>
160 * <dt>
161 * <code>"unbound-prefix-in-entity-reference" [fatal]</code> </dt>
162 * <dd> Raised if the
163 * configuration parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespaces'>
164 * namespaces</a>" is set to <code>true</code> and an entity whose replacement text
165 * contains unbound namespace prefixes is referenced in a location where
166 * there are no bindings for the namespace prefixes. </dd>
167 * <dt>
168 * <code>"unsupported-encoding" [fatal]</code></dt>
169 * <dd> Raised if an unsupported
170 * encoding is encountered. </dd>
171 * </dl>
172 * <p> In addition to raising the defined errors and warnings, implementations
173 * are expected to raise implementation specific errors and warnings for any
174 * other error and warning cases such as IO errors (file not found,
175 * permission denied,...) and so on.
176 * <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
177and Save Specification</a>.
178 */
179public interface LSSerializer {
180    /**
181     *  The <code>DOMConfiguration</code> object used by the
182     * <code>LSSerializer</code> when serializing a DOM node.
183     * <br> In addition to the parameters recognized by the <a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMConfiguration'>
184     * DOMConfiguration</a> interface defined in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
185     * , the <code>DOMConfiguration</code> objects for
186     * <code>LSSerializer</code> adds, or modifies, the following
187     * parameters:
188     * <dl>
189     * <dt><code>"canonical-form"</code></dt>
190     * <dd>
191     * <dl>
192     * <dt><code>true</code></dt>
193     * <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>].
194     * In addition to the behavior described in "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-canonical-form'>
195     * canonical-form</a>" [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
196     * , setting this parameter to <code>true</code> will set the parameters
197     * "format-pretty-print", "discard-default-content", and "xml-declaration
198     * ", to <code>false</code>. Setting one of those parameters to
199     * <code>true</code> will set this parameter to <code>false</code>.
200     * Serializing an XML 1.1 document when "canonical-form" is
201     * <code>true</code> will generate a fatal error. </dd>
202     * <dt><code>false</code></dt>
203     * <dd>[<em>required</em>] (<em>default</em>) Do not canonicalize the output. </dd>
204     * </dl></dd>
205     * <dt><code>"discard-default-content"</code></dt>
206     * <dd>
207     * <dl>
208     * <dt>
209     * <code>true</code></dt>
210     * <dd>[<em>required</em>] (<em>default</em>) Use the <code>Attr.specified</code> attribute to decide what attributes
211     * should be discarded. Note that some implementations might use
212     * whatever information available to the implementation (i.e. XML
213     * schema, DTD, the <code>Attr.specified</code> attribute, and so on) to
214     * determine what attributes and content to discard if this parameter is
215     * set to <code>true</code>. </dd>
216     * <dt><code>false</code></dt>
217     * <dd>[<em>required</em>]Keep all attributes and all content.</dd>
218     * </dl></dd>
219     * <dt><code>"format-pretty-print"</code></dt>
220     * <dd>
221     * <dl>
222     * <dt>
223     * <code>true</code></dt>
224     * <dd>[<em>optional</em>] Formatting the output by adding whitespace to produce a pretty-printed,
225     * indented, human-readable form. The exact form of the transformations
226     * is not specified by this specification. Pretty-printing changes the
227     * content of the document and may affect the validity of the document,
228     * validating implementations should preserve validity. </dd>
229     * <dt>
230     * <code>false</code></dt>
231     * <dd>[<em>required</em>] (<em>default</em>) Don't pretty-print the result. </dd>
232     * </dl></dd>
233     * <dt>
234     * <code>"ignore-unknown-character-denormalizations"</code> </dt>
235     * <dd>
236     * <dl>
237     * <dt>
238     * <code>true</code></dt>
239     * <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
240     * supported, a character is encountered for which the normalization
241     * properties cannot be determined, then raise a
242     * <code>"unknown-character-denormalization"</code> warning (instead of
243     * raising an error, if this parameter is not set) and ignore any
244     * possible denormalizations caused by these characters. </dd>
245     * <dt>
246     * <code>false</code></dt>
247     * <dd>[<em>optional</em>] Report a fatal error if a character is encountered for which the
248     * processor cannot determine the normalization properties. </dd>
249     * </dl></dd>
250     * <dt>
251     * <code>"normalize-characters"</code></dt>
252     * <dd> This parameter is equivalent to
253     * 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>]
254     * . Unlike in the Core, the default value for this parameter is
255     * <code>true</code>. While DOM implementations are not required to
256     * support <a href='http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-fullnorm'>fully
257     * 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
258     * parameter must be activated by default if supported. </dd>
259     * <dt>
260     * <code>"xml-declaration"</code></dt>
261     * <dd>
262     * <dl>
263     * <dt><code>true</code></dt>
264     * <dd>[<em>required</em>] (<em>default</em>) If a <code>Document</code>, <code>Element</code>, or <code>Entity</code>
265     *  node is serialized, the XML declaration, or text declaration, should
266     * be included. The version (<code>Document.xmlVersion</code> if the
267     * document is a Level 3 document and the version is non-null, otherwise
268     * use the value "1.0"), and the output encoding (see
269     * <code>LSSerializer.write</code> for details on how to find the output
270     * encoding) are specified in the serialized XML declaration. </dd>
271     * <dt>
272     * <code>false</code></dt>
273     * <dd>[<em>required</em>] Do not serialize the XML and text declarations. Report a
274     * <code>"xml-declaration-needed"</code> warning if this will cause
275     * 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
276     * encoding would be needed to be able to re-parse the serialized data). </dd>
277     * </dl></dd>
278     * </dl>
279     */
280    public DOMConfiguration getDomConfig();
281
282    /**
283     *  The end-of-line sequence of characters to be used in the XML being
284     * written out. Any string is supported, but XML treats only a certain
285     * set of characters sequence as end-of-line (See section 2.11,
286     * "End-of-Line Handling" in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>], if the
287     * serialized content is XML 1.0 or section 2.11, "End-of-Line Handling"
288     * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>], if the
289     * serialized content is XML 1.1). Using other character sequences than
290     * the recommended ones can result in a document that is either not
291     * serializable or not well-formed).
292     * <br> On retrieval, the default value of this attribute is the
293     * implementation specific default end-of-line sequence. DOM
294     * implementations should choose the default to match the usual
295     * convention for text files in the environment being used.
296     * Implementations must choose a default sequence that matches one of
297     * those allowed by XML 1.0 or XML 1.1, depending on the serialized
298     * content. Setting this attribute to <code>null</code> will reset its
299     * value to the default value.
300     * <br>
301     */
302    public String getNewLine();
303    /**
304     *  The end-of-line sequence of characters to be used in the XML being
305     * written out. Any string is supported, but XML treats only a certain
306     * set of characters sequence as end-of-line (See section 2.11,
307     * "End-of-Line Handling" in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>], if the
308     * serialized content is XML 1.0 or section 2.11, "End-of-Line Handling"
309     * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>], if the
310     * serialized content is XML 1.1). Using other character sequences than
311     * the recommended ones can result in a document that is either not
312     * serializable or not well-formed).
313     * <br> On retrieval, the default value of this attribute is the
314     * implementation specific default end-of-line sequence. DOM
315     * implementations should choose the default to match the usual
316     * convention for text files in the environment being used.
317     * Implementations must choose a default sequence that matches one of
318     * those allowed by XML 1.0 or XML 1.1, depending on the serialized
319     * content. Setting this attribute to <code>null</code> will reset its
320     * value to the default value.
321     * <br>
322     */
323    public void setNewLine(String newLine);
324
325    /**
326     *  When the application provides a filter, the serializer will call out
327     * to the filter before serializing each Node. The filter implementation
328     * can choose to remove the node from the stream or to terminate the
329     * serialization early.
330     * <br> The filter is invoked after the operations requested by the
331     * <code>DOMConfiguration</code> parameters have been applied. For
332     * 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'>
333     * cdata-sections</a>" is set to <code>false</code>.
334     */
335    public LSSerializerFilter getFilter();
336    /**
337     *  When the application provides a filter, the serializer will call out
338     * to the filter before serializing each Node. The filter implementation
339     * can choose to remove the node from the stream or to terminate the
340     * serialization early.
341     * <br> The filter is invoked after the operations requested by the
342     * <code>DOMConfiguration</code> parameters have been applied. For
343     * 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'>
344     * cdata-sections</a>" is set to <code>false</code>.
345     */
346    public void setFilter(LSSerializerFilter filter);
347
348    /**
349     *  Serialize the specified node as described above in the general
350     * description of the <code>LSSerializer</code> interface. The output is
351     * written to the supplied <code>LSOutput</code>.
352     * <br> When writing to a <code>LSOutput</code>, the encoding is found by
353     * looking at the encoding information that is reachable through the
354     * <code>LSOutput</code> and the item to be written (or its owner
355     * document) in this order:
356     * <ol>
357     * <li> <code>LSOutput.encoding</code>,
358     * </li>
359     * <li>
360     * <code>Document.inputEncoding</code>,
361     * </li>
362     * <li>
363     * <code>Document.xmlEncoding</code>.
364     * </li>
365     * </ol>
366     * <br> If no encoding is reachable through the above properties, a
367     * default encoding of "UTF-8" will be used. If the specified encoding
368     * is not supported an "unsupported-encoding" fatal error is raised.
369     * <br> If no output is specified in the <code>LSOutput</code>, a
370     * "no-output-specified" fatal error is raised.
371     * <br> The implementation is responsible of associating the appropriate
372     * media type with the serialized data.
373     * <br> When writing to a HTTP URI, a HTTP PUT is performed. When writing
374     * to other types of URIs, the mechanism for writing the data to the URI
375     * is implementation dependent.
376     * @param nodeArg  The node to serialize.
377     * @param destination The destination for the serialized DOM.
378     * @return  Returns <code>true</code> if <code>node</code> was
379     *   successfully serialized. Return <code>false</code> in case the
380     *   normal processing stopped but the implementation kept serializing
381     *   the document; the result of the serialization being implementation
382     *   dependent then.
383     * @exception LSException
384     *    SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to
385     *   serialize the node. DOM applications should attach a
386     *   <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
387     *   error-handler</a>" if they wish to get details on the error.
388     */
389    public boolean write(Node nodeArg,
390                         LSOutput destination)
391                         throws LSException;
392
393    /**
394     *  A convenience method that acts as if <code>LSSerializer.write</code>
395     * was called with a <code>LSOutput</code> with no encoding specified
396     * and <code>LSOutput.systemId</code> set to the <code>uri</code>
397     * argument.
398     * @param nodeArg  The node to serialize.
399     * @param uri The URI to write to.
400     * @return  Returns <code>true</code> if <code>node</code> was
401     *   successfully serialized. Return <code>false</code> in case the
402     *   normal processing stopped but the implementation kept serializing
403     *   the document; the result of the serialization being implementation
404     *   dependent then.
405     * @exception LSException
406     *    SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to
407     *   serialize the node. DOM applications should attach a
408     *   <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
409     *   error-handler</a>" if they wish to get details on the error.
410     */
411    public boolean writeToURI(Node nodeArg,
412                              String uri)
413                              throws LSException;
414
415    /**
416     *  Serialize the specified node as described above in the general
417     * description of the <code>LSSerializer</code> interface. The output is
418     * written to a <code>DOMString</code> that is returned to the caller.
419     * The encoding used is the encoding of the <code>DOMString</code> type,
420     * i.e. UTF-16. Note that no Byte Order Mark is generated in a
421     * <code>DOMString</code> object.
422     * @param nodeArg  The node to serialize.
423     * @return  Returns the serialized data.
424     * @exception DOMException
425     *    DOMSTRING_SIZE_ERR: Raised if the resulting string is too long to
426     *   fit in a <code>DOMString</code>.
427     * @exception LSException
428     *    SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to
429     *   serialize the node. DOM applications should attach a
430     *   <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
431     *   error-handler</a>" if they wish to get details on the error.
432     */
433    public String writeToString(Node nodeArg)
434                                throws DOMException, LSException;
435
436}