[188] | 1 | #ifndef DOMWriter_HEADER_GUARD_
|
---|
| 2 | #define DOMWriter_HEADER_GUARD_
|
---|
| 3 |
|
---|
| 4 | /*
|
---|
| 5 | * The Apache Software License, Version 1.1
|
---|
| 6 | *
|
---|
| 7 | * Copyright (c) 2002 The Apache Software Foundation. All rights
|
---|
| 8 | * reserved.
|
---|
| 9 | *
|
---|
| 10 | * Redistribution and use in source and binary forms, with or without
|
---|
| 11 | * modification, are permitted provided that the following conditions
|
---|
| 12 | * are met:
|
---|
| 13 | *
|
---|
| 14 | * 1. Redistributions of source code must retain the above copyright
|
---|
| 15 | * notice, this list of conditions and the following disclaimer.
|
---|
| 16 | *
|
---|
| 17 | * 2. Redistributions in binary form must reproduce the above copyright
|
---|
| 18 | * notice, this list of conditions and the following disclaimer in
|
---|
| 19 | * the documentation and/or other materials provided with the
|
---|
| 20 | * distribution.
|
---|
| 21 | *
|
---|
| 22 | * 3. The end-user documentation included with the redistribution,
|
---|
| 23 | * if any, must include the following acknowledgment:
|
---|
| 24 | * "This product includes software developed by the
|
---|
| 25 | * Apache Software Foundation (http://www.apache.org/)."
|
---|
| 26 | * Alternately, this acknowledgment may appear in the software itself,
|
---|
| 27 | * if and wherever such third-party acknowledgments normally appear.
|
---|
| 28 | *
|
---|
| 29 | * 4. The names "Xerces" and "Apache Software Foundation" must
|
---|
| 30 | * not be used to endorse or promote products derived from this
|
---|
| 31 | * software without prior written permission. For written
|
---|
| 32 | * permission, please contact apache\@apache.org.
|
---|
| 33 | *
|
---|
| 34 | * 5. Products derived from this software may not be called "Apache",
|
---|
| 35 | * nor may "Apache" appear in their name, without prior written
|
---|
| 36 | * permission of the Apache Software Foundation.
|
---|
| 37 | *
|
---|
| 38 | * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
|
---|
| 39 | * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
---|
| 40 | * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
---|
| 41 | * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
|
---|
| 42 | * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
---|
| 43 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
---|
| 44 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
|
---|
| 45 | * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
---|
| 46 | * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
---|
| 47 | * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
---|
| 48 | * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
---|
| 49 | * SUCH DAMAGE.
|
---|
| 50 | * ====================================================================
|
---|
| 51 | *
|
---|
| 52 | * This software consists of voluntary contributions made by many
|
---|
| 53 | * individuals on behalf of the Apache Software Foundation, and was
|
---|
| 54 | * originally based on software copyright (c) 1999, International
|
---|
| 55 | * Business Machines, Inc., http://www.ibm.com . For more information
|
---|
| 56 | * on the Apache Software Foundation, please see
|
---|
| 57 | * <http://www.apache.org/>.
|
---|
| 58 | */
|
---|
| 59 |
|
---|
| 60 | /*
|
---|
| 61 | * $Id: DOMWriter.hpp,v 1.10 2003/03/07 19:59:09 tng Exp $
|
---|
| 62 | * $Log: DOMWriter.hpp,v $
|
---|
| 63 | * Revision 1.10 2003/03/07 19:59:09 tng
|
---|
| 64 | * [Bug 11692] Unimplement the hidden constructors and assignment operator to remove warnings from gcc.
|
---|
| 65 | *
|
---|
| 66 | * Revision 1.9 2002/11/27 18:46:39 tng
|
---|
| 67 | * Documentation: clarify that DOMWriter::writeToString always returns string in UTF-16
|
---|
| 68 | *
|
---|
| 69 | * Revision 1.8 2002/11/04 15:09:25 tng
|
---|
| 70 | * C++ Namespace Support.
|
---|
| 71 | *
|
---|
| 72 | * Revision 1.7 2002/08/22 15:04:57 tng
|
---|
| 73 | * Remove unused parameter variables in inline functions.
|
---|
| 74 | *
|
---|
| 75 | * Revision 1.6 2002/06/25 16:04:49 tng
|
---|
| 76 | * DOM L3: add function release().
|
---|
| 77 | *
|
---|
| 78 | * Revision 1.5 2002/06/06 20:53:07 tng
|
---|
| 79 | * Documentation Fix: Update the API Documentation for DOM headers
|
---|
| 80 | *
|
---|
| 81 | * Revision 1.4 2002/06/03 22:33:21 peiyongz
|
---|
| 82 | * DOMWriter: constants moved to XMLUni
|
---|
| 83 | *
|
---|
| 84 | * Revision 1.3 2002/05/31 20:59:40 peiyongz
|
---|
| 85 | * Add "introduced in DOM3"
|
---|
| 86 | *
|
---|
| 87 | * Revision 1.2 2002/05/30 16:25:33 tng
|
---|
| 88 | * Fix doxygen warning message.
|
---|
| 89 | *
|
---|
| 90 | * Revision 1.1 2002/05/28 22:38:55 peiyongz
|
---|
| 91 | * DOM3 Save Interface: DOMWriter/DOMWriterFilter
|
---|
| 92 | *
|
---|
| 93 | */
|
---|
| 94 |
|
---|
| 95 | /**
|
---|
| 96 | *
|
---|
| 97 | * DOMWriter provides an API for serializing (writing) a DOM document out in
|
---|
| 98 | * an XML document. The XML data is written to an output stream, the type of
|
---|
| 99 | * which depends on the specific language bindings in use. During
|
---|
| 100 | * serialization of XML data, namespace fixup is done when possible.
|
---|
| 101 | * <p> <code>DOMWriter</code> accepts any node type for serialization. For
|
---|
| 102 | * nodes of type <code>Document</code> or <code>Entity</code>, well formed
|
---|
| 103 | * XML will be created if possible. The serialized output for these node
|
---|
| 104 | * types is either as a Document or an External Entity, respectively, and is
|
---|
| 105 | * acceptable input for an XML parser. For all other types of nodes the
|
---|
| 106 | * serialized form is not specified, but should be something useful to a
|
---|
| 107 | * human for debugging or diagnostic purposes. Note: rigorously designing an
|
---|
| 108 | * external (source) form for stand-alone node types that don't already have
|
---|
| 109 | * one defined in seems a bit much to take on here.
|
---|
| 110 | * <p>Within a Document or Entity being serialized, Nodes are processed as
|
---|
| 111 | * follows Documents are written including an XML declaration and a DTD
|
---|
| 112 | * subset, if one exists in the DOM. Writing a document node serializes the
|
---|
| 113 | * entire document. Entity nodes, when written directly by
|
---|
| 114 | * <code>writeNode</code> defined in the <code>DOMWriter</code> interface,
|
---|
| 115 | * output the entity expansion but no namespace fixup is done. The resulting
|
---|
| 116 | * output will be valid as an external entity. Entity References nodes are
|
---|
| 117 | * serializes as an entity reference of the form
|
---|
| 118 | * <code>"&entityName;"</code>) in the output. Child nodes (the
|
---|
| 119 | * expansion) of the entity reference are ignored. CDATA sections
|
---|
| 120 | * containing content characters that can not be represented in the
|
---|
| 121 | * specified output encoding are handled according to the
|
---|
| 122 | * "split-cdata-sections" feature.If the feature is <code>true</code>, CDATA
|
---|
| 123 | * sections are split, and the unrepresentable characters are serialized as
|
---|
| 124 | * numeric character references in ordinary content. The exact position and
|
---|
| 125 | * number of splits is not specified. If the feature is <code>false</code>,
|
---|
| 126 | * unrepresentable characters in a CDATA section are reported as errors. The
|
---|
| 127 | * error is not recoverable - there is no mechanism for supplying
|
---|
| 128 | * alternative characters and continuing with the serialization. All other
|
---|
| 129 | * node types (DOMElement, DOMText, etc.) are serialized to their corresponding
|
---|
| 130 | * XML source form.
|
---|
| 131 | * <p> Within the character data of a document (outside of markup), any
|
---|
| 132 | * characters that cannot be represented directly are replaced with
|
---|
| 133 | * character references. Occurrences of '<' and '&' are replaced by
|
---|
| 134 | * the predefined entities &lt; and &amp. The other predefined
|
---|
| 135 | * entities (&gt, &apos, etc.) are not used; these characters can be
|
---|
| 136 | * included directly. Any character that can not be represented directly in
|
---|
| 137 | * the output character encoding is serialized as a numeric character
|
---|
| 138 | * reference.
|
---|
| 139 | * <p> Attributes not containing quotes are serialized in quotes. Attributes
|
---|
| 140 | * containing quotes but no apostrophes are serialized in apostrophes
|
---|
| 141 | * (single quotes). Attributes containing both forms of quotes are
|
---|
| 142 | * serialized in quotes, with quotes within the value represented by the
|
---|
| 143 | * predefined entity &quot;. Any character that can not be represented
|
---|
| 144 | * directly in the output character encoding is serialized as a numeric
|
---|
| 145 | * character reference.
|
---|
| 146 | * <p> Within markup, but outside of attributes, any occurrence of a character
|
---|
| 147 | * that cannot be represented in the output character encoding is reported
|
---|
| 148 | * as an error. An example would be serializing the element
|
---|
| 149 | * <LaCañada/> with the encoding="us-ascii".
|
---|
| 150 | * <p> When requested by setting the <code>normalize-characters</code> feature
|
---|
| 151 | * on <code>DOMWriter</code>, all data to be serialized, both markup and
|
---|
| 152 | * character data, is W3C Text normalized according to the rules defined in
|
---|
| 153 | * . The W3C Text normalization process affects only the data as it is being
|
---|
| 154 | * written; it does not alter the DOM's view of the document after
|
---|
| 155 | * serialization has completed.
|
---|
| 156 | * <p>Namespaces are fixed up during serialization, the serialization process
|
---|
| 157 | * will verify that namespace declarations, namespace prefixes and the
|
---|
| 158 | * namespace URIs associated with Elements and Attributes are consistent. If
|
---|
| 159 | * inconsistencies are found, the serialized form of the document will be
|
---|
| 160 | * altered to remove them. The algorithm used for doing the namespace fixup
|
---|
| 161 | * while seralizing a document is a combination of the algorithms used for
|
---|
| 162 | * lookupNamespaceURI and lookupNamespacePrefix . previous paragraph to be
|
---|
| 163 | * defined closer here.
|
---|
| 164 | * <p>Any changes made affect only the namespace prefixes and declarations
|
---|
| 165 | * appearing in the serialized data. The DOM's view of the document is not
|
---|
| 166 | * altered by the serialization operation, and does not reflect any changes
|
---|
| 167 | * made to namespace declarations or prefixes in the serialized output.
|
---|
| 168 | * <p> While serializing a document the serializer will write out
|
---|
| 169 | * non-specified values (such as attributes whose <code>specified</code> is
|
---|
| 170 | * <code>false</code>) if the <code>output-default-values</code> feature is
|
---|
| 171 | * set to <code>true</code>. If the <code>output-default-values</code> flag
|
---|
| 172 | * is set to <code>false</code> and the <code>use-abstract-schema</code>
|
---|
| 173 | * feature is set to <code>true</code> the abstract schema will be used to
|
---|
| 174 | * determine if a value is specified or not, if
|
---|
| 175 | * <code>use-abstract-schema</code> is not set the <code>specified</code>
|
---|
| 176 | * flag on attribute nodes is used to determine if attribute values should
|
---|
| 177 | * be written out.
|
---|
| 178 | * <p> Ref to Core spec (1.1.9, XML namespaces, 5th paragraph) entity ref
|
---|
| 179 | * description about warning about unbound entity refs. Entity refs are
|
---|
| 180 | * always serialized as &foo;, also mention this in the load part of
|
---|
| 181 | * this spec.
|
---|
| 182 | * <p> When serializing a document the DOMWriter checks to see if the document
|
---|
| 183 | * element in the document is a DOM Level 1 element or a DOM Level 2 (or
|
---|
| 184 | * higher) element (this check is done by looking at the localName of the
|
---|
| 185 | * root element). If the root element is a DOM Level 1 element then the
|
---|
| 186 | * DOMWriter will issue an error if a DOM Level 2 (or higher) element is
|
---|
| 187 | * found while serializing. Likewise if the document element is a DOM Level
|
---|
| 188 | * 2 (or higher) element and the DOMWriter sees a DOM Level 1 element an
|
---|
| 189 | * error is issued. Mixing DOM Level 1 elements with DOM Level 2 (or higher)
|
---|
| 190 | * is not supported.
|
---|
| 191 | * <p> <code>DOMWriter</code>s have a number of named features that can be
|
---|
| 192 | * queried or set. The name of <code>DOMWriter</code> features must be valid
|
---|
| 193 | * XML names. Implementation specific features (extensions) should choose an
|
---|
| 194 | * implementation dependent prefix to avoid name collisions.
|
---|
| 195 | * <p>Here is a list of properties that must be recognized by all
|
---|
| 196 | * implementations.
|
---|
| 197 | * <dl>
|
---|
| 198 | * <dt><code>"normalize-characters"</code></dt>
|
---|
| 199 | * <dd>
|
---|
| 200 | * <dl>
|
---|
| 201 | * <dt><code>true</code></dt>
|
---|
| 202 | * <dd>[
|
---|
| 203 | * optional] (default) Perform the W3C Text Normalization of the characters
|
---|
| 204 | * in document as they are written out. Only the characters being written
|
---|
| 205 | * are (potentially) altered. The DOM document itself is unchanged. </dd>
|
---|
| 206 | * <dt>
|
---|
| 207 | * <code>false</code></dt>
|
---|
| 208 | * <dd>[required] do not perform character normalization. </dd>
|
---|
| 209 | * </dl></dd>
|
---|
| 210 | * <dt>
|
---|
| 211 | * <code>"split-cdata-sections"</code></dt>
|
---|
| 212 | * <dd>
|
---|
| 213 | * <dl>
|
---|
| 214 | * <dt><code>true</code></dt>
|
---|
| 215 | * <dd>[required] (default)
|
---|
| 216 | * Split CDATA sections containing the CDATA section termination marker
|
---|
| 217 | * ']]>' or characters that can not be represented in the output
|
---|
| 218 | * encoding, and output the characters using numeric character references.
|
---|
| 219 | * If a CDATA section is split a warning is issued. </dd>
|
---|
| 220 | * <dt><code>false</code></dt>
|
---|
| 221 | * <dd>[
|
---|
| 222 | * required] Signal an error if a <code>CDATASection</code> contains an
|
---|
| 223 | * unrepresentable character. </dd>
|
---|
| 224 | * </dl></dd>
|
---|
| 225 | * <dt><code>"validation"</code></dt>
|
---|
| 226 | * <dd>
|
---|
| 227 | * <dl>
|
---|
| 228 | * <dt><code>true</code></dt>
|
---|
| 229 | * <dd>[
|
---|
| 230 | * optional] Use the abstract schema to validate the document as it is being
|
---|
| 231 | * serialized. If validation errors are found the error handler is notified
|
---|
| 232 | * about the error. Setting this state will also set the feature
|
---|
| 233 | * <code>use-abstract-schema</code> to <code>true</code>. </dd>
|
---|
| 234 | * <dt><code>false</code></dt>
|
---|
| 235 | * <dd>[
|
---|
| 236 | * required] (default) Don't validate the document as it is being
|
---|
| 237 | * serialized. </dd>
|
---|
| 238 | * </dl></dd>
|
---|
| 239 | * <dt><code>"expand-entity-references"</code></dt>
|
---|
| 240 | * <dd>
|
---|
| 241 | * <dl>
|
---|
| 242 | * <dt><code>true</code></dt>
|
---|
| 243 | * <dd>[
|
---|
| 244 | * optional] Expand <code>EntityReference</code> nodes when serializing. </dd>
|
---|
| 245 | * <dt>
|
---|
| 246 | * <code>false</code></dt>
|
---|
| 247 | * <dd>[required] (default) Serialize all
|
---|
| 248 | * <code>EntityReference</code> nodes as XML entity references. </dd>
|
---|
| 249 | * </dl></dd>
|
---|
| 250 | * <dt>
|
---|
| 251 | * <code>"whitespace-in-element-content"</code></dt>
|
---|
| 252 | * <dd>
|
---|
| 253 | * <dl>
|
---|
| 254 | * <dt><code>true</code></dt>
|
---|
| 255 | * <dd>[required] (
|
---|
| 256 | * default) Output all white spaces in the document. </dd>
|
---|
| 257 | * <dt><code>false</code></dt>
|
---|
| 258 | * <dd>[
|
---|
| 259 | * optional] Only output white space that is not within element content. The
|
---|
| 260 | * implementation is expected to use the
|
---|
| 261 | * <code>isWhitespaceInElementContent</code> flag on <code>Text</code> nodes
|
---|
| 262 | * to determine if a text node should be written out or not. </dd>
|
---|
| 263 | * </dl></dd>
|
---|
| 264 | * <dt>
|
---|
| 265 | * <code>"discard-default-content"</code></dt>
|
---|
| 266 | * <dd>
|
---|
| 267 | * <dl>
|
---|
| 268 | * <dt><code>true</code></dt>
|
---|
| 269 | * <dd>[required] (default
|
---|
| 270 | * ) Use whatever information available to the implementation (i.e. XML
|
---|
| 271 | * schema, DTD, the <code>specified</code> flag on <code>Attr</code> nodes,
|
---|
| 272 | * and so on) to decide what attributes and content should be serialized or
|
---|
| 273 | * not. Note that the <code>specified</code> flag on <code>Attr</code> nodes
|
---|
| 274 | * in itself is not always reliable, it is only reliable when it is set to
|
---|
| 275 | * <code>false</code> since the only case where it can be set to
|
---|
| 276 | * <code>false</code> is if the attribute was created by a Level 1
|
---|
| 277 | * implementation. </dd>
|
---|
| 278 | * <dt><code>false</code></dt>
|
---|
| 279 | * <dd>[required] Output all attributes and
|
---|
| 280 | * all content. </dd>
|
---|
| 281 | * </dl></dd>
|
---|
| 282 | * <dt><code>"format-canonical"</code></dt>
|
---|
| 283 | * <dd>
|
---|
| 284 | * <dl>
|
---|
| 285 | * <dt><code>true</code></dt>
|
---|
| 286 | * <dd>[optional]
|
---|
| 287 | * This formatting writes the document according to the rules specified in .
|
---|
| 288 | * Setting this feature to true will set the feature "format-pretty-print"
|
---|
| 289 | * to false. </dd>
|
---|
| 290 | * <dt><code>false</code></dt>
|
---|
| 291 | * <dd>[required] (default) Don't canonicalize the
|
---|
| 292 | * output. </dd>
|
---|
| 293 | * </dl></dd>
|
---|
| 294 | * <dt><code>"format-pretty-print"</code></dt>
|
---|
| 295 | * <dd>
|
---|
| 296 | * <dl>
|
---|
| 297 | * <dt><code>true</code></dt>
|
---|
| 298 | * <dd>[optional]
|
---|
| 299 | * Formatting the output by adding whitespace to produce a pretty-printed,
|
---|
| 300 | * indented, human-readable form. The exact form of the transformations is
|
---|
| 301 | * not specified by this specification. Setting this feature to true will
|
---|
| 302 | * set the feature "format-canonical" to false. </dd>
|
---|
| 303 | * <dt><code>false</code></dt>
|
---|
| 304 | * <dd>[required]
|
---|
| 305 | * (default) Don't pretty-print the result. </dd>
|
---|
| 306 | * </dl></dd>
|
---|
| 307 | * </dl>
|
---|
| 308 | * <p>See also the <a href='http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409'>Document Object Model (DOM) Level 3 Abstract Schemas and Load
|
---|
| 309 | * and Save Specification</a>.
|
---|
| 310 | *
|
---|
| 311 | * @since DOM Level 3
|
---|
| 312 | */
|
---|
| 313 |
|
---|
| 314 |
|
---|
| 315 | #include <xercesc/dom/DOMNode.hpp>
|
---|
| 316 | #include <xercesc/dom/DOMWriterFilter.hpp>
|
---|
| 317 | #include <xercesc/dom/DOMErrorHandler.hpp>
|
---|
| 318 | #include <xercesc/framework/XMLFormatter.hpp>
|
---|
| 319 |
|
---|
| 320 | XERCES_CPP_NAMESPACE_BEGIN
|
---|
| 321 |
|
---|
| 322 | class CDOM_EXPORT DOMWriter {
|
---|
| 323 | protected :
|
---|
| 324 | // -----------------------------------------------------------------------
|
---|
| 325 | // Hidden constructors
|
---|
| 326 | // -----------------------------------------------------------------------
|
---|
| 327 | /** @name Hidden constructors */
|
---|
| 328 | //@{
|
---|
| 329 | DOMWriter() {};
|
---|
| 330 | //@}
|
---|
| 331 | private:
|
---|
| 332 | // -----------------------------------------------------------------------
|
---|
| 333 | // Unimplemented constructors and operators
|
---|
| 334 | // -----------------------------------------------------------------------
|
---|
| 335 | /** @name Unimplemented constructors and operators */
|
---|
| 336 | //@{
|
---|
| 337 | DOMWriter(const DOMWriter &);
|
---|
| 338 | DOMWriter & operator = (const DOMWriter &);
|
---|
| 339 | //@}
|
---|
| 340 |
|
---|
| 341 |
|
---|
| 342 | public:
|
---|
| 343 | // -----------------------------------------------------------------------
|
---|
| 344 | // All constructors are hidden, just the destructor is available
|
---|
| 345 | // -----------------------------------------------------------------------
|
---|
| 346 | /** @name Destructor */
|
---|
| 347 | //@{
|
---|
| 348 | /**
|
---|
| 349 | * Destructor
|
---|
| 350 | *
|
---|
| 351 | */
|
---|
| 352 | virtual ~DOMWriter() {};
|
---|
| 353 | //@}
|
---|
| 354 |
|
---|
| 355 | // -----------------------------------------------------------------------
|
---|
| 356 | // Virtual DOMWriter interface
|
---|
| 357 | // -----------------------------------------------------------------------
|
---|
| 358 | /** @name Functions introduced in DOM Level 3 */
|
---|
| 359 | //@{
|
---|
| 360 | // -----------------------------------------------------------------------
|
---|
| 361 | // Feature methods
|
---|
| 362 | // -----------------------------------------------------------------------
|
---|
| 363 | /**
|
---|
| 364 | * Query whether setting a feature to a specific value is supported.
|
---|
| 365 | * <br>The feature name has the same form as a DOM hasFeature string.
|
---|
| 366 | *
|
---|
| 367 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 368 | *
|
---|
| 369 | * @param featName The feature name, which is a DOM has-feature style string.
|
---|
| 370 | * @param state The requested state of the feature (<code>true</code> or
|
---|
| 371 | * <code>false</code>).
|
---|
| 372 | * @return <code>true</code> if the feature could be successfully set to
|
---|
| 373 | * the specified value, or <code>false</code> if the feature is not
|
---|
| 374 | * recognized or the requested value is not supported. The value of
|
---|
| 375 | * the feature itself is not changed.
|
---|
| 376 | * @since DOM Level 3
|
---|
| 377 | */
|
---|
| 378 | virtual bool canSetFeature(const XMLCh* const featName
|
---|
| 379 | , bool state) const = 0;
|
---|
| 380 | /**
|
---|
| 381 | * Set the state of a feature.
|
---|
| 382 | * <br>The feature name has the same form as a DOM hasFeature string.
|
---|
| 383 | * <br>It is possible for a <code>DOMWriter</code> to recognize a feature
|
---|
| 384 | * name but to be unable to set its value.
|
---|
| 385 | *
|
---|
| 386 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 387 | *
|
---|
| 388 | * @param featName The feature name.
|
---|
| 389 | * @param state The requested state of the feature (<code>true</code> or
|
---|
| 390 | * <code>false</code>).
|
---|
| 391 | * @exception DOMException
|
---|
| 392 | * Raise a NOT_SUPPORTED_ERR exception when the <code>DOMWriter</code>
|
---|
| 393 | * recognizes the feature name but cannot set the requested value.
|
---|
| 394 | * <br>Raise a NOT_FOUND_ERR When the <code>DOMWriter</code> does not
|
---|
| 395 | * recognize the feature name.
|
---|
| 396 | * @see getFeature
|
---|
| 397 | * @since DOM Level 3
|
---|
| 398 | */
|
---|
| 399 | virtual void setFeature(const XMLCh* const featName
|
---|
| 400 | , bool state) = 0;
|
---|
| 401 |
|
---|
| 402 | /**
|
---|
| 403 | * Look up the value of a feature.
|
---|
| 404 | * <br>The feature name has the same form as a DOM hasFeature string
|
---|
| 405 | * @param featName The feature name, which is a string with DOM has-feature
|
---|
| 406 | * syntax.
|
---|
| 407 | * @return The current state of the feature (<code>true</code> or
|
---|
| 408 | * <code>false</code>).
|
---|
| 409 | * @exception DOMException
|
---|
| 410 | * Raise a NOT_FOUND_ERR When the <code>DOMWriter</code> does not
|
---|
| 411 | * recognize the feature name.
|
---|
| 412 | *
|
---|
| 413 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 414 | *
|
---|
| 415 | * @see setFeature
|
---|
| 416 | * @since DOM Level 3
|
---|
| 417 | */
|
---|
| 418 | virtual bool getFeature(const XMLCh* const featName) const = 0;
|
---|
| 419 |
|
---|
| 420 | // -----------------------------------------------------------------------
|
---|
| 421 | // Setter methods
|
---|
| 422 | // -----------------------------------------------------------------------
|
---|
| 423 | /**
|
---|
| 424 | * The character encoding in which the output will be written.
|
---|
| 425 | * <br> The encoding to use when writing is determined as follows: If the
|
---|
| 426 | * encoding attribute has been set, that value will be used.If the
|
---|
| 427 | * encoding attribute is <code>null</code> or empty, but the item to be
|
---|
| 428 | * written includes an encoding declaration, that value will be used.If
|
---|
| 429 | * neither of the above provides an encoding name, a default encoding of
|
---|
| 430 | * "UTF-8" will be used.
|
---|
| 431 | * <br>The default value is <code>null</code>.
|
---|
| 432 | *
|
---|
| 433 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 434 | *
|
---|
| 435 | * @param encoding The character encoding in which the output will be written.
|
---|
| 436 | * @see getEncoding
|
---|
| 437 | * @since DOM Level 3
|
---|
| 438 | */
|
---|
| 439 | virtual void setEncoding(const XMLCh* const encoding) = 0;
|
---|
| 440 |
|
---|
| 441 | /**
|
---|
| 442 | * The end-of-line sequence of characters to be used in the XML being
|
---|
| 443 | * written out. The only permitted values are these:
|
---|
| 444 | * <dl>
|
---|
| 445 | * <dt><code>null</code></dt>
|
---|
| 446 | * <dd>
|
---|
| 447 | * Use a default end-of-line sequence. DOM implementations should choose
|
---|
| 448 | * the default to match the usual convention for text files in the
|
---|
| 449 | * environment being used. Implementations must choose a default
|
---|
| 450 | * sequence that matches one of those allowed by 2.11 "End-of-Line
|
---|
| 451 | * Handling". </dd>
|
---|
| 452 | * <dt>CR</dt>
|
---|
| 453 | * <dd>The carriage-return character (#xD).</dd>
|
---|
| 454 | * <dt>CR-LF</dt>
|
---|
| 455 | * <dd> The
|
---|
| 456 | * carriage-return and line-feed characters (#xD #xA). </dd>
|
---|
| 457 | * <dt>LF</dt>
|
---|
| 458 | * <dd> The line-feed
|
---|
| 459 | * character (#xA). </dd>
|
---|
| 460 | * </dl>
|
---|
| 461 | * <br>The default value for this attribute is <code>null</code>.
|
---|
| 462 | *
|
---|
| 463 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 464 | *
|
---|
| 465 | * @param newLine The end-of-line sequence of characters to be used.
|
---|
| 466 | * @see getNewLine
|
---|
| 467 | * @since DOM Level 3
|
---|
| 468 | */
|
---|
| 469 | virtual void setNewLine(const XMLCh* const newLine) = 0;
|
---|
| 470 |
|
---|
| 471 | /**
|
---|
| 472 | * The error handler that will receive error notifications during
|
---|
| 473 | * serialization. The node where the error occured is passed to this
|
---|
| 474 | * error handler, any modification to nodes from within an error
|
---|
| 475 | * callback should be avoided since this will result in undefined,
|
---|
| 476 | * implementation dependent behavior.
|
---|
| 477 | *
|
---|
| 478 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 479 | *
|
---|
| 480 | * @param errorHandler The error handler to be used.
|
---|
| 481 | * @see getErrorHandler
|
---|
| 482 | * @since DOM Level 3
|
---|
| 483 | */
|
---|
| 484 | virtual void setErrorHandler(DOMErrorHandler *errorHandler) = 0;
|
---|
| 485 |
|
---|
| 486 | /**
|
---|
| 487 | * When the application provides a filter, the serializer will call out
|
---|
| 488 | * to the filter before serializing each Node. Attribute nodes are never
|
---|
| 489 | * passed to the filter. The filter implementation can choose to remove
|
---|
| 490 | * the node from the stream or to terminate the serialization early.
|
---|
| 491 | *
|
---|
| 492 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 493 | *
|
---|
| 494 | * @param filter The writer filter to be used.
|
---|
| 495 | * @see getFilter
|
---|
| 496 | * @since DOM Level 3
|
---|
| 497 | */
|
---|
| 498 | virtual void setFilter(DOMWriterFilter *filter) = 0;
|
---|
| 499 |
|
---|
| 500 | // -----------------------------------------------------------------------
|
---|
| 501 | // Getter methods
|
---|
| 502 | // -----------------------------------------------------------------------
|
---|
| 503 | /**
|
---|
| 504 | * Return the character encoding in which the output will be written.
|
---|
| 505 | *
|
---|
| 506 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 507 | *
|
---|
| 508 | * @return The character encoding used.
|
---|
| 509 | * @see setEncoding
|
---|
| 510 | * @since DOM Level 3
|
---|
| 511 | */
|
---|
| 512 | virtual const XMLCh* getEncoding() const = 0;
|
---|
| 513 |
|
---|
| 514 | /**
|
---|
| 515 | * Return the end-of-line sequence of characters to be used in the XML being
|
---|
| 516 | * written out.
|
---|
| 517 | *
|
---|
| 518 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 519 | *
|
---|
| 520 | * @return The end-of-line sequence of characters to be used.
|
---|
| 521 | * @see setNewLine
|
---|
| 522 | * @since DOM Level 3
|
---|
| 523 | */
|
---|
| 524 | virtual const XMLCh* getNewLine() const = 0;
|
---|
| 525 |
|
---|
| 526 | /**
|
---|
| 527 | * Return the error handler that will receive error notifications during
|
---|
| 528 | * serialization.
|
---|
| 529 | *
|
---|
| 530 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 531 | *
|
---|
| 532 | * @return The error handler to be used.
|
---|
| 533 | * @see setErrorHandler
|
---|
| 534 | * @since DOM Level 3
|
---|
| 535 | */
|
---|
| 536 | virtual DOMErrorHandler* getErrorHandler() const = 0;
|
---|
| 537 |
|
---|
| 538 | /**
|
---|
| 539 | * Return the WriterFilter used.
|
---|
| 540 | *
|
---|
| 541 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 542 | *
|
---|
| 543 | * @return The writer filter used.
|
---|
| 544 | * @see setFilter
|
---|
| 545 | * @since DOM Level 3
|
---|
| 546 | */
|
---|
| 547 | virtual DOMWriterFilter* getFilter() const = 0;
|
---|
| 548 |
|
---|
| 549 | // -----------------------------------------------------------------------
|
---|
| 550 | // Write methods
|
---|
| 551 | // -----------------------------------------------------------------------
|
---|
| 552 | /**
|
---|
| 553 | * Write out the specified node as described above in the description of
|
---|
| 554 | * <code>DOMWriter</code>. Writing a Document or Entity node produces a
|
---|
| 555 | * serialized form that is well formed XML. Writing other node types
|
---|
| 556 | * produces a fragment of text in a form that is not fully defined by
|
---|
| 557 | * this document, but that should be useful to a human for debugging or
|
---|
| 558 | * diagnostic purposes.
|
---|
| 559 | *
|
---|
| 560 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 561 | *
|
---|
| 562 | * @param destination The destination for the data to be written.
|
---|
| 563 | * @param nodeToWrite The <code>Document</code> or <code>Entity</code> node to
|
---|
| 564 | * be written. For other node types, something sensible should be
|
---|
| 565 | * written, but the exact serialized form is not specified.
|
---|
| 566 | * @return Returns <code>true</code> if <code>node</code> was
|
---|
| 567 | * successfully serialized and <code>false</code> in case a failure
|
---|
| 568 | * occured and the failure wasn't canceled by the error handler.
|
---|
| 569 | * @exception DOMSystemException
|
---|
| 570 | * This exception will be raised in response to any sort of IO or system
|
---|
| 571 | * error that occurs while writing to the destination. It may wrap an
|
---|
| 572 | * underlying system exception.
|
---|
| 573 | * @since DOM Level 3
|
---|
| 574 | */
|
---|
| 575 | virtual bool writeNode(XMLFormatTarget* const destination
|
---|
| 576 | , const DOMNode &nodeToWrite) = 0;
|
---|
| 577 |
|
---|
| 578 | /**
|
---|
| 579 | * Serialize the specified node as described above in the description of
|
---|
| 580 | * <code>DOMWriter</code>. The result of serializing the node is
|
---|
| 581 | * returned as a string. Writing a Document or Entity node produces a
|
---|
| 582 | * serialized form that is well formed XML. Writing other node types
|
---|
| 583 | * produces a fragment of text in a form that is not fully defined by
|
---|
| 584 | * this document, but that should be useful to a human for debugging or
|
---|
| 585 | * diagnostic purposes.
|
---|
| 586 | *
|
---|
| 587 | * <p><b>"Experimental - subject to change"</b></p>
|
---|
| 588 | *
|
---|
| 589 | * @param nodeToWrite The node to be written.
|
---|
| 590 | * @return Returns the serialized data, or <code>null</code> in case a
|
---|
| 591 | * failure occured and the failure wasn't canceled by the error
|
---|
| 592 | * handler. The returned string is always in UTF-16.
|
---|
| 593 | * The encoding information available in DOMWriter is ignored in writeToString().
|
---|
| 594 | * @since DOM Level 3
|
---|
| 595 | */
|
---|
| 596 | virtual XMLCh* writeToString(const DOMNode &nodeToWrite) = 0;
|
---|
| 597 |
|
---|
| 598 | //@}
|
---|
| 599 |
|
---|
| 600 | // -----------------------------------------------------------------------
|
---|
| 601 | // Non-standard Extension
|
---|
| 602 | // -----------------------------------------------------------------------
|
---|
| 603 | /** @name Non-standard Extension */
|
---|
| 604 | //@{
|
---|
| 605 | /**
|
---|
| 606 | * Called to indicate that this Writer is no longer in use
|
---|
| 607 | * and that the implementation may relinquish any resources associated with it.
|
---|
| 608 | *
|
---|
| 609 | * Access to a released object will lead to unexpected result.
|
---|
| 610 | */
|
---|
| 611 | virtual void release() = 0;
|
---|
| 612 | //@}
|
---|
| 613 |
|
---|
| 614 |
|
---|
| 615 | };
|
---|
| 616 |
|
---|
| 617 | XERCES_CPP_NAMESPACE_END
|
---|
| 618 |
|
---|
| 619 | #endif
|
---|