mirror of
https://github.com/pocoproject/poco.git
synced 2024-12-26 19:22:34 +01:00
224 lines
9.6 KiB
C++
224 lines
9.6 KiB
C++
//
|
|
// XMLReader.h
|
|
//
|
|
// $Id: //poco/1.2/XML/include/Poco/SAX/XMLReader.h#1 $
|
|
//
|
|
// Library: XML
|
|
// Package: SAX
|
|
// Module: SAX
|
|
//
|
|
// SAX2 XMLReader Interface.
|
|
//
|
|
// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
|
|
// and Contributors.
|
|
//
|
|
// Permission is hereby granted, free of charge, to any person or organization
|
|
// obtaining a copy of the software and accompanying documentation covered by
|
|
// this license (the "Software") to use, reproduce, display, distribute,
|
|
// execute, and transmit the Software, and to prepare derivative works of the
|
|
// Software, and to permit third-parties to whom the Software is furnished to
|
|
// do so, all subject to the following:
|
|
//
|
|
// The copyright notices in the Software and this entire statement, including
|
|
// the above license grant, this restriction and the following disclaimer,
|
|
// must be included in all copies of the Software, in whole or in part, and
|
|
// all derivative works of the Software, unless such copies or derivative
|
|
// works are solely in the form of machine-executable object code generated by
|
|
// a source language processor.
|
|
//
|
|
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
// FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
|
|
// SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
|
|
// FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
|
|
// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
|
// DEALINGS IN THE SOFTWARE.
|
|
//
|
|
|
|
|
|
#ifndef SAX_XMLReader_INCLUDED
|
|
#define SAX_XMLReader_INCLUDED
|
|
|
|
|
|
#include "Poco/XML/XML.h"
|
|
#include "Poco/XML/XMLString.h"
|
|
|
|
|
|
namespace Poco {
|
|
namespace XML {
|
|
|
|
|
|
class EntityResolver;
|
|
class DTDHandler;
|
|
class ContentHandler;
|
|
class ErrorHandler;
|
|
class InputSource;
|
|
class LexicalHandler;
|
|
class NamespaceHandler;
|
|
|
|
|
|
class XML_API XMLReader
|
|
/// Interface for reading an XML document using callbacks.
|
|
/// XMLReader is the interface that an XML parser's SAX2 driver must
|
|
/// implement. This interface allows an application to set and
|
|
/// query features and properties in the parser, to register event handlers
|
|
/// for document processing, and to initiate a document parse.
|
|
/// All SAX interfaces are assumed to be synchronous: the parse methods must not
|
|
/// return until parsing is complete, and readers
|
|
/// must wait for an event-handler callback to return before reporting the next event.
|
|
{
|
|
public:
|
|
virtual void setEntityResolver(EntityResolver* pResolver) = 0;
|
|
/// Allow an application to register an entity resolver.
|
|
///
|
|
/// If the application does not register an entity resolver, the
|
|
/// XMLReader will perform its own default resolution.
|
|
///
|
|
/// Applications may register a new or different resolver in the middle of a
|
|
/// parse, and the SAX parser must begin using the new resolver immediately.
|
|
|
|
virtual EntityResolver* getEntityResolver() const = 0;
|
|
/// Return the current entity resolver.
|
|
|
|
virtual void setDTDHandler(DTDHandler* pDTDHandler) = 0;
|
|
/// Allow an application to register a DTD event handler.
|
|
///
|
|
/// If the application does not register a DTD handler, all DTD events reported by
|
|
/// the SAX parser will be silently ignored.
|
|
///
|
|
/// Applications may register a new or different handler in the middle of a parse,
|
|
/// and the SAX parser must begin using the new handler immediately.
|
|
|
|
virtual DTDHandler* getDTDHandler() const = 0;
|
|
/// Return the current DTD handler.
|
|
|
|
virtual void setContentHandler(ContentHandler* pContentHandler) = 0;
|
|
/// Allow an application to register a content event handler.
|
|
///
|
|
/// If the application does not register a content handler, all content events
|
|
/// reported by the SAX parser will be silently ignored.
|
|
///
|
|
/// Applications may register a new or different handler in the middle of a parse,
|
|
/// and the SAX parser must begin using the new handler immediately.
|
|
|
|
virtual ContentHandler* getContentHandler() const = 0;
|
|
/// Return the current content handler.
|
|
|
|
virtual void setErrorHandler(ErrorHandler* pErrorHandler) = 0;
|
|
/// Allow an application to register an error event handler.
|
|
///
|
|
/// If the application does not register an error handler, all error events reported by
|
|
/// the SAX parser will be silently ignored; however, normal processing may not continue.
|
|
/// It is highly recommended that all SAX applications implement an error handler to avoid
|
|
/// unexpected bugs.
|
|
///
|
|
/// Applications may register a new or different handler in the middle of a parse, and the
|
|
/// SAX parser must begin using the new handler immediately.
|
|
|
|
virtual ErrorHandler* getErrorHandler() const = 0;
|
|
/// Return the current error handler.
|
|
|
|
virtual void setFeature(const XMLString& featureId, bool state) = 0;
|
|
/// Set the state of a feature.
|
|
///
|
|
/// The feature name is any fully-qualified URI. It is possible for an XMLReader to
|
|
/// expose a feature value but to be unable to change the current value. Some feature
|
|
/// values may be immutable or mutable only in specific contexts, such as before, during,
|
|
/// or after a parse.
|
|
///
|
|
/// All XMLReaders are required to support setting http://xml.org/sax/features/namespaces
|
|
/// to true and http://xml.org/sax/features/namespace-prefixes to false.
|
|
|
|
virtual bool getFeature(const XMLString& featureId) const = 0;
|
|
/// Look up the value of a feature.
|
|
///
|
|
/// The feature name is any fully-qualified URI. It is possible for an XMLReader
|
|
/// to recognize a feature name but temporarily be unable to return its value.
|
|
/// Some feature values may be available only in specific contexts, such as before,
|
|
/// during, or after a parse. Also, some feature values may not be programmatically
|
|
/// accessible. (In the case of an adapter for SAX1 Parser, there is no
|
|
/// implementation-independent way to expose whether the underlying parser is performing
|
|
/// validation, expanding external entities, and so forth.)
|
|
///
|
|
/// All XMLReaders are required to recognize the
|
|
/// http://xml.org/sax/features/namespaces and the
|
|
/// http://xml.org/sax/features/namespace-prefixes feature names.
|
|
/// Implementors are free (and encouraged) to invent their own features,
|
|
/// using names built on their own URIs.
|
|
|
|
virtual void setProperty(const XMLString& propertyId, const XMLString& value) = 0;
|
|
/// Set the value of a property.
|
|
///
|
|
/// The property name is any fully-qualified URI. It is possible for an XMLReader
|
|
/// to recognize a property name but to be unable to change the current value.
|
|
/// Some property values may be immutable or mutable only in specific contexts,
|
|
/// such as before, during, or after a parse.
|
|
///
|
|
/// XMLReaders are not required to recognize setting any specific property names, though a
|
|
/// core set is defined by SAX2.
|
|
///
|
|
/// This method is also the standard mechanism for setting extended handlers.
|
|
|
|
virtual void setProperty(const XMLString& propertyId, void* value) = 0;
|
|
/// Set the value of a property.
|
|
/// See also setProperty(const XMLString&, const XMLString&).
|
|
|
|
virtual void* getProperty(const XMLString& propertyId) const = 0;
|
|
/// Look up the value of a property.
|
|
/// String values are returned as XMLChar*
|
|
/// The property name is any fully-qualified URI. It is possible for an XMLReader to
|
|
/// recognize a property name but temporarily be unable to return its value. Some property
|
|
/// values may be available only in specific contexts, such as before, during, or after a parse.
|
|
///
|
|
/// XMLReaders are not required to recognize any specific property names, though an initial
|
|
/// core set is documented for SAX2.
|
|
///
|
|
/// Implementors are free (and encouraged) to invent their own properties, using names
|
|
/// built on their own URIs.
|
|
|
|
virtual void parse(InputSource* pSource) = 0;
|
|
/// Parse an XML document.
|
|
///
|
|
/// The application can use this method to instruct the XML reader to begin parsing an
|
|
/// XML document from any valid input source (a character stream, a byte stream, or a URI).
|
|
///
|
|
/// Applications may not invoke this method while a parse is in progress (they should create
|
|
/// a new XMLReader instead for each nested XML document). Once a parse is complete, an
|
|
/// application may reuse the same XMLReader object, possibly with a different input source.
|
|
/// Configuration of the XMLReader object (such as handler bindings and values established for
|
|
/// feature flags and properties) is unchanged by completion of a parse, unless the definition of that
|
|
/// aspect of the configuration explicitly specifies other behavior. (For example, feature flags or
|
|
/// properties exposing characteristics of the document being parsed.)
|
|
///
|
|
/// During the parse, the XMLReader will provide information about the XML document through the registered
|
|
/// event handlers.
|
|
///
|
|
/// This method is synchronous: it will not return until parsing has ended. If a client application
|
|
/// wants to terminate parsing early, it should throw an exception.
|
|
|
|
virtual void parse(const XMLString& systemId) = 0;
|
|
/// Parse an XML document from a system identifier.
|
|
/// See also parse(InputSource*).
|
|
|
|
// SAX Features
|
|
static const XMLString FEATURE_VALIDATION;
|
|
static const XMLString FEATURE_NAMESPACES;
|
|
static const XMLString FEATURE_NAMESPACE_PREFIXES;
|
|
static const XMLString FEATURE_EXTERNAL_GENERAL_ENTITIES;
|
|
static const XMLString FEATURE_EXTERNAL_PARAMETER_ENTITIES;
|
|
static const XMLString FEATURE_STRING_INTERNING;
|
|
|
|
// SAX Properties
|
|
static const XMLString PROPERTY_DECLARATION_HANDLER;
|
|
static const XMLString PROPERTY_LEXICAL_HANDLER;
|
|
|
|
protected:
|
|
virtual ~XMLReader();
|
|
};
|
|
|
|
|
|
} } // namespace Poco::XML
|
|
|
|
|
|
#endif // SAX_XMLReader_INCLUDED
|