xercesc/sax/Parser.hpp

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *      http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 /*
0019  * $Id$
0020  */
0021
0022 #if !defined(XERCESC_INCLUDE_GUARD_PARSER_HPP)
0023 #define XERCESC_INCLUDE_GUARD_PARSER_HPP
0024
0025 #include <xercesc/util/XercesDefs.hpp>
0026
0027 XERCES_CPP_NAMESPACE_BEGIN
0028
0029 class DTDHandler;
0030 class EntityResolver;
0031 class DocumentHandler;
0032 class ErrorHandler;
0033 class InputSource;
0034
0035 /**
0036   * Basic interface for SAX (Simple API for XML) parsers.
0037   *
0038   * All SAX parsers must implement this basic interface: it allows
0039   * applications to register handlers for different types of events
0040   * and to initiate a parse from a URI, or a character stream.
0041   *
0042   * All SAX parsers must also implement a zero-argument constructor
0043   * (though other constructors are also allowed).
0044   *
0045   * SAX parsers are reusable but not re-entrant: the application
0046   * may reuse a parser object (possibly with a different input source)
0047   * once the first parse has completed successfully, but it may not
0048   * invoke the parse() methods recursively within a parse.
0049   *
0050   * @see EntityResolver#EntityResolver
0051   * @see DTDHandler#DTDHandler
0052   * @see DocumentHandler#DocumentHandler
0053   * @see ErrorHandler#ErrorHandler
0054   * @see HandlerBase#HandlerBase
0055   * @see InputSource#InputSource
0056   */
0057
0058 #include <xercesc/util/XercesDefs.hpp>
0059
0060 class SAX_EXPORT Parser
0061 {
0062 public:
0063     /** @name Constructors and Destructor */
0064     // -----------------------------------------------------------------------
0065     //  Constructors and Destructor
0066     // -----------------------------------------------------------------------
0067     //@{
0068     /** The default constructor */
0069     Parser()
0070     {
0071     }
0072     /** The destructor */
0073     virtual ~Parser()
0074     {
0075     }
0076     //@}
0077
0078     //-----------------------------------------------------------------------
0079     // The parser interface
0080     //-----------------------------------------------------------------------
0081     /** @name The parser interfaces */
0082     //@{
0083   /**
0084     * Allow an application to register a custom entity resolver.
0085     *
0086     * If the application does not register an entity resolver, the
0087     * SAX parser will resolve system identifiers and open connections
0088     * to entities itself (this is the default behaviour implemented in
0089     * HandlerBase).
0090     *
0091     * Applications may register a new or different entity resolver
0092     * in the middle of a parse, and the SAX parser must begin using
0093     * the new resolver immediately.
0094     *
0095     * @param resolver The object for resolving entities.
0096     * @see EntityResolver#EntityResolver
0097     * @see HandlerBase#HandlerBase
0098     */
0099     virtual void setEntityResolver(EntityResolver* const resolver) = 0;
0100
0101   /**
0102     * Allow an application to register a DTD event handler.
0103     *
0104     * If the application does not register a DTD handler, all DTD
0105     * events reported by the SAX parser will be silently ignored (this
0106     * is the default behaviour implemented by HandlerBase).
0107     *
0108     * Applications may register a new or different handler in the middle
0109     * of a parse, and the SAX parser must begin using the new handler
0110     * immediately.
0111     *
0112     * @param handler The DTD handler.
0113     * @see DTDHandler#DTDHandler
0114     * @see HandlerBase#HandlerBase
0115     */
0116     virtual void setDTDHandler(DTDHandler* const handler) = 0;
0117
0118   /**
0119     * Allow an application to register a document event handler.
0120     *
0121     * If the application does not register a document handler, all
0122     * document events reported by the SAX parser will be silently
0123     * ignored (this is the default behaviour implemented by
0124     * HandlerBase).
0125     *
0126     * Applications may register a new or different handler in the
0127     * middle of a parse, and the SAX parser must begin using the new
0128     * handler immediately.
0129     *
0130     * @param handler The document handler.
0131     * @see DocumentHandler#DocumentHandler
0132     * @see HandlerBase#HandlerBase
0133     */
0134     virtual void setDocumentHandler(DocumentHandler* const handler) = 0;
0135
0136   /**
0137     * Allow an application to register an error event handler.
0138     *
0139     * If the application does not register an error event handler,
0140     * all error events reported by the SAX parser will be silently
0141     * ignored, except for fatalError, which will throw a SAXException
0142     * (this is the default behaviour implemented by HandlerBase).
0143     *
0144     * Applications may register a new or different handler in the
0145     * middle of a parse, and the SAX parser must begin using the new
0146     * handler immediately.
0147     *
0148     * @param handler The error handler.
0149     * @see ErrorHandler#ErrorHandler
0150     * @see SAXException#SAXException
0151     * @see HandlerBase#HandlerBase
0152     */
0153     virtual void setErrorHandler(ErrorHandler* const handler) = 0;
0154
0155   /**
0156     * Parse an XML document.
0157     *
0158     * The application can use this method to instruct the SAX parser
0159     * to begin parsing an XML document from any valid input
0160     * source (a character stream, a byte stream, or a URI).
0161     *
0162     * Applications may not invoke this method while a parse is in
0163     * progress (they should create a new Parser instead for each
0164     * additional XML document).  Once a parse is complete, an
0165     * application may reuse the same Parser object, possibly with a
0166     * different input source.
0167     *
0168     * @param source The input source for the top-level of the
0169     *               XML document.
0170     * @exception SAXException Any SAX exception, possibly
0171     *            wrapping another exception.
0172     * @exception XMLException An exception from the parser or client
0173     *            handler code.
0174     * @see InputSource#InputSource
0175     * @see #setEntityResolver
0176     * @see #setDTDHandler
0177     * @see #setDocumentHandler
0178     * @see #setErrorHandler
0179     */
0180     virtual void parse
0181     (
0182         const   InputSource&    source
0183     ) = 0;
0184
0185   /**
0186     * Parse an XML document from a system identifier (URI).
0187     *
0188     * This method is a shortcut for the common case of reading a
0189     * document from a system identifier.  It is the exact equivalent
0190     * of the following:
0191     *
0192     * parse(new URLInputSource(systemId));
0193     *
0194     * If the system identifier is a URL, it must be fully resolved
0195     * by the application before it is passed to the parser.
0196     *
0197     * @param systemId The system identifier (URI).
0198     * @exception SAXException Any SAX exception, possibly
0199     *            wrapping another exception.
0200     * @exception XMLException An exception from the parser or client
0201     *            handler code.
0202     * @see #parse(const InputSource&)
0203     */
0204     virtual void parse
0205     (
0206         const   XMLCh* const    systemId
0207     ) = 0;
0208
0209   /**
0210     * Parse an XML document from a system identifier (URI).
0211     *
0212     * This method is a shortcut for the common case of reading a
0213     * document from a system identifier.  It is the exact equivalent
0214     * of the following:
0215     *
0216     * parse(new URLInputSource(systemId));
0217     *
0218     * If the system identifier is a URL, it must be fully resolved
0219     * by the application before it is passed to the parser.
0220     *
0221     * @param systemId The system identifier (URI).
0222     * @exception SAXException Any SAX exception, possibly
0223     *            wrapping another exception.
0224     * @exception XMLException An exception from the parser or client
0225     *            handler code.
0226     * @see #parse(const InputSource&)
0227     */
0228     virtual void parse
0229     (
0230         const   char* const     systemId
0231     ) = 0;
0232     //@}
0233
0234
0235 private :
0236     /* The copy constructor, you cannot call this directly */
0237     Parser(const Parser&);
0238
0239     /* The assignment operator, you cannot call this directly */
0240     Parser& operator=(const Parser&);
0241 };
0242
0243 XERCES_CPP_NAMESPACE_END
0244
0245 #endif