DOMWriter.hpp
上传用户:zhuqijet
上传日期:2013-06-25
资源大小:10074k
文件大小:27k
源码类别:

词法分析

开发平台:

Visual C++

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