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

词法分析

开发平台:

Visual C++

  1. /*
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 1999-2002 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Xerces" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation, and was
  51.  * originally based on software copyright (c) 1999, International
  52.  * Business Machines, Inc., http://www.ibm.com .  For more information
  53.  * on the Apache Software Foundation, please see
  54.  * <http://www.apache.org/>.
  55.  */
  56. /*
  57.  * $Id: DOMParser.hpp,v 1.18 2003/05/22 02:26:50 knoaman Exp $
  58.  *
  59.  */
  60. #if !defined(DOMPARSER_HPP)
  61. #define DOMPARSER_HPP
  62. #include <xercesc/framework/XMLDocumentHandler.hpp>
  63. #include <xercesc/framework/XMLErrorReporter.hpp>
  64. #include <xercesc/framework/XMLEntityHandler.hpp>
  65. #include <xercesc/util/ValueStackOf.hpp>
  66. #include <xercesc/validators/DTD/DocTypeHandler.hpp>
  67. #include <xercesc/validators/DTD/DTDElementDecl.hpp>
  68. #include "DOM_Document.hpp"
  69. #include "DOM_DocumentType.hpp"
  70. XERCES_CPP_NAMESPACE_BEGIN
  71. class EntityResolver;
  72. class ErrorHandler;
  73. class XMLPScanToken;
  74. class XMLScanner;
  75. class XMLValidator;
  76. class Grammar;
  77. class GrammarResolver;
  78. /**
  79.   * This class implements the Document Object Model (DOM) interface.
  80.   * It should be used by applications which choose to parse and
  81.   * process the XML document using the DOM api's. This implementation
  82.   * also allows the applications to install an error and an entitty
  83.   * handler (useful extensions to the DOM specification).
  84.   *
  85.   * <p>It can be used to instantiate a validating or non-validating
  86.   * parser, by setting a member flag.</p>
  87.   */
  88. class PARSERS_EXPORT DOMParser :
  89.     public XMLDocumentHandler
  90.     , public XMLErrorReporter
  91.     , public XMLEntityHandler
  92.     , public DocTypeHandler
  93.     , public XMemory
  94. {
  95. public :
  96.     // -----------------------------------------------------------------------
  97.     //  Class types
  98.     // -----------------------------------------------------------------------
  99.     enum ValSchemes
  100.     {
  101.         Val_Never
  102.         , Val_Always
  103.         , Val_Auto
  104.     };
  105.     // -----------------------------------------------------------------------
  106.     //  Constructors and Detructor
  107.     // -----------------------------------------------------------------------
  108.     /** @name Constructors and Destructor */
  109.     //@{
  110.     /** Construct a DOMParser, with an optional validator
  111.       *
  112.       * Constructor with an instance of validator class to use for
  113.       * validation. If you don't provide a validator, a default one will
  114.       * be created for you in the scanner.
  115.       *
  116.       * @param valToAdopt Pointer to the validator instance to use. The
  117.       *                   parser is responsible for freeing the memory.
  118.       */
  119.     DOMParser
  120.     (
  121.           XMLValidator* const  valToAdopt = 0
  122.         , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
  123.     );
  124.     /**
  125.       * Destructor
  126.       */
  127.     ~DOMParser();
  128.     //@}
  129.     /** Reset the parser
  130.       *
  131.       * This method resets the state of the DOM driver and makes
  132.       * it ready for a fresh parse run.
  133.       */
  134.     void reset();
  135.     // -----------------------------------------------------------------------
  136.     //  Getter methods
  137.     // -----------------------------------------------------------------------
  138.     /** @name Getter methods */
  139.     //@{
  140.     /** Get the DOM document
  141.       *
  142.       * This method returns the DOM_Document object representing the
  143.       * root of the document tree. This object provides the primary
  144.       * access to the document's data.
  145.       *
  146.       * @return The DOM_Document object which represents the entire
  147.       *         XML document.
  148.       */
  149.     DOM_Document getDocument();
  150.     /** Get a pointer to the error handler
  151.       *
  152.       * This method returns the installed error handler. If no handler
  153.       * has been installed, then it will be a zero pointer.
  154.       *
  155.       * @return The pointer to the installed error handler object.
  156.       */
  157.     ErrorHandler* getErrorHandler();
  158.     /** Get a const pointer to the error handler
  159.       *
  160.       * This method returns the installed error handler.  If no handler
  161.       * has been installed, then it will be a zero pointer.
  162.       *
  163.       * @return A const pointer to the installed error handler object.
  164.       */
  165.     const ErrorHandler* getErrorHandler() const;
  166.     /** Get a pointer to the entity resolver
  167.       *
  168.       * This method returns the installed entity resolver.  If no resolver
  169.       * has been installed, then it will be a zero pointer.
  170.       *
  171.       * @return The pointer to the installed entity resolver object.
  172.       */
  173.     EntityResolver* getEntityResolver();
  174.     /** Get a const pointer to the entity resolver
  175.       *
  176.       * This method returns the installed entity resolver. If no resolver
  177.       * has been installed, then it will be a zero pointer.
  178.       *
  179.       * @return A const pointer to the installed entity resolver object.
  180.       */
  181.     const EntityResolver* getEntityResolver() const;
  182.     /** Get a const reference to the underlying scanner
  183.       *
  184.       * This method returns a reference to the underlying scanner object.
  185.       * It allows read only access to data maintained in the scanner.
  186.       *
  187.       * @return A const reference to the underlying scanner object.
  188.       */
  189.     const XMLScanner& getScanner() const;
  190.     /** Get a const reference to the validator
  191.       *
  192.       * This method returns a reference to the parser's installed
  193.       * validator.
  194.       *
  195.       * @return A const reference to the installed validator object.
  196.       */
  197.     const XMLValidator& getValidator() const;
  198.     /**
  199.       * This method returns an enumerated value that indicates the current
  200.       * validation scheme set on this parser.
  201.       *
  202.       * @return The ValSchemes value current set on this parser.
  203.       * @see #setValidationScheme
  204.       */
  205.     ValSchemes getValidationScheme() const;
  206.     /** Get the 'do schema' flag
  207.       *
  208.       * This method returns the state of the parser's schema processing
  209.       * flag.
  210.       *
  211.       * @return true, if the parser is currently configured to
  212.       *         understand schema, false otherwise.
  213.       *
  214.       * @see #setDoSchema
  215.       */
  216.     bool getDoSchema() const;
  217.     /** Get the 'full schema constraint checking' flag
  218.       *
  219.       * This method returns the state of the parser's full schema constraint
  220.       * checking flag.
  221.       *
  222.       * @return true, if the parser is currently configured to
  223.       *         have full schema constraint checking, false otherwise.
  224.       *
  225.       * @see #setValidationSchemaFullChecking
  226.       */
  227.     bool getValidationSchemaFullChecking() const;
  228.     /** Get error count from the last parse operation.
  229.       *
  230.       * This method returns the error count from the last parse
  231.       * operation. Note that this count is actually stored in the
  232.       * scanner, so this method simply returns what the
  233.       * scanner reports.
  234.       *
  235.       * @return number of errors encountered during the latest
  236.       * parse operation.
  237.       *
  238.       */
  239.     int getErrorCount() const;
  240.     /** Get the 'do namespaces' flag
  241.       *
  242.       * This method returns the state of the parser's namespace processing
  243.       * flag.
  244.       *
  245.       * @return true, if the parser is currently configured to
  246.       *         understand namespaces, false otherwise.
  247.       *
  248.       * @see #setDoNamespaces
  249.       */
  250.     bool getDoNamespaces() const;
  251.     /** Get the 'exit on first error' flag
  252.       *
  253.       * This method returns the state of the parser's
  254.       * exit-on-First-Fatal-Error flag. If this flag is true, then the
  255.       * parse will exit the first time it sees any non-wellformed XML or
  256.       * any validity error. The default state is true.
  257.       *
  258.       * @return true, if the parser is currently configured to
  259.       *         exit on the first fatal error, false otherwise.
  260.       *
  261.       * @see #setExitOnFirstFatalError
  262.       */
  263.     bool getExitOnFirstFatalError() const;
  264.     /**
  265.       * This method returns the state of the parser's
  266.       * validation-constraint-fatal flag.
  267.       *
  268.       * @return true, if the parser is currently configured to
  269.       *         set validation constraint errors as fatal, false
  270.       *         otherwise.
  271.       *
  272.       * @see #setValidationContraintFatal
  273.       */
  274.     bool getValidationConstraintFatal() const;
  275.     /** Get the 'include entity references' flag
  276.       *
  277.       * This method returns the flag that specifies whether the parser is
  278.       * creating entity reference nodes in the DOM tree being produced.
  279.       *
  280.       * @return  The state of the create entity reference node
  281.       *               flag.
  282.       * @see #setCreateEntityReferenceNodes
  283.       */
  284.     bool  getCreateEntityReferenceNodes()const;
  285.    /** Get the 'include ignorable whitespace' flag.
  286.       *
  287.       * This method returns the state of the parser's include ignorable
  288.       * whitespace flag.
  289.       *
  290.       * @return 'true' if the include ignorable whitespace flag is set on
  291.       *         the parser, 'false' otherwise.
  292.       *
  293.       * @see #setIncludeIgnorableWhitespace
  294.       */
  295.     bool getIncludeIgnorableWhitespace() const;
  296.     /** Get the 'to create MXLDecl node' flag.
  297.       *
  298.       * This method returns the state of the parser's to create XMLDecl
  299.       * DOM Node flag.
  300.       *
  301.       * @return 'true' if the toCreateXMLDeclTypeNode flag is set on
  302.       *         the parser, 'false' otherwise.
  303.       *
  304.       */
  305.     bool getToCreateXMLDeclTypeNode() const;
  306.    /** Get the set of Namespace/SchemaLocation that is specified externaly.
  307.       *
  308.       * This method returns the list of Namespace/SchemaLocation that was
  309.       * specified using setExternalSchemaLocation.
  310.       *
  311.       * The parser owns the returned string, and the memory allocated for
  312.       * the returned string will be destroyed when the parser is deleted.
  313.       *
  314.       * To ensure assessiblity of the returned information after the parser
  315.       * is deleted, callers need to copy and store the returned information
  316.       * somewhere else.
  317.       *
  318.       * @return a pointer to the list of Namespace/SchemaLocation that was
  319.       *         specified externally.  The pointer spans the same life-time as
  320.       *         the parser.  A null pointer is returned if nothing
  321.       *         was specified externally.
  322.       *
  323.       * @see #setExternalSchemaLocation(const XMLCh* const)
  324.       */
  325.     XMLCh* getExternalSchemaLocation() const;
  326.    /** Get the noNamespace SchemaLocation that is specified externaly.
  327.       *
  328.       * This method returns the no target namespace XML Schema Location
  329.       * that was specified using setExternalNoNamespaceSchemaLocation.
  330.       *
  331.       * The parser owns the returned string, and the memory allocated for
  332.       * the returned string will be destroyed when the parser is deleted.
  333.       *
  334.       * To ensure assessiblity of the returned information after the parser
  335.       * is deleted, callers need to copy and store the returned information
  336.       * somewhere else.
  337.       *
  338.       * @return a pointer to the no target namespace Schema Location that was
  339.       *         specified externally.  The pointer spans the same life-time as
  340.       *         the parser.  A null pointer is returned if nothing
  341.       *         was specified externally.
  342.       *
  343.       * @see #setExternalNoNamespaceSchemaLocation(const XMLCh* const)
  344.       */
  345.     XMLCh* getExternalNoNamespaceSchemaLocation() const;
  346.     /** Get the 'Grammar caching' flag
  347.       *
  348.       * This method returns the state of the parser's grammar caching when
  349.       * parsing an XML document.
  350.       *
  351.       * @return true, if the parser is currently configured to
  352.       *         cache grammars, false otherwise.
  353.       *
  354.       * @see #cacheGrammarFromParse
  355.       */
  356.     bool isCachingGrammarFromParse() const;
  357.     /** Get the 'Use cached grammar' flag
  358.       *
  359.       * This method returns the state of the parser's use of cached grammar
  360.       * when parsing an XML document.
  361.       *
  362.       * @return true, if the parser is currently configured to
  363.       *         use cached grammars, false otherwise.
  364.       *
  365.       * @see #useCachedGrammarInParse
  366.       */
  367.     bool isUsingCachedGrammarInParse() const;
  368.     /**
  369.       * Get the 'calculate src offset flag'
  370.       *
  371.       * This method returns the state of the parser's src offset calculation
  372.       * when parsing an XML document.
  373.       *
  374.       * @return true, if the parser is currently configured to
  375.       *         calculate src offsets, false otherwise.
  376.       *
  377.       * @see #setCalculateSrcOfs
  378.       */
  379.     bool getCalculateSrcOfs() const;
  380.     /**
  381.       * Get the 'force standard uri flag'
  382.       *
  383.       * This method returns the state if the parser forces standard uri
  384.       *
  385.       * @return true, if the parser is currently configured to
  386.       *         force standard uri, i.e. malformed uri will be rejected.
  387.       *
  388.       * @see #setStandardUriConformant
  389.       */
  390.     bool getStandardUriConformant() const;
  391.     /**
  392.       * Retrieve the grammar that is associated with the specified namespace key
  393.       *
  394.       * @param  nameSpaceKey Namespace key
  395.       * @return Grammar associated with the Namespace key.
  396.       */
  397.     Grammar* getGrammar(const XMLCh* const nameSpaceKey);
  398.     /**
  399.       * Retrieve the grammar where the root element is declared.
  400.       *
  401.       * @return Grammar where root element declared
  402.       */
  403.     Grammar* getRootGrammar();
  404.     /**
  405.       * Returns the string corresponding to a URI id from the URI string pool.
  406.       *
  407.       * @param uriId id of the string in the URI string pool.
  408.       * @return URI string corresponding to the URI id.
  409.       */
  410.     const XMLCh* getURIText(unsigned int uriId) const;
  411.     /**
  412.       * Returns the current src offset within the input source.
  413.       *
  414.       * @return offset within the input source
  415.       */
  416.     unsigned int getSrcOffset() const;
  417.     //@}
  418.     // -----------------------------------------------------------------------
  419.     //  Setter methods
  420.     // -----------------------------------------------------------------------
  421.     /** @name Setter methods */
  422.     //@{
  423.     /** Set the error handler
  424.       *
  425.       * This method allows applications to install their own error handler
  426.       * to trap error and warning messages.
  427.       *
  428.       * <i>Any previously set handler is merely dropped, since the parser
  429.       * does not own them.</i>
  430.       *
  431.       * @param handler  A const pointer to the user supplied error
  432.       *                 handler.
  433.       *
  434.       * @see #getErrorHandler
  435.       */
  436.     void setErrorHandler(ErrorHandler* const handler);
  437.     /** Set the entity resolver
  438.       *
  439.       * This method allows applications to install their own entity
  440.       * resolver. By installing an entity resolver, the applications
  441.       * can trap and potentially redirect references to external
  442.       * entities.
  443.       *
  444.       * <i>Any previously set resolver is merely dropped, since the parser
  445.       * does not own them.</i>
  446.       *
  447.       * @param handler  A const pointer to the user supplied entity
  448.       *                 resolver.
  449.       *
  450.       * @see #getEntityResolver
  451.       */
  452.     void setEntityResolver(EntityResolver* const handler);
  453.     /** Set the 'do namespaces' flag
  454.       *
  455.       * This method allows users to enable or disable the parser's
  456.       * namespace processing. When set to true, parser starts enforcing
  457.       * all the constraints and rules specified by the NameSpace
  458.       * specification.
  459.       *
  460.       * The parser's default state is: false.
  461.       *
  462.       * @param newState The value specifying whether NameSpace rules should
  463.       *                 be enforced or not.
  464.       *
  465.       * @see #getDoNamespaces
  466.       */
  467.     void setDoNamespaces(const bool newState);
  468.     /** Set the 'exit on first error' flag
  469.       *
  470.       * This method allows users to set the parser's behaviour when it
  471.       * encounters the first fatal error. If set to true, the parser
  472.       * will exit at the first fatal error. If false, then it will
  473.       * report the error and continue processing.
  474.       *
  475.       * The default value is 'true' and the parser exits on the
  476.       * first fatal error.
  477.       *
  478.       * @param newState The value specifying whether the parser should
  479.       *                 continue or exit when it encounters the first
  480.       *                 fatal error.
  481.       *
  482.       * @see #getExitOnFirstFatalError
  483.       */
  484.     void setExitOnFirstFatalError(const bool newState);
  485.     /**
  486.       * This method allows users to set the parser's behaviour when it
  487.       * encounters a validtion constraint error. If set to true, and the
  488.       * the parser will treat validation error as fatal and will exit depends on the
  489.       * state of "getExitOnFirstFatalError". If false, then it will
  490.       * report the error and continue processing.
  491.       *
  492.       * Note: setting this true does not mean the validation error will be printed with
  493.       * the word "Fatal Error".   It is still printed as "Error", but the parser
  494.       * will exit if "setExitOnFirstFatalError" is set to true.
  495.       *
  496.       * <p>The default value is 'false'.</p>
  497.       *
  498.       * @param newState If true, the parser will exit if "setExitOnFirstFatalError"
  499.       *                 is set to true.
  500.       *
  501.       * @see #getValidationConstraintFatal
  502.       * @see #setExitOnFirstFatalError
  503.       */
  504.     void setValidationConstraintFatal(const bool newState);
  505.      /** Set the 'include entity references' flag
  506.       *
  507.       * This method allows the user to specify whether the parser should
  508.       * create entity reference nodes in the DOM tree being produced.
  509.       * When the 'create' flag is
  510.       * true, the parser will create EntityReference nodes in the DOM tree.
  511.       * The EntityReference nodes and their child nodes will be read-only.
  512.       * When the 'create' flag is false, no EntityReference nodes will be created.
  513.       * <p>The replacement text
  514.       * of the entity is included in either case, either as a
  515.       * child of the Entity Reference node or in place at the location
  516.       * of the reference.
  517.       * <p>The default value is 'true'.
  518.       *
  519.       * @param create The new state of the create entity reference nodes
  520.       *               flag.
  521.       * @see #getCreateEntityReferenceNodes
  522.       */
  523.     void setCreateEntityReferenceNodes(const bool create);
  524.    /** Set the 'include ignorable whitespace' flag
  525.       *
  526.       * This method allows the user to specify whether a validating parser
  527.       * should include ignorable whitespaces as text nodes.  It has no effect
  528.       * on non-validating parsers which always include non-markup text.
  529.       * <p>When set to true (also the default), ignorable whitespaces will be
  530.       * added to the DOM tree as text nodes.  The method
  531.       * DOM_Text::isIgnorableWhitespace() will return true for those text
  532.       * nodes only.
  533.       * <p>When set to false, all ignorable whitespace will be discarded and
  534.       * no text node is added to the DOM tree.  Note: applications intended
  535.       * to process the "xml:space" attribute should not set this flag to false.
  536.       * And this flag also overrides any schema datateye whitespace facets,
  537.       * that is, all ignorable whitespace will be discarded even though
  538.       * 'preserve' is set in schema datatype whitespace facets.
  539.       *
  540.       * @param include The new state of the include ignorable whitespace
  541.       *                flag.
  542.       *
  543.       * @see #getIncludeIgnorableWhitespace
  544.       */
  545.     void setIncludeIgnorableWhitespace(const bool include);
  546.     /**
  547.       * This method allows users to set the validation scheme to be used
  548.       * by this parser. The value is one of the ValSchemes enumerated values
  549.       * defined by this class:
  550.       *
  551.       * <br>  Val_Never  - turn off validation
  552.       * <br>  Val_Always - turn on validation
  553.       * <br>  Val_Auto   - turn on validation if any internal/external
  554.       *                  DTD subset have been seen
  555.       *
  556.       * <p>The parser's default state is: Val_Auto.</p>
  557.       *
  558.       * @param newScheme The new validation scheme to use.
  559.       *
  560.       * @see #getValidationScheme
  561.       */
  562.     void setValidationScheme(const ValSchemes newScheme);
  563.     /** Set the 'do schema' flag
  564.       *
  565.       * This method allows users to enable or disable the parser's
  566.       * schema processing. When set to false, parser will not process
  567.       * any schema found.
  568.       *
  569.       * The parser's default state is: false.
  570.       *
  571.       * Note: If set to true, namespace processing must also be turned on.
  572.       *
  573.       * @param newState The value specifying whether schema support should
  574.       *                 be enforced or not.
  575.       *
  576.       * @see #getDoSchema
  577.       */
  578.     void setDoSchema(const bool newState);
  579.     /**
  580.       * This method allows the user to turn full Schema constraint checking on/off.
  581.       * Only takes effect if Schema validation is enabled.
  582.       * If turned off, partial constraint checking is done.
  583.       *
  584.       * Full schema constraint checking includes those checking that may
  585.       * be time-consuming or memory intensive. Currently, particle unique
  586.       * attribution constraint checking and particle derivation resriction checking
  587.       * are controlled by this option.
  588.       *
  589.       * The parser's default state is: false.
  590.       *
  591.       * @param schemaFullChecking True to turn on full schema constraint checking.
  592.       *
  593.       * @see #getValidationSchemaFullChecking
  594.       */
  595.     void setValidationSchemaFullChecking(const bool schemaFullChecking);
  596.     /**
  597.       * This method allows users to set the toCreateXMLDeclTypeNode flag
  598.       * by this parser. By setting it to 'true' user can have XMLDecl type
  599.       * nodes attached to the DOM tree.
  600.       *
  601.       * <p>The parser's default state is: false </p>
  602.       *
  603.       * @param create The new to create XMLDecl type node flag
  604.       *
  605.       */
  606.     void setToCreateXMLDeclTypeNode(const bool create);
  607.     /**
  608.       * This method allows the user to specify a list of schemas to use.
  609.       * If the targetNamespace of a schema specified using this method matches
  610.       * the targetNamespace of a schema occuring in the instance document in
  611.       * the schemaLocation attribute, or if the targetNamespace matches the
  612.       * namespace attribute of the "import" element, the schema specified by the
  613.       * user using this method will be used (i.e., the schemaLocation attribute
  614.       * in the instance document or on the "import" element will be effectively ignored).
  615.       *
  616.       * If this method is called more than once, only the last one takes effect.
  617.       *
  618.       * The syntax is the same as for schemaLocation attributes in instance
  619.       * documents: e.g, "http://www.example.com file_name.xsd". The user can
  620.       * specify more than one XML Schema in the list.
  621.       *
  622.       * @param schemaLocation the list of schemas to use
  623.       *
  624.       * @see #getExternalSchemaLocation
  625.       */
  626.     void setExternalSchemaLocation(const XMLCh* const schemaLocation);
  627.     /**
  628.       * This method is same as setExternalSchemaLocation(const XMLCh* const).
  629.       * It takes native char string as parameter
  630.       *
  631.       * @param schemaLocation the list of schemas to use
  632.       *
  633.       * @see #setExternalSchemaLocation(const XMLCh* const)
  634.       */
  635.     void setExternalSchemaLocation(const char* const schemaLocation);
  636.     /**
  637.       * This method allows the user to specify the no target namespace XML
  638.       * Schema Location externally.  If specified, the instance document's
  639.       * noNamespaceSchemaLocation attribute will be effectively ignored.
  640.       *
  641.       * If this method is called more than once, only the last one takes effect.
  642.       *
  643.       * The syntax is the same as for the noNamespaceSchemaLocation attribute
  644.       * that may occur in an instance document: e.g."file_name.xsd".
  645.       *
  646.       * @param noNamespaceSchemaLocation the XML Schema Location with no target namespace
  647.       *
  648.       * @see #getExternalNoNamespaceSchemaLocation
  649.       */
  650.     void setExternalNoNamespaceSchemaLocation(const XMLCh* const noNamespaceSchemaLocation);
  651.     /**
  652.       * This method is same as setExternalNoNamespaceSchemaLocation(const XMLCh* const).
  653.       * It takes native char string as parameter
  654.       *
  655.       * @param noNamespaceSchemaLocation the XML Schema Location with no target namespace
  656.       *
  657.       * @see #setExternalNoNamespaceSchemaLocation(const XMLCh* const)
  658.       */
  659.     void setExternalNoNamespaceSchemaLocation(const char* const noNamespaceSchemaLocation);
  660.     /** Set the 'Grammar caching' flag
  661.       *
  662.       * This method allows users to enable or disable caching of grammar when
  663.       * parsing XML documents. When set to true, the parser will cache the
  664.       * resulting grammar for use in subsequent parses.
  665.       *
  666.       * If the flag is set to true, the 'Use cached grammar' flag will also be
  667.       * set to true.
  668.       *
  669.       * The parser's default state is: false.
  670.       *
  671.       * @param newState The value specifying whether we should cache grammars
  672.       *                 or not.
  673.       *
  674.       * @see #isCachingGrammarFromParse
  675.       * @see #useCachedGrammarInParse
  676.       */
  677.     void cacheGrammarFromParse(const bool newState);
  678.     /** Set the 'Use cached grammar' flag
  679.       *
  680.       * This method allows users to enable or disable the use of cached
  681.       * grammars.  When set to true, the parser will use the cached grammar,
  682.       * instead of building the grammar from scratch, to validate XML
  683.       * documents.
  684.       *
  685.       * If the 'Grammar caching' flag is set to true, this mehod ignore the
  686.       * value passed in.
  687.       *
  688.       * The parser's default state is: false.
  689.       *
  690.       * @param newState The value specifying whether we should use the cached
  691.       *                 grammar or not.
  692.       *
  693.       * @see #isUsingCachedGrammarInParse
  694.       * @see #cacheGrammarFromParse
  695.       */
  696.     void useCachedGrammarInParse(const bool newState);
  697.     /** Enable/disable src offset calculation
  698.       *
  699.       * This method allows users to enable/disable src offset calculation.
  700.       * Disabling the calculation will improve performance.
  701.       *
  702.       * The parser's default state is: false.
  703.       *
  704.       * @param newState The value specifying whether we should enable or
  705.       *                 disable src offset calculation
  706.       *
  707.       * @see #getCalculateSrcOfs
  708.       */
  709.     void setCalculateSrcOfs(const bool newState);
  710.     /** Force standard uri
  711.       *
  712.       * This method allows users to tell the parser to force standard uri conformance.
  713.       *
  714.       * The parser's default state is: false.
  715.       *
  716.       * @param newState The value specifying whether the parser should reject malformed URI.
  717.       *
  718.       * @see #getStandardUriConformant
  719.       */
  720.     void setStandardUriConformant(const bool newState);
  721.     /** Set the scanner to use when scanning the XML document
  722.       *
  723.       * This method allows users to set the scanner to use
  724.       * when scanning a given XML document.
  725.       *
  726.       * @param scannerName The name of the desired scanner
  727.       */
  728.     void useScanner(const XMLCh* const scannerName);
  729.     //@}
  730.     // -----------------------------------------------------------------------
  731.     //  Parsing methods
  732.     // -----------------------------------------------------------------------
  733.     /** @name Parsing methods */
  734.     //@{
  735.     /** Parse via an input source object
  736.       *
  737.       * This method invokes the parsing process on the XML file specified
  738.       * by the InputSource parameter. This API is borrowed from the
  739.       * SAX Parser interface.
  740.       *
  741.       * @param source A const reference to the InputSource object which
  742.       *               points to the XML file to be parsed.
  743.       * @exception SAXException Any SAX exception, possibly
  744.       *            wrapping another exception.
  745.       * @exception XMLException An exception from the parser or client
  746.       *            handler code.
  747.       * @exception DOM_DOMException A DOM exception as per DOM spec.
  748.       * @see InputSource#InputSource
  749.       * @see #setEntityResolver
  750.       * @see #setErrorHandler
  751.       */
  752.     void parse(const InputSource& source);
  753.     /** Parse via a file path or URL
  754.       *
  755.       * This method invokes the parsing process on the XML file specified by
  756.       * the Unicode string parameter 'systemId'. This method is borrowed
  757.       * from the SAX Parser interface.
  758.       *
  759.       * @param systemId A const XMLCh pointer to the Unicode string which
  760.       *                 contains the path to the XML file to be parsed.
  761.       *
  762.       * @exception SAXException Any SAX exception, possibly
  763.       *            wrapping another exception.
  764.       * @exception XMLException An exception from the parser or client
  765.       *            handler code.
  766.       * @exception DOM_DOMException A DOM exception as per DOM spec.
  767.       * @see #parse(InputSource,...)
  768.       */
  769.     void parse(const XMLCh* const systemId);
  770.     /** Parse via a file path or URL (in the local code page)
  771.       *
  772.       * This method invokes the parsing process on the XML file specified by
  773.       * the native char* string parameter 'systemId'.
  774.       *
  775.       * @param systemId A const char pointer to a native string which
  776.       *                 contains the path to the XML file to be parsed.
  777.       * @exception SAXException Any SAX exception, possibly
  778.       *            wrapping another exception.
  779.       * @exception XMLException An exception from the parser or client
  780.       *            handler code.
  781.       * @exception DOM_DOMException A DOM exception as per DOM spec.
  782.       * @see #parse(InputSource,...)
  783.       */
  784.     void parse(const char* const systemId);
  785.     /** Begin a progressive parse operation
  786.       *
  787.       * This method is used to start a progressive parse on a XML file.
  788.       * To continue parsing, subsequent calls must be to the parseNext
  789.       * method.
  790.       *
  791.       * It scans through the prolog and returns a token to be used on
  792.       * subsequent scanNext() calls. If the return value is true, then the
  793.       * token is legal and ready for further use. If it returns false, then
  794.       * the scan of the prolog failed and the token is not going to work on
  795.       * subsequent scanNext() calls.
  796.       *
  797.       * @param systemId A pointer to a Unicode string represting the path
  798.       *                 to the XML file to be parsed.
  799.       * @param toFill   A token maintaing state information to maintain
  800.       *                 internal consistency between invocation of 'parseNext'
  801.       *                 calls.
  802.       * @return 'true', if successful in parsing the prolog. It indicates the
  803.       *         user can go ahead with parsing the rest of the file. It
  804.       *         returns 'false' to indicate that the parser could not parse
  805.       *         the prolog.
  806.       *
  807.       * @see #parseNext
  808.       * @see #parseFirst(char*,...)
  809.       * @see #parseFirst(InputSource&,...)
  810.       */
  811.     bool parseFirst
  812.     (
  813.         const   XMLCh* const    systemId
  814.         ,       XMLPScanToken&  toFill
  815.     );
  816.     /** Begin a progressive parse operation
  817.       *
  818.       * This method is used to start a progressive parse on a XML file.
  819.       * To continue parsing, subsequent calls must be to the parseNext
  820.       * method.
  821.       *
  822.       * It scans through the prolog and returns a token to be used on
  823.       * subsequent scanNext() calls. If the return value is true, then the
  824.       * token is legal and ready for further use. If it returns false, then
  825.       * the scan of the prolog failed and the token is not going to work on
  826.       * subsequent scanNext() calls.
  827.       *
  828.       * @param systemId A pointer to a regular native string represting
  829.       *                 the path to the XML file to be parsed.
  830.       * @param toFill   A token maintaing state information to maintain
  831.       *                 internal consistency between invocation of 'parseNext'
  832.       *                 calls.
  833.       *
  834.       * @return 'true', if successful in parsing the prolog. It indicates the
  835.       *         user can go ahead with parsing the rest of the file. It
  836.       *         returns 'false' to indicate that the parser could not parse
  837.       *         the prolog.
  838.       *
  839.       * @see #parseNext
  840.       * @see #parseFirst(XMLCh*,...)
  841.       * @see #parseFirst(InputSource&,...)
  842.       */
  843.     bool parseFirst
  844.     (
  845.         const   char* const     systemId
  846.         ,       XMLPScanToken&  toFill
  847.     );
  848.     /** Begin a progressive parse operation
  849.       *
  850.       * This method is used to start a progressive parse on a XML file.
  851.       * To continue parsing, subsequent calls must be to the parseNext
  852.       * method.
  853.       *
  854.       * It scans through the prolog and returns a token to be used on
  855.       * subsequent scanNext() calls. If the return value is true, then the
  856.       * token is legal and ready for further use. If it returns false, then
  857.       * the scan of the prolog failed and the token is not going to work on
  858.       * subsequent scanNext() calls.
  859.       *
  860.       * @param source   A const reference to the InputSource object which
  861.       *                 points to the XML file to be parsed.
  862.       * @param toFill   A token maintaing state information to maintain
  863.       *                 internal consistency between invocation of 'parseNext'
  864.       *                 calls.
  865.       *
  866.       * @return 'true', if successful in parsing the prolog. It indicates the
  867.       *         user can go ahead with parsing the rest of the file. It
  868.       *         returns 'false' to indicate that the parser could not parse
  869.       *         the prolog.
  870.       *
  871.       * @see #parseNext
  872.       * @see #parseFirst(XMLCh*,...)
  873.       * @see #parseFirst(char*,...)
  874.       */
  875.     bool parseFirst
  876.     (
  877.         const   InputSource&    source
  878.         ,       XMLPScanToken&  toFill
  879.     );
  880.     /** Continue a progressive parse operation
  881.       *
  882.       * This method is used to continue with progressive parsing of
  883.       * XML files started by a call to 'parseFirst' method.
  884.       *
  885.       * It parses the XML file and stops as soon as it comes across
  886.       * a XML token (as defined in the XML specification).
  887.       *
  888.       * @param token A token maintaing state information to maintain
  889.       *              internal consistency between invocation of 'parseNext'
  890.       *              calls.
  891.       *
  892.       * @return 'true', if successful in parsing the next XML token.
  893.       *         It indicates the user can go ahead with parsing the rest
  894.       *         of the file. It returns 'false' to indicate that the parser
  895.       *         could not find next token as per the XML specification
  896.       *         production rule.
  897.       *
  898.       * @see #parseFirst(XMLCh*,...)
  899.       * @see #parseFirst(char*,...)
  900.       * @see #parseFirst(InputSource&,...)
  901.       */
  902.     bool parseNext(XMLPScanToken& token);
  903.     /** Reset the parser after a progressive parse
  904.       *
  905.       * If a progressive parse loop exits before the end of the document
  906.       * is reached, the parser has no way of knowing this. So it will leave
  907.       * open any files or sockets or memory buffers that were in use at
  908.       * the time that the parse loop exited.
  909.       *
  910.       * The next parse operation will cause these open files and such to
  911.       * be closed, but the next parse operation might occur at some unknown
  912.       * future point. To avoid this problem, you should reset the parser if
  913.       * you exit the loop early.
  914.       *
  915.       * If you exited because of an error, then this cleanup will be done
  916.       * for you. Its only when you exit the file prematurely of your own
  917.       * accord, because you've found what you wanted in the file most
  918.       * likely.
  919.       *
  920.       * @param token A token maintaing state information to maintain
  921.       *              internal consistency between invocation of 'parseNext'
  922.       *              calls.
  923.       *
  924.       * @see #parseFirst(XMLCh*,...)
  925.       * @see #parseFirst(char*,...)
  926.       * @see #parseFirst(InputSource&,...)
  927.       */
  928.     void parseReset(XMLPScanToken& token);
  929.     //@}
  930.     // -----------------------------------------------------------------------
  931.     //  Grammar preparsing interface
  932.     // -----------------------------------------------------------------------
  933.     /** @name Implementation of Grammar preparsing interface's. */
  934.     //@{
  935.     /**
  936.       * Preparse schema grammar (XML Schema, DTD, etc.) via an input source
  937.       * object.
  938.       *
  939.       * This method invokes the preparsing process on a schema grammar XML
  940.       * file specified by the SAX InputSource parameter. If the 'toCache' flag
  941.       * is enabled, the parser will cache the grammars for re-use. If a grammar
  942.       * key is found in the pool, no caching of any grammar will take place.
  943.       *
  944.       * <p><b>"Experimental - subject to change"</b></p>
  945.       *
  946.       * @param source A const reference to the SAX InputSource object which
  947.       *               points to the schema grammar file to be preparsed.
  948.       * @param grammarType The grammar type (Schema or DTD).
  949.       * @param toCache If <code>true</code>, we cache the preparsed grammar,
  950.       *                otherwise, no chaching. Default is <code>false</code>.
  951.       * @return The preparsed schema grammar object (SchemaGrammar or
  952.       *         DTDGrammar). That grammar object is owned by the parser.
  953.       *
  954.       * @exception SAXException Any SAX exception, possibly
  955.       *            wrapping another exception.
  956.       * @exception XMLException An exception from the parser or client
  957.       *            handler code.
  958.       * @exception DOMException A DOM exception as per DOM spec.
  959.       *
  960.       * @see InputSource#InputSource
  961.       */
  962.     Grammar* loadGrammar(const InputSource& source,
  963.                          const short grammarType,
  964.                          const bool toCache = false);
  965.     /**
  966.       * Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL
  967.       *
  968.       * This method invokes the preparsing process on a schema grammar XML
  969.       * file specified by the file path parameter. If the 'toCache' flag
  970.       * is enabled, the parser will cache the grammars for re-use. If a grammar
  971.       * key is found in the pool, no caching of any grammar will take place.
  972.       *
  973.       * <p><b>"Experimental - subject to change"</b></p>
  974.       *
  975.       * @param systemId A const XMLCh pointer to the Unicode string which
  976.       *                 contains the path to the XML grammar file to be
  977.       *                 preparsed.
  978.       * @param grammarType The grammar type (Schema or DTD).
  979.       * @param toCache If <code>true</code>, we cache the preparsed grammar,
  980.       *                otherwise, no chaching. Default is <code>false</code>.
  981.       * @return The preparsed schema grammar object (SchemaGrammar or
  982.       *         DTDGrammar). That grammar object is owned by the parser.
  983.       *
  984.       * @exception SAXException Any SAX exception, possibly
  985.       *            wrapping another exception.
  986.       * @exception XMLException An exception from the parser or client
  987.       *            handler code.
  988.       * @exception DOMException A DOM exception as per DOM spec.
  989.       */
  990.     Grammar* loadGrammar(const XMLCh* const systemId,
  991.                          const short grammarType,
  992.                          const bool toCache = false);
  993.     /**
  994.       * Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL
  995.       *
  996.       * This method invokes the preparsing process on a schema grammar XML
  997.       * file specified by the file path parameter. If the 'toCache' flag
  998.       * is enabled, the parser will cache the grammars for re-use. If a grammar
  999.       * key is found in the pool, no caching of any grammar will take place.
  1000.       *
  1001.       * <p><b>"Experimental - subject to change"</b></p>
  1002.       *
  1003.       * @param systemId A const char pointer to a native string which contains
  1004.       *                 the path to the XML grammar file to be preparsed.
  1005.       * @param grammarType The grammar type (Schema or DTD).
  1006.       * @param toCache If <code>true</code>, we cache the preparsed grammar,
  1007.       *                otherwise, no chaching. Default is <code>false</code>.
  1008.       * @return The preparsed schema grammar object (SchemaGrammar or
  1009.       *         DTDGrammar). That grammar object is owned by the parser.
  1010.       *
  1011.       * @exception SAXException Any SAX exception, possibly
  1012.       *            wrapping another exception.
  1013.       * @exception XMLException An exception from the parser or client
  1014.       *            handler code.
  1015.       * @exception DOMException A DOM exception as per DOM spec.
  1016.       */
  1017.     Grammar* loadGrammar(const char* const systemId,
  1018.                          const short grammarType,
  1019.                          const bool toCache = false);
  1020.     /**
  1021.       * This method allows the user to reset the pool of cached grammars.
  1022.       */
  1023.     void resetCachedGrammarPool();
  1024.     //@}
  1025.     // -----------------------------------------------------------------------
  1026.     //  Implementation of the XMLErrorReporter interface.
  1027.     // -----------------------------------------------------------------------
  1028.     /** @name Implementation of the XMLErrorReporter interface. */
  1029.     //@{
  1030.     /** Handle errors reported from the parser
  1031.       *
  1032.       * This method is used to report back errors found while parsing the
  1033.       * XML file. This method is also borrowed from the SAX specification.
  1034.       * It calls the corresponding user installed Error Handler method:
  1035.       * 'fatal', 'error', 'warning' depending on the severity of the error.
  1036.       * This classification is defined by the XML specification.
  1037.       *
  1038.       * @param errCode An integer code for the error.
  1039.       * @param msgDomain A const pointer to an Unicode string representing
  1040.       *                  the message domain to use.
  1041.       * @param errType An enumeration classifying the severity of the error.
  1042.       * @param errorText A const pointer to an Unicode string representing
  1043.       *                  the text of the error message.
  1044.       * @param systemId  A const pointer to an Unicode string representing
  1045.       *                  the system id of the XML file where this error
  1046.       *                  was discovered.
  1047.       * @param publicId  A const pointer to an Unicode string representing
  1048.       *                  the public id of the XML file where this error
  1049.       *                  was discovered.
  1050.       * @param lineNum   The line number where the error occurred.
  1051.       * @param colNum    The column number where the error occurred.
  1052.       * @see ErrorHandler
  1053.       */
  1054.     virtual void error
  1055.     (
  1056.         const   unsigned int                errCode
  1057.         , const XMLCh* const                msgDomain
  1058.         , const XMLErrorReporter::ErrTypes  errType
  1059.         , const XMLCh* const                errorText
  1060.         , const XMLCh* const                systemId
  1061.         , const XMLCh* const                publicId
  1062.         , const XMLSSize_t                  lineNum
  1063.         , const XMLSSize_t                  colNum
  1064.     );
  1065.     /** Reset any error data before a new parse
  1066.      *
  1067.       * This method allows the user installed Error Handler callback to
  1068.       * 'reset' itself.
  1069.       *
  1070.       * <b><font color="#FF0000">This method is a no-op for this DOM
  1071.       * implementation.</font></b>
  1072.       */
  1073.     virtual void resetErrors();
  1074.     //@}
  1075.     // -----------------------------------------------------------------------
  1076.     //  Implementation of the XMLEntityHandler interface.
  1077.     // -----------------------------------------------------------------------
  1078.     /** @name Implementation of the XMLEntityHandler interface. */
  1079.     //@{
  1080.     /** Handle an end of input source event
  1081.       *
  1082.       * This method is used to indicate the end of parsing of an external
  1083.       * entity file.
  1084.       *
  1085.       * <b><font color="#FF0000">This method is a no-op for this DOM
  1086.       * implementation.</font></b>
  1087.       *
  1088.       * @param inputSource A const reference to the InputSource object
  1089.       *                    which points to the XML file being parsed.
  1090.       * @see InputSource
  1091.       */
  1092.     virtual void endInputSource(const InputSource& inputSource);
  1093.     /** Expand a system id
  1094.       *
  1095.       * This method allows an installed XMLEntityHandler to further
  1096.       * process any system id's of enternal entities encountered in
  1097.       * the XML file being parsed, such as redirection etc.
  1098.       *
  1099.       * <b><font color="#FF0000">This method always returns 'false'
  1100.       * for this DOM implementation.</font></b>
  1101.       *
  1102.       * @param systemId  A const pointer to an Unicode string representing
  1103.       *                  the system id scanned by the parser.
  1104.       * @param toFill    A pointer to a buffer in which the application
  1105.       *                  processed system id is stored.
  1106.       * @return 'true', if any processing is done, 'false' otherwise.
  1107.       */
  1108.     virtual bool expandSystemId
  1109.     (
  1110.         const   XMLCh* const    systemId
  1111.         ,       XMLBuffer&      toFill
  1112.     );
  1113.     /** Reset any entity handler information
  1114.       *
  1115.       * This method allows the installed XMLEntityHandler to reset
  1116.       * itself.
  1117.       *
  1118.       * <b><font color="#FF0000">This method is a no-op for this DOM
  1119.       * implementation.</font></b>
  1120.       */
  1121.     virtual void resetEntities();
  1122.     /** Resolve a public/system id
  1123.       *
  1124.       * This method allows a user installed entity handler to further
  1125.       * process any pointers to external entities. The applications can
  1126.       * implement 'redirection' via this callback. This method is also
  1127.       * borrowed from the SAX specification.
  1128.       *
  1129.       * @param publicId A const pointer to a Unicode string representing the
  1130.       *                 public id of the entity just parsed.
  1131.       * @param systemId A const pointer to a Unicode string representing the
  1132.       *                 system id of the entity just parsed.
  1133.       * @param baseURI  A const pointer to a Unicode string representing the
  1134.       *                 base URI of the entity just parsed,
  1135.       *                 or <code>null</code> if there is no base URI.
  1136.       * @return The value returned by the user installed resolveEntity
  1137.       *         method or NULL otherwise to indicate no processing was done.
  1138.       *         The returned InputSource is owned by the parser which is
  1139.       *         responsible to clean up the memory.
  1140.       * @see EntityResolver
  1141.       * @see XMLEntityHandler
  1142.       */
  1143.     virtual InputSource* resolveEntity
  1144.     (
  1145.         const   XMLCh* const    publicId
  1146.         , const XMLCh* const    systemId
  1147.         , const XMLCh* const    baseURI = 0
  1148.     );
  1149.     /** Handle a 'start input source' event
  1150.       *
  1151.       * This method is used to indicate the start of parsing an external
  1152.       * entity file.
  1153.       *
  1154.       * <b><font color="#FF0000">This method is a no-op for this DOM parse
  1155.       * implementation.</font></b>
  1156.       *
  1157.       * @param inputSource A const reference to the InputSource object
  1158.       *                    which points to the external entity
  1159.       *                    being parsed.
  1160.       */
  1161.     virtual void startInputSource(const InputSource& inputSource);
  1162.     //@}
  1163.     // -----------------------------------------------------------------------
  1164.     //  Implementation of the XMLDocumentHandler interface.
  1165.     // -----------------------------------------------------------------------
  1166.     /** @name Implementation of the XMLDocumentHandler interface. */
  1167.     //@{
  1168.     /** Handle document character events
  1169.       *
  1170.       * This method is used to report all the characters scanned by the
  1171.       * parser. This DOM implementation stores this data in the appropriate
  1172.       * DOM node, creating one if necessary.
  1173.       *
  1174.       * @param chars   A const pointer to a Unicode string representing the
  1175.       *                character data.
  1176.       * @param length  The length of the Unicode string returned in 'chars'.
  1177.       * @param cdataSection  A flag indicating if the characters represent
  1178.       *                      content from the CDATA section.
  1179.       */
  1180.     virtual void docCharacters
  1181.     (
  1182.         const   XMLCh* const    chars
  1183.         , const unsigned int    length
  1184.         , const bool            cdataSection
  1185.     );
  1186.     /** Handle a document comment event
  1187.       *
  1188.       * This method is used to report any comments scanned by the parser.
  1189.       * A new comment node is created which stores this data.
  1190.       *
  1191.       * @param comment A const pointer to a null terminated Unicode
  1192.       *                string representing the comment text.
  1193.       */
  1194.     virtual void docComment
  1195.     (
  1196.         const   XMLCh* const    comment
  1197.     );
  1198.     /** Handle a document PI event
  1199.       *
  1200.       * This method is used to report any PI scanned by the parser. A new
  1201.       * PI node is created and appended as a child of the current node in
  1202.       * the tree.
  1203.       *
  1204.       * @param target A const pointer to a Unicode string representing the
  1205.       *               target of the PI declaration.
  1206.       * @param data   A const pointer to a Unicode string representing the
  1207.       *               data of the PI declaration. See the PI production rule
  1208.       *               in the XML specification for details.
  1209.       */
  1210.     virtual void docPI
  1211.     (
  1212.         const   XMLCh* const    target
  1213.         , const XMLCh* const    data
  1214.     );
  1215.     /** Handle the end of document event
  1216.       *
  1217.       * This method is used to indicate the end of the current document.
  1218.       */
  1219.     virtual void endDocument();
  1220.     /** Handle and end of element event
  1221.       *
  1222.       * This method is used to indicate the end tag of an element. The
  1223.       * DOMParse pops the current element off the top of the element
  1224.       * stack, and make it the new current element.
  1225.       *
  1226.       * @param elemDecl A const reference to the object containing element
  1227.       *                 declaration information.
  1228.       * @param urlId    An id referring to the namespace prefix, if
  1229.       *                 namespaces setting is switched on.
  1230.       * @param isRoot   A flag indicating whether this element was the
  1231.       *                 root element.
  1232.       * @param elemPrefix A const pointer to a Unicode string containing
  1233.       *                 the namespace prefix for this element. Applicable
  1234.       *                 only when namespace processing is enabled.
  1235.       */
  1236.     virtual void endElement
  1237.     (
  1238.         const   XMLElementDecl& elemDecl
  1239.         , const unsigned int    urlId
  1240.         , const bool            isRoot
  1241.         , const XMLCh* const    elemPrefix=0
  1242.     );
  1243.     /** Handle and end of entity reference event
  1244.       *
  1245.       * This method is used to indicate that an end of an entity reference
  1246.       * was just scanned.
  1247.       *
  1248.       * @param entDecl A const reference to the object containing the
  1249.       *                entity declaration information.
  1250.       */
  1251.     virtual void endEntityReference
  1252.     (
  1253.         const   XMLEntityDecl&  entDecl
  1254.     );
  1255.     /** Handle an ignorable whitespace vent
  1256.       *
  1257.       * This method is used to report all the whitespace characters, which
  1258.       * are determined to be 'ignorable'. This distinction between characters
  1259.       * is only made, if validation is enabled.
  1260.       *
  1261.       * Any whitespace before content is ignored. If the current node is
  1262.       * already of type DOM_Node::TEXT_NODE, then these whitespaces are
  1263.       * appended, otherwise a new Text node is created which stores this
  1264.       * data. Essentially all contiguous ignorable characters are collected
  1265.       * in one node.
  1266.       *
  1267.       * @param chars   A const pointer to a Unicode string representing the
  1268.       *                ignorable whitespace character data.
  1269.       * @param length  The length of the Unicode string 'chars'.
  1270.       * @param cdataSection  A flag indicating if the characters represent
  1271.       *                      content from the CDATA section.
  1272.       */
  1273.     virtual void ignorableWhitespace
  1274.     (
  1275.         const   XMLCh* const    chars
  1276.         , const unsigned int    length
  1277.         , const bool            cdataSection
  1278.     );
  1279.     /** Handle a document reset event
  1280.       *
  1281.       * This method allows the user installed Document Handler to 'reset'
  1282.       * itself, freeing all the memory resources. The scanner calls this
  1283.       * method before starting a new parse event.
  1284.       */
  1285.     virtual void resetDocument();
  1286.     /** Handle a start document event
  1287.       *
  1288.       * This method is used to report the start of the parsing process.
  1289.       */
  1290.     virtual void startDocument();
  1291.     /** Handle a start element event
  1292.       *
  1293.       * This method is used to report the start of an element. It is
  1294.       * called at the end of the element, by which time all attributes
  1295.       * specified are also parsed. A new DOM Element node is created
  1296.       * along with as many attribute nodes as required. This new element
  1297.       * is added appended as a child of the current node in the tree, and
  1298.       * then replaces it as the current node (if the isEmpty flag is false.)
  1299.       *
  1300.       * @param elemDecl A const reference to the object containing element
  1301.       *                 declaration information.
  1302.       * @param urlId    An id referring to the namespace prefix, if
  1303.       *                 namespaces setting is switched on.
  1304.       * @param elemPrefix A const pointer to a Unicode string containing
  1305.       *                 the namespace prefix for this element. Applicable
  1306.       *                 only when namespace processing is enabled.
  1307.       * @param attrList A const reference to the object containing the
  1308.       *                 list of attributes just scanned for this element.
  1309.       * @param attrCount A count of number of attributes in the list
  1310.       *                 specified by the parameter 'attrList'.
  1311.       * @param isEmpty  A flag indicating whether this is an empty element
  1312.       *                 or not. If empty, then no endElement() call will
  1313.       *                 be made.
  1314.       * @param isRoot   A flag indicating whether this element was the
  1315.       *                 root element.
  1316.       * @see DocumentHandler#startElement
  1317.       */
  1318.     virtual void startElement
  1319.     (
  1320.         const   XMLElementDecl&         elemDecl
  1321.         , const unsigned int            urlId
  1322.         , const XMLCh* const            elemPrefix
  1323.         , const RefVectorOf<XMLAttr>&   attrList
  1324.         , const unsigned int            attrCount
  1325.         , const bool                    isEmpty
  1326.         , const bool                    isRoot
  1327.     );
  1328.     /** Handle a start entity reference event
  1329.       *
  1330.       * This method is used to indicate the start of an entity reference.
  1331.       * If the expand entity reference flag is true, then a new
  1332.       * DOM Entity reference node is created.
  1333.       *
  1334.       * @param entDecl A const reference to the object containing the
  1335.       *                entity declaration information.
  1336.       */
  1337.     virtual void startEntityReference
  1338.     (
  1339.         const   XMLEntityDecl&  entDecl
  1340.     );
  1341.     /** Handle an XMLDecl event
  1342.       *
  1343.       * This method is used to report the XML decl scanned by the parser.
  1344.       * Refer to the XML specification to see the meaning of parameters.
  1345.       *
  1346.       * <b><font color="#FF0000">This method is a no-op for this DOM
  1347.       * implementation.</font></b>
  1348.       *
  1349.       * @param versionStr A const pointer to a Unicode string representing
  1350.       *                   version string value.
  1351.       * @param encodingStr A const pointer to a Unicode string representing
  1352.       *                    the encoding string value.
  1353.       * @param standaloneStr A const pointer to a Unicode string
  1354.       *                      representing the standalone string value.
  1355.       * @param actualEncStr A const pointer to a Unicode string
  1356.       *                     representing the actual encoding string
  1357.       *                     value.
  1358.       */
  1359.     virtual void XMLDecl
  1360.     (
  1361.         const   XMLCh* const    versionStr
  1362.         , const XMLCh* const    encodingStr
  1363.         , const XMLCh* const    standaloneStr
  1364.         , const XMLCh* const    actualEncStr
  1365.     );
  1366.     //@}
  1367.     /** @name Deprecated Methods */
  1368.     //@{
  1369.     /** Set the 'expand entity references' flag
  1370.       *
  1371.       * DEPRECATED.  USE setCreateEntityReferenceNodes instead.
  1372.       * This method allows the user to specify whether the parser should
  1373.       * expand all entity reference nodes. When the 'do expansion' flag is
  1374.       * true, the DOM tree does not have any entity reference nodes. It is
  1375.       * replaced by the sub-tree representing the replacement text of the
  1376.       * entity. When the 'do expansion' flag is false, the DOM tree
  1377.       * contains an extra entity reference node, whose children is the
  1378.       * sub tree of the replacement text.
  1379.       * <p>The default value is 'false'.
  1380.       *
  1381.       * @param expand The new state of the expand entity reference
  1382.       *               flag.
  1383.       * @see #setCreateEntityReferenceNodes
  1384.       */
  1385.     void setExpandEntityReferences(const bool expand);
  1386.     /** Get the 'expand entity references' flag.
  1387.       * DEPRECATED Use getCreateEntityReferenceNodes() instead.
  1388.       *
  1389.       * This method returns the state of the parser's expand entity
  1390.       * references flag.
  1391.       *
  1392.       * @return 'true' if the expand entity reference flag is set on
  1393.       *         the parser, 'false' otherwise.
  1394.       *
  1395.       * @see #setExpandEntityReferences
  1396.       * @see #setCreateEntityReferenceNodes
  1397.       * @see #getCreateEntityReferenceNodes
  1398.       */
  1399.     bool getExpandEntityReferences() const;
  1400.     /**
  1401.       * DEPRECATED Use getValidationScheme() instead
  1402.       *
  1403.       * This method returns the state of the parser's validation
  1404.       * handling flag which controls whether validation checks
  1405.       * are enforced or not.
  1406.       *
  1407.       * @return true, if the parser is currently configured to
  1408.       *         do validation, false otherwise.
  1409.       *
  1410.       * @see #setDoValidation
  1411.       * @see #getValidationScheme
  1412.       */
  1413.     bool getDoValidation() const;
  1414.     /**
  1415.       * DEPRECATED Use setValidationScheme(const ValSchemes newScheme) instead
  1416.       *
  1417.       * This method allows users to enable or disable the parser's validation
  1418.       * checks.
  1419.       *
  1420.       * <p>By default, the parser does not to any validation. The default
  1421.       * value is false.</p>
  1422.       *
  1423.       * @param newState The value specifying whether the parser should
  1424.       *                 do validity checks or not against the DTD in the
  1425.       *                 input XML document.
  1426.       *
  1427.       * @see #getDoValidation
  1428.       * @see #setValidationScheme
  1429.       */
  1430.     void setDoValidation(const bool newState);
  1431.     /**
  1432.       * Deprecated doctypehandler interfaces
  1433.       */
  1434. virtual void attDef
  1435.     (
  1436.         const   DTDElementDecl&     elemDecl
  1437.         , const DTDAttDef&          attDef
  1438.         , const bool                ignoring
  1439.     );
  1440.     virtual void doctypeComment
  1441.     (
  1442.         const   XMLCh* const    comment
  1443.     );
  1444.     virtual void doctypeDecl
  1445.     (
  1446.         const   DTDElementDecl& elemDecl
  1447.         , const XMLCh* const    publicId
  1448.         , const XMLCh* const    systemId
  1449.         , const bool            hasIntSubset
  1450.         , const bool            hasExtSubset = false
  1451.     );
  1452.     virtual void doctypePI
  1453.     (
  1454.         const   XMLCh* const    target
  1455.         , const XMLCh* const    data
  1456.     );
  1457.     virtual void doctypeWhitespace
  1458.     (
  1459.         const   XMLCh* const    chars
  1460.         , const unsigned int    length
  1461.     );
  1462.     virtual void elementDecl
  1463.     (
  1464.         const   DTDElementDecl& decl
  1465.         , const bool            isIgnored
  1466.     );
  1467.     virtual void endAttList
  1468.     (
  1469.         const   DTDElementDecl& elemDecl
  1470.     );
  1471.     virtual void endIntSubset();
  1472.     virtual void endExtSubset();
  1473.     virtual void entityDecl
  1474.     (
  1475.         const   DTDEntityDecl&  entityDecl
  1476.         , const bool            isPEDecl
  1477.         , const bool            isIgnored
  1478.     );
  1479.     virtual void resetDocType();
  1480.     virtual void notationDecl
  1481.     (
  1482.         const   XMLNotationDecl&    notDecl
  1483.         , const bool                isIgnored
  1484.     );
  1485.     virtual void startAttList
  1486.     (
  1487.         const   DTDElementDecl& elemDecl
  1488.     );
  1489.     virtual void startIntSubset();
  1490.     virtual void startExtSubset();
  1491.     virtual void TextDecl
  1492.     (
  1493.         const   XMLCh* const    versionStr
  1494.         , const XMLCh* const    encodingStr
  1495.     );
  1496.     //@}
  1497. protected :
  1498.     // -----------------------------------------------------------------------
  1499.     //  Protected getter methods
  1500.     // -----------------------------------------------------------------------
  1501.     /** @name Protected getter methods */
  1502.     //@{
  1503.     /** Get the current DOM node
  1504.       *
  1505.       * This provides derived classes with access to the current node, i.e.
  1506.       * the node to which new nodes are being added.
  1507.       */
  1508.     DOM_Node getCurrentNode();
  1509.     //@}
  1510.     // -----------------------------------------------------------------------
  1511.     //  Protected setter methods
  1512.     // -----------------------------------------------------------------------
  1513.     /** @name Protected setter methods */
  1514.     //@{
  1515.     /** Set the current DOM node
  1516.       *
  1517.       * This method sets the current node maintained inside the parser to
  1518.       * the one specified.
  1519.       *
  1520.       * @param toSet The DOM node which will be the current node.
  1521.       */
  1522.     void setCurrentNode(DOM_Node toSet);
  1523.     /** Set the document node
  1524.       *
  1525.       * This method sets the DOM Document node to the one specified.
  1526.       *
  1527.       * @param toSet The new DOM Document node for this XML document.
  1528.       */
  1529.     void setDocument(DOM_Document toSet);
  1530.     //@}
  1531. private :
  1532.     // -----------------------------------------------------------------------
  1533.     //  Protected setter methods
  1534.     // -----------------------------------------------------------------------
  1535.     void initialize();
  1536.     void cleanUp();
  1537.     // -----------------------------------------------------------------------
  1538.     //  Private data members
  1539.     //
  1540.     //  fCurrentNode
  1541.     //  fCurrentParent
  1542.     //      Used to track the current node during nested element events. Since
  1543.     //      the tree must be built from a set of disjoint callbacks, we need
  1544.     //      these to keep up with where we currently are.
  1545.     //
  1546.     //  fDocument
  1547.     //      The root document object, filled with the document contents.
  1548.     //
  1549.     //  fEntityResolver
  1550.     //      The installed SAX entity resolver, if any. Null if none.
  1551.     //
  1552.     //  fErrorHandler
  1553.     //      The installed SAX error handler, if any. Null if none.
  1554.     //
  1555.     //  fCreateEntityReferenceNode
  1556.     //      Indicates whether entity reference nodes should be created.
  1557.     //
  1558.     //  fIncludeIgnorableWhitespace
  1559.     //      Indicates whether ignorable whiltespace should be added to
  1560.     //      the DOM tree for validating parsers.
  1561.     //
  1562.     //  fNodeStack
  1563.     //      Used to track previous parent nodes during nested element events.
  1564.     //
  1565.     //  fParseInProgress
  1566.     //      Used to prevent multiple entrance to the parser while its doing
  1567.     //      a parse.
  1568.     //
  1569.     //  fScanner
  1570.     //      The scanner used for this parser. This is created during the
  1571.     //      constructor.
  1572.     //
  1573.     //  fWithinElement
  1574.     //      A flag to indicate that the parser is within at least one level
  1575.     //      of element processing.
  1576.     //
  1577.     //  fDocumentType
  1578.     //      Used to store and update the documentType variable information
  1579.     //      in fDocument
  1580.     //
  1581.     //  fToCreateXMLDecTypeNode
  1582.     //      A flag to create a DOM_XMLDecl node in the ODM tree if it exists
  1583.     //      This is an extension to xerces implementation
  1584.     //
  1585.     // -----------------------------------------------------------------------
  1586.     bool                    fToCreateXMLDeclTypeNode;
  1587.     bool                    fCreateEntityReferenceNodes;
  1588.     bool                    fIncludeIgnorableWhitespace;
  1589.     bool                    fParseInProgress;
  1590.     bool                    fWithinElement;
  1591.     DOM_Node                fCurrentParent;
  1592.     DOM_Node                fCurrentNode;
  1593.     DOM_Document            fDocument;
  1594.     EntityResolver*         fEntityResolver;
  1595.     ErrorHandler*           fErrorHandler;
  1596.     ValueStackOf<DOM_Node>* fNodeStack;
  1597.     XMLScanner*             fScanner;
  1598.     DocumentTypeImpl*       fDocumentType;
  1599.     GrammarResolver*        fGrammarResolver;
  1600.     XMLStringPool*          fURIStringPool;
  1601.     XMLValidator*           fValidator;
  1602.     MemoryManager*          fMemoryManager;
  1603. };
  1604. // ---------------------------------------------------------------------------
  1605. //  DOMParser: Handlers for the XMLEntityHandler interface
  1606. // ---------------------------------------------------------------------------
  1607. inline void DOMParser::endInputSource(const InputSource&)
  1608. {
  1609.     // The DOM entity resolver doesn't handle this
  1610. }
  1611. inline bool DOMParser::expandSystemId(const XMLCh* const, XMLBuffer&)
  1612. {
  1613.     // The DOM entity resolver doesn't handle this
  1614.     return false;
  1615. }
  1616. inline void DOMParser::resetEntities()
  1617. {
  1618.     // Nothing to do on this one
  1619. }
  1620. inline void DOMParser::startInputSource(const InputSource&)
  1621. {
  1622.     // The DOM entity resolver doesn't handle this
  1623. }
  1624. // ---------------------------------------------------------------------------
  1625. //  DOMParser: Getter methods
  1626. // ---------------------------------------------------------------------------
  1627. inline DOM_Document DOMParser::getDocument()
  1628. {
  1629.     return fDocument;
  1630. }
  1631. inline ErrorHandler* DOMParser::getErrorHandler()
  1632. {
  1633.     return fErrorHandler;
  1634. }
  1635. inline const ErrorHandler* DOMParser::getErrorHandler() const
  1636. {
  1637.     return fErrorHandler;
  1638. }
  1639. inline EntityResolver* DOMParser::getEntityResolver()
  1640. {
  1641.     return fEntityResolver;
  1642. }
  1643. inline const EntityResolver* DOMParser::getEntityResolver() const
  1644. {
  1645.     return fEntityResolver;
  1646. }
  1647. inline bool DOMParser::getExpandEntityReferences() const
  1648. {
  1649.     return !fCreateEntityReferenceNodes;
  1650. }
  1651. inline bool DOMParser::getCreateEntityReferenceNodes() const
  1652. {
  1653.     return fCreateEntityReferenceNodes;
  1654. }
  1655. inline bool DOMParser::getIncludeIgnorableWhitespace() const
  1656. {
  1657.     return fIncludeIgnorableWhitespace;
  1658. }
  1659. inline const XMLScanner& DOMParser::getScanner() const
  1660. {
  1661.     return *fScanner;
  1662. }
  1663. inline bool DOMParser::getToCreateXMLDeclTypeNode() const
  1664. {
  1665.     return fToCreateXMLDeclTypeNode;
  1666. }
  1667. // ---------------------------------------------------------------------------
  1668. //  DOMParser: Setter methods
  1669. // ---------------------------------------------------------------------------
  1670. inline void DOMParser::setExpandEntityReferences(const bool expand)
  1671. {
  1672.     fCreateEntityReferenceNodes = !expand;
  1673. }
  1674. inline void DOMParser::setCreateEntityReferenceNodes(const bool create)
  1675. {
  1676.     fCreateEntityReferenceNodes = create;
  1677. }
  1678. inline void DOMParser::setIncludeIgnorableWhitespace(const bool include)
  1679. {
  1680.     fIncludeIgnorableWhitespace = include;
  1681. }
  1682. inline void DOMParser::setToCreateXMLDeclTypeNode(const bool create)
  1683. {
  1684.     fToCreateXMLDeclTypeNode = create;
  1685. }
  1686. // ---------------------------------------------------------------------------
  1687. //  DOMParser: Protected getter methods
  1688. // ---------------------------------------------------------------------------
  1689. inline DOM_Node DOMParser::getCurrentNode()
  1690. {
  1691.     return fCurrentNode;
  1692. }
  1693. // ---------------------------------------------------------------------------
  1694. //  DOMParser: Protected setter methods
  1695. // ---------------------------------------------------------------------------
  1696. inline void DOMParser::setCurrentNode(DOM_Node toSet)
  1697. {
  1698.     fCurrentNode = toSet;
  1699. }
  1700. inline void DOMParser::setDocument(DOM_Document toSet)
  1701. {
  1702.     fDocument = toSet;
  1703. }
  1704. XERCES_CPP_NAMESPACE_END
  1705. #endif