|
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>&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 '<' and '&' are replaced by |
|
122 * the predefined entities &lt; and &amp;. The other predefined |
|
123 * entities (&gt;, &apos;, and &quot;) might not be used, except |
|
124 * where needed (e.g. using &gt; in cases such as ']]>'). 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 * "&apos;", and the double-quote character (") as "&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 <LaCa\u00f1ada/> 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 } |