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

词法分析

开发平台:

Visual C++

  1. #ifndef DOMBuilder_HEADER_GUARD_
  2. #define DOMBuilder_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) 2001, 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: DOMBuilder.hpp,v 1.11 2003/03/07 19:58:58 tng Exp $
  60.  *
  61.  */
  62. #include <xercesc/util/XercesDefs.hpp>
  63. XERCES_CPP_NAMESPACE_BEGIN
  64. class DOMErrorHandler;
  65. class DOMEntityResolver;
  66. class DOMInputSource;
  67. class DOMBuilderFilter;
  68. class DOMNode;
  69. class DOMDocument;
  70. class Grammar;
  71. /**
  72.  * DOMBuilder provides an API for parsing XML documents and building the
  73.  * corresponding DOM document tree. A DOMBuilder instance is obtained from
  74.  * the DOMImplementationLS interface by invoking its createDOMBuilder method.
  75.  * This implementation also allows the applications to install an error and
  76.  * an entity handler (useful extensions to the DOM specification).
  77.  *
  78.  * @since DOM Level 3
  79.  *
  80.  */
  81. class CDOM_EXPORT DOMBuilder
  82. {
  83. protected :
  84.     // -----------------------------------------------------------------------
  85.     //  Hidden constructors
  86.     // -----------------------------------------------------------------------
  87.     /** @name Hidden constructors */
  88.     //@{    
  89.     DOMBuilder() {};
  90.     //@}
  91. private:    
  92.     // -----------------------------------------------------------------------
  93.     // Unimplemented constructors and operators
  94.     // -----------------------------------------------------------------------
  95.     /** @name Unimplemented constructors and operators */
  96.     //@{
  97.     DOMBuilder(const DOMBuilder &);
  98.     DOMBuilder & operator = (const DOMBuilder &);
  99.     //@}
  100. public:
  101.     // -----------------------------------------------------------------------
  102.     //  All constructors are hidden, just the destructor is available
  103.     // -----------------------------------------------------------------------
  104.     /** @name Destructor */
  105.     //@{
  106.     /**
  107.      * Destructor
  108.      *
  109.      */
  110.     virtual ~DOMBuilder() {};
  111.     //@}
  112.     // -----------------------------------------------------------------------
  113.     //  Class types
  114.     // -----------------------------------------------------------------------
  115.     /** @name Public Constants */
  116.     //@{
  117.     /**
  118.      * Action types for use in parseWithContext.
  119.      *
  120.      * <p> <code>ACTION_REPLACE</code>:
  121.      * Replace the context node with the result of parsing the input source.
  122.      * For this action to work the context node must be an
  123.      * <code>DOMElement</code>, <code>DOMText</code>, <code>DOMCDATASection</code>,
  124.      * <code>DOMComment</code>, <code>DOMProcessingInstruction</code>, or
  125.      * <code>DOMEntityReference</code> node.</p>
  126.      *
  127.      * <p> <code>ACTION_APPEND</code>:
  128.      * Append the result of parsing the input source to the context node. For
  129.      * this action to work, the context node must be an <code>DOMElement</code>.</p>
  130.      *
  131.      * <p> <code>ACTION_INSERT_AFTER</code>:
  132.      * Insert the result of parsing the input source after the context node.
  133.      * For this action to work the context nodes parent must be an
  134.      * <code>DOMElement</code>.</p>
  135.      *
  136.      * <p> <code>ACTION_INSERT_BEFORE</code>:
  137.      * Insert the result of parsing the input source before the context node.
  138.      * For this action to work the context nodes parent must be an
  139.      * <code>DOMElement</code>.</p>
  140.      *
  141.      * @see parseWithContext(...)
  142.      * @since DOM Level 3
  143.      */
  144.     enum ActionType
  145.     {
  146.         ACTION_REPLACE            = 1,
  147.         ACTION_APPEND_AS_CHILDREN = 2,
  148.         ACTION_INSERT_AFTER       = 3,
  149.         ACTION_INSERT_BEFORE      = 4
  150.     };
  151.     //@}
  152.     // -----------------------------------------------------------------------
  153.     //  Virtual DOMBuilder interface
  154.     // -----------------------------------------------------------------------
  155.     /** @name Functions introduced in DOM Level 3 */
  156.     //@{
  157.     // -----------------------------------------------------------------------
  158.     //  Getter methods
  159.     // -----------------------------------------------------------------------
  160.     /**
  161.       * Get a pointer to the error handler
  162.       *
  163.       * This method returns the installed error handler. If no handler
  164.       * has been installed, then it will be a zero pointer.
  165.       *
  166.       * <p><b>"Experimental - subject to change"</b></p>
  167.       *
  168.       * @return The pointer to the installed error handler object.
  169.       * @since DOM Level 3
  170.       */
  171.     virtual DOMErrorHandler* getErrorHandler() = 0;
  172.     /**
  173.       * Get a const pointer to the error handler
  174.       *
  175.       * This method returns the installed error handler.  If no handler
  176.       * has been installed, then it will be a zero pointer.
  177.       *
  178.       * <p><b>"Experimental - subject to change"</b></p>
  179.       *
  180.       * @return A const pointer to the installed error handler object.
  181.       * @since DOM Level 3
  182.       */
  183.     virtual const DOMErrorHandler* getErrorHandler() const = 0;
  184.     /**
  185.       * Get a pointer to the entity resolver
  186.       *
  187.       * This method returns the installed entity resolver.  If no resolver
  188.       * has been installed, then it will be a zero pointer.
  189.       *
  190.       * <p><b>"Experimental - subject to change"</b></p>
  191.       *
  192.       * @return The pointer to the installed entity resolver object.
  193.       * @since DOM Level 3
  194.       */
  195.     virtual DOMEntityResolver* getEntityResolver() = 0;
  196.     /**
  197.       * Get a const pointer to the entity resolver
  198.       *
  199.       * This method returns the installed entity resolver. If no resolver
  200.       * has been installed, then it will be a zero pointer.
  201.       *
  202.       * <p><b>"Experimental - subject to change"</b></p>
  203.       *
  204.       * @return A const pointer to the installed entity resolver object.
  205.       * @since DOM Level 3
  206.       */
  207.     virtual const DOMEntityResolver* getEntityResolver() const = 0;
  208.     /**
  209.       * Get a pointer to the application filter
  210.       *
  211.       * This method returns the installed application filter. If no filter
  212.       * has been installed, then it will be a zero pointer.
  213.       *
  214.       * <p><b>"Experimental - subject to change"</b></p>
  215.       *
  216.       * @return The pointer to the installed application filter.
  217.       * @since DOM Level 3
  218.       */
  219.     virtual DOMBuilderFilter* getFilter() = 0;
  220.     /**
  221.       * Get a const pointer to the application filter
  222.       *
  223.       * This method returns the installed application filter. If no filter
  224.       * has been installed, then it will be a zero pointer.
  225.       *
  226.       * <p><b>"Experimental - subject to change"</b></p>
  227.       *
  228.       * @return A const pointer to the installed application filter
  229.       * @since DOM Level 3
  230.       */
  231.     virtual const DOMBuilderFilter* getFilter() const = 0;
  232.     // -----------------------------------------------------------------------
  233.     //  Setter methods
  234.     // -----------------------------------------------------------------------
  235.     /**
  236.       * Set the error handler
  237.       *
  238.       * This method allows applications to install their own error handler
  239.       * to trap error and warning messages.
  240.       *
  241.       * <i>Any previously set handler is merely dropped, since the parser
  242.       * does not own them.</i>
  243.       *
  244.       * <p><b>"Experimental - subject to change"</b></p>
  245.       *
  246.       * @param handler  A const pointer to the user supplied error
  247.       *                 handler.
  248.       *
  249.       * @see #getErrorHandler
  250.       * @since DOM Level 3
  251.       */
  252.     virtual void setErrorHandler(DOMErrorHandler* const handler) = 0;
  253.     /**
  254.       * Set the entity resolver
  255.       *
  256.       * This method allows applications to install their own entity
  257.       * resolver. By installing an entity resolver, the applications
  258.       * can trap and potentially redirect references to external
  259.       * entities.
  260.       *
  261.       * <i>Any previously set resolver is merely dropped, since the parser
  262.       * does not own them.</i>
  263.       *
  264.       * <p><b>"Experimental - subject to change"</b></p>
  265.       *
  266.       * @param handler  A const pointer to the user supplied entity
  267.       *                 resolver.
  268.       *
  269.       * @see #getEntityResolver
  270.       * @since DOM Level 3
  271.       */
  272.     virtual void setEntityResolver(DOMEntityResolver* const handler) = 0;
  273.     /**
  274.       * Set the application filter
  275.       *
  276.       * When the application provides a filter, the parser will call out to
  277.       * the filter at the completion of the construction of each Element node.
  278.       * The filter implementation can choose to remove the element from the
  279.       * document being constructed (unless the element is the document element)
  280.       * or to terminate the parse early. If the document is being validated
  281.       * when it's loaded the validation happens before the filter is called.
  282.       *
  283.       * <i>Any previously set filter is merely dropped, since the parser
  284.       * does not own them.</i>
  285.       *
  286.       * <p><b>"Experimental - subject to change"</b></p>
  287.       *
  288.       * @param filter  A const pointer to the user supplied application
  289.       *                filter.
  290.       *
  291.       * @see #getFilter
  292.       * @since DOM Level 3
  293.       */
  294.     virtual void setFilter(DOMBuilderFilter* const filter) = 0;
  295.     // -----------------------------------------------------------------------
  296.     //  Feature methods
  297.     // -----------------------------------------------------------------------
  298.     /**
  299.       * Set the state of a feature
  300.       *
  301.       * It is possible for a DOMBuilder to recognize a feature name but to be
  302.       * unable to set its value.
  303.       *
  304.       * <p><b>"Experimental - subject to change"</b></p>
  305.       *
  306.       * See http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderFeatures for
  307.       * the list of supported features.
  308.       *
  309.       * @param name  The feature name.
  310.       * @param state The requested state of the feature (true or false).
  311.       * @exception DOMException
  312.       *     NOT_SUPPORTED_ERR: Raised when the DOMBuilder recognizes the
  313.       *     feature name but cannot set the requested value.
  314.       *     <br>NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
  315.       *     the feature name.
  316.       *
  317.       * @see #setFeature
  318.       * @see #canSetFeature
  319.       * @since DOM Level 3
  320.       */
  321.     virtual void setFeature(const XMLCh* const name, const bool state) = 0;
  322.     /**
  323.       * Look up the value of a feature.
  324.       *
  325.       * <p><b>"Experimental - subject to change"</b></p>
  326.       *
  327.       * @param name The feature name.
  328.       * @return The current state of the feature (true or false)
  329.       * @exception DOMException
  330.       *     NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
  331.       *     the feature name.
  332.       *
  333.       * @see #getFeature
  334.       * @see #canSetFeature
  335.       * @since DOM Level 3
  336.       */
  337.     virtual bool getFeature(const XMLCh* const name) const = 0;
  338.     /**
  339.       * Query whether setting a feature to a specific value is supported.
  340.       *
  341.       * <p><b>"Experimental - subject to change"</b></p>
  342.       *
  343.       * @param name  The feature name.
  344.       * @param state The requested state of the feature (true or false).
  345.       * @return <code>true</code> if the feature could be successfully set
  346.       *     to the specified value, or <code>false</code> if the feature
  347.       *     is not recognized or the requested value is not supported. The
  348.       *     value of the feature itself is not changed.
  349.       *
  350.       * @see #getFeature
  351.       * @see #setFeature
  352.       * @since DOM Level 3
  353.       */
  354.     virtual bool canSetFeature(const XMLCh* const name, const bool state) const = 0;
  355.     // -----------------------------------------------------------------------
  356.     //  Parsing methods
  357.     // -----------------------------------------------------------------------
  358.     /**
  359.       * Parse via an input source object
  360.       *
  361.       * This method invokes the parsing process on the XML file specified
  362.       * by the DOMInputSource parameter. This API is borrowed from the
  363.       * SAX Parser interface.
  364.       *
  365.       * The parser owns the returned DOMDocument.  It will be deleted
  366.       * when the parser is released.
  367.       *
  368.       * <p><b>"Experimental - subject to change"</b></p>
  369.       *
  370.       * @param source A const reference to the DOMInputSource object which
  371.       *               points to the XML file to be parsed.
  372.       * @return If the DOMBuilder is a synchronous DOMBuilder the newly created
  373.       *         and populated DOMDocument is returned. If the DOMBuilder is
  374.       *         asynchronous then <code>null</code> is returned since the
  375.       *         document object is not yet parsed when this method returns.
  376.       * @exception SAXException Any SAX exception, possibly
  377.       *            wrapping another exception.
  378.       * @exception XMLException An exception from the parser or client
  379.       *            handler code.
  380.       * @exception DOMException A DOM exception as per DOM spec.
  381.       *
  382.       * @see DOMInputSource#DOMInputSource
  383.       * @see #setEntityResolver
  384.       * @see #setErrorHandler
  385.       * @see resetDocumentPool
  386.       * @since DOM Level 3
  387.       */
  388.     virtual DOMDocument* parse(const DOMInputSource& source) = 0;
  389.     /**
  390.       * Parse via a file path or URL
  391.       *
  392.       * This method invokes the parsing process on the XML file specified by
  393.       * the Unicode string parameter 'systemId'.
  394.       *
  395.       * The parser owns the returned DOMDocument.  It will be deleted
  396.       * when the parser is released.
  397.       *
  398.       * <p><b>"Experimental - subject to change"</b></p>
  399.       *
  400.       * @param systemId A const XMLCh pointer to the Unicode string which
  401.       *                 contains the path to the XML file to be parsed.
  402.       * @return If the DOMBuilder is a synchronous DOMBuilder the newly created
  403.       *         and populated DOMDocument is returned. If the DOMBuilder is
  404.       *         asynchronous then <code>null</code> is returned since the
  405.       *         document object is not yet parsed when this method returns.
  406.       * @exception SAXException Any SAX exception, possibly
  407.       *            wrapping another exception.
  408.       * @exception XMLException An exception from the parser or client
  409.       *            handler code.
  410.       * @exception DOMException A DOM exception as per DOM spec.
  411.       *
  412.       * @see #parse(DOMInputSource,...)
  413.       * @see resetDocumentPool
  414.       * @since DOM Level 3
  415.       */
  416.     virtual DOMDocument* parseURI(const XMLCh* const systemId) = 0;
  417.     /**
  418.       * Parse via a file path or URL (in the local code page)
  419.       *
  420.       * This method invokes the parsing process on the XML file specified by
  421.       * the native char* string parameter 'systemId'.
  422.       *
  423.       * The parser owns the returned DOMDocument.  It will be deleted
  424.       * when the parser is released.
  425.       *
  426.       * <p><b>"Experimental - subject to change"</b></p>
  427.       *
  428.       * @param systemId A const char pointer to a native string which
  429.       *                 contains the path to the XML file to be parsed.
  430.       * @return If the DOMBuilder is a synchronous DOMBuilder the newly created
  431.       *         and populated DOMDocument is returned. If the DOMBuilder is
  432.       *         asynchronous then <code>null</code> is returned since the
  433.       *         document object is not yet parsed when this method returns.
  434.       * @exception SAXException Any SAX exception, possibly
  435.       *            wrapping another exception.
  436.       * @exception XMLException An exception from the parser or client
  437.       *            handler code.
  438.       * @exception DOMException A DOM exception as per DOM spec.
  439.       *
  440.       * @see #parse(DOMInputSource,...)
  441.       * @see resetDocumentPool
  442.       */
  443.     virtual DOMDocument* parseURI(const char* const systemId) = 0;
  444.     /**
  445.       * Parse via an input source object
  446.       *
  447.       * This method invokes the parsing process on the XML file specified
  448.       * by the DOMInputSource parameter, and inserts the content into an
  449.       * existing document at the position specified with the contextNode
  450.       * and action arguments. When parsing the input stream the context node
  451.       * is used for resolving unbound namespace prefixes.
  452.       *
  453.       * <p><b>"Experimental - subject to change"</b></p>
  454.       *
  455.       * @param source A const reference to the DOMInputSource object which
  456.       *               points to the XML file to be parsed.
  457.       * @param contextNode The node that is used as the context for the data
  458.       *                    that is being parsed. This node must be a Document
  459.       *                    node, a DocumentFragment node, or a node of a type
  460.       *                    that is allowed as a child of an element, e.g. it
  461.       *                    can not be an attribute node.
  462.       * @param action This parameter describes which action should be taken
  463.       *               between the new set of node being inserted and the
  464.       *               existing children of the context node.
  465.       * @exception DOMException
  466.       *     NOT_SUPPORTED_ERR: Raised when the DOMBuilder doesn't support
  467.       *     this method.
  468.       *     <br>NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is
  469.       *     readonly.
  470.       * @since DOM Level 3
  471.       */
  472.     virtual void parseWithContext
  473.     (
  474.         const   DOMInputSource& source
  475.         ,       DOMNode* const contextNode
  476.         , const short action
  477.     ) = 0;
  478.     //@}
  479.     // -----------------------------------------------------------------------
  480.     //  Non-standard Extension
  481.     // -----------------------------------------------------------------------
  482.     /** @name Non-standard Extension */
  483.     //@{
  484.     /**
  485.       * Query the current value of a property in a DOMBuilder.
  486.       *
  487.       * The builder owns the returned pointer.  The memory allocated for
  488.       * the returned pointer will be destroyed when the builder is deleted.
  489.       *
  490.       * To ensure assessiblity of the returned information after the builder
  491.       * is deleted, callers need to copy and store the returned information
  492.       * somewhere else; otherwise you may get unexpected result.  Since the returned
  493.       * pointer is a generic void pointer, see
  494.       * http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderProperties to learn
  495.       * exactly what type of property value each property returns for replication.
  496.       *
  497.       * @param name The unique identifier (URI) of the property being set.
  498.       * @return     The current value of the property.  The pointer spans the same
  499.       *             life-time as the parser.  A null pointer is returned if nothing
  500.       *             was specified externally.
  501.       * @exception DOMException
  502.       *     <br>NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
  503.       *     the requested property.
  504.       */
  505.     virtual void* getProperty(const XMLCh* const name) const = 0 ;
  506.     /**
  507.       * Set the value of any property in a DOMBuilder.
  508.       * See http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderProperties for
  509.       * the list of supported properties.
  510.       *
  511.       * It takes a void pointer as the property value.  Application is required to initialize this void
  512.       * pointer to a correct type.  See http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderProperties
  513.       * to learn exactly what type of property value each property expects for processing.
  514.       * Passing a void pointer that was initialized with a wrong type will lead to unexpected result.
  515.       * If the same property is set more than once, the last one takes effect.
  516.       *
  517.       * @param name The unique identifier (URI) of the property being set.
  518.       * @param value The requested value for the property.
  519.       *            See http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderProperties to learn
  520.       *            exactly what type of property value each property expects for processing.
  521.       *            Passing a void pointer that was initialized with a wrong type will lead
  522.       *            to unexpected result.
  523.       * @exception DOMException
  524.       *     <br>NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
  525.       *     the requested property.
  526.       */
  527.     virtual void setProperty(const XMLCh* const name, void* value) = 0 ;
  528.     /**
  529.      * Called to indicate that this DOMBuilder is no longer in use
  530.      * and that the implementation may relinquish any resources associated with it.
  531.      *
  532.      * Access to a released object will lead to unexpected result.
  533.      */
  534.     virtual void              release() = 0;
  535.     /** Reset the documents vector pool and release all the associated memory
  536.       * back to the system.
  537.       *
  538.       * When parsing a document using a DOM parser, all memory allocated
  539.       * for a DOM tree is associated to the DOM document.
  540.       *
  541.       * If you do multiple parse using the same DOM parser instance, then
  542.       * multiple DOM documents will be generated and saved in a vector pool.
  543.       * All these documents (and thus all the allocated memory)
  544.       * won't be deleted until the parser instance is destroyed.
  545.       *
  546.       * If you don't need these DOM documents anymore and don't want to
  547.       * destroy the DOM parser instance at this moment, then you can call this method
  548.       * to reset the document vector pool and release all the allocated memory
  549.       * back to the system.
  550.       *
  551.       * It is an error to call this method if you are in the middle of a
  552.       * parse (e.g. in the mid of a progressive parse).
  553.       *
  554.       * @exception IOException An exception from the parser if this function
  555.       *            is called when a parse is in progress.
  556.       *
  557.       */
  558.     virtual void              resetDocumentPool() = 0;
  559.     /**
  560.       * Preparse schema grammar (XML Schema, DTD, etc.) via an input source
  561.       * object.
  562.       *
  563.       * This method invokes the preparsing process on a schema grammar XML
  564.       * file specified by the DOMInputSource parameter. If the 'toCache' flag
  565.       * is enabled, the parser will cache the grammars for re-use. If a grammar
  566.       * key is found in the pool, no caching of any grammar will take place.
  567.       *
  568.       * <p><b>"Experimental - subject to change"</b></p>
  569.       *
  570.       * @param source A const reference to the DOMInputSource object which
  571.       *               points to the schema grammar file to be preparsed.
  572.       * @param grammarType The grammar type (Schema or DTD).
  573.       * @param toCache If <code>true</code>, we cache the preparsed grammar,
  574.       *                otherwise, no chaching. Default is <code>false</code>.
  575.       * @return The preparsed schema grammar object (SchemaGrammar or
  576.       *         DTDGrammar). That grammar object is owned by the parser.
  577.       *
  578.       * @exception SAXException Any SAX exception, possibly
  579.       *            wrapping another exception.
  580.       * @exception XMLException An exception from the parser or client
  581.       *            handler code.
  582.       * @exception DOMException A DOM exception as per DOM spec.
  583.       *
  584.       * @see DOMInputSource#DOMInputSource
  585.       */
  586.     virtual Grammar* loadGrammar(const DOMInputSource& source,
  587.                                  const short grammarType,
  588.                                  const bool toCache = false) = 0;
  589.     /**
  590.       * Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL
  591.       *
  592.       * This method invokes the preparsing process on a schema grammar XML
  593.       * file specified by the file path parameter. If the 'toCache' flag is
  594.       * enabled, the parser will cache the grammars for re-use. If a grammar
  595.       * key is found in the pool, no caching of any grammar will take place.
  596.       *
  597.       * <p><b>"Experimental - subject to change"</b></p>
  598.       *
  599.       * @param systemId A const XMLCh pointer to the Unicode string which
  600.       *                 contains the path to the XML grammar file to be
  601.       *                 preparsed.
  602.       * @param grammarType The grammar type (Schema or DTD).
  603.       * @param toCache If <code>true</code>, we cache the preparsed grammar,
  604.       *                otherwise, no chaching. Default is <code>false</code>.
  605.       * @return The preparsed schema grammar object (SchemaGrammar or
  606.       *         DTDGrammar). That grammar object is owned by the parser.
  607.       *
  608.       * @exception SAXException Any SAX exception, possibly
  609.       *            wrapping another exception.
  610.       * @exception XMLException An exception from the parser or client
  611.       *            handler code.
  612.       * @exception DOMException A DOM exception as per DOM spec.
  613.       */
  614.     virtual Grammar* loadGrammar(const XMLCh* const systemId,
  615.                                  const short grammarType,
  616.                                  const bool toCache = false) = 0;
  617.     /**
  618.       * Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL
  619.       *
  620.       * This method invokes the preparsing process on a schema grammar XML
  621.       * file specified by the file path parameter. If the 'toCache' flag is
  622.       * enabled, the parser will cache the grammars for re-use. If a grammar
  623.       * key is found in the pool, no caching of any grammar will take place.
  624.       *
  625.       * <p><b>"Experimental - subject to change"</b></p>
  626.       *
  627.       * @param systemId A const char pointer to a native string which contains
  628.       *                 the path to the XML grammar file to be preparsed.
  629.       * @param grammarType The grammar type (Schema or DTD).
  630.       * @param toCache If <code>true</code>, we cache the preparsed grammar,
  631.       *                otherwise, no chaching. Default is <code>false</code>.
  632.       * @return The preparsed schema grammar object (SchemaGrammar or
  633.       *         DTDGrammar). That grammar object is owned by the parser.
  634.       *
  635.       *
  636.       * @exception SAXException Any SAX exception, possibly
  637.       *            wrapping another exception.
  638.       * @exception XMLException An exception from the parser or client
  639.       *            handler code.
  640.       * @exception DOMException A DOM exception as per DOM spec.
  641.       */
  642.     virtual Grammar* loadGrammar(const char* const systemId,
  643.                                  const short grammarType,
  644.                                  const bool toCache = false) = 0;
  645.     /**
  646.      * Retrieve the grammar that is associated with the specified namespace key
  647.      *
  648.      * @param  nameSpaceKey Namespace key
  649.      * @return Grammar associated with the Namespace key.
  650.      */
  651.     virtual Grammar* getGrammar(const XMLCh* const nameSpaceKey) const = 0;
  652.     /**
  653.      * Retrieve the grammar where the root element is declared.
  654.      *
  655.      * @return Grammar where root element declared
  656.      */
  657.     virtual Grammar* getRootGrammar() const = 0;
  658.     /**
  659.      * Returns the string corresponding to a URI id from the URI string pool.
  660.      *
  661.      * @param uriId id of the string in the URI string pool.
  662.      * @return URI string corresponding to the URI id.
  663.      */
  664.     virtual const XMLCh* getURIText(unsigned int uriId) const = 0;
  665.     /**
  666.       * Clear the cached grammar pool
  667.       */
  668.     virtual void resetCachedGrammarPool() = 0;
  669.     /**
  670.       * Returns the current src offset within the input source.
  671.       *
  672.       * @return offset within the input source
  673.       */
  674.     virtual unsigned int getSrcOffset() const = 0;
  675.     //@}
  676. };
  677. XERCES_CPP_NAMESPACE_END
  678. #endif