1//
2// XMLReader.h
3//
4// Library: XML
5// Package: SAX
6// Module: SAX
7//
8// SAX2 XMLReader Interface.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef SAX_XMLReader_INCLUDED
18#define SAX_XMLReader_INCLUDED
19
20
21#include "Poco/XML/XML.h"
22#include "Poco/XML/XMLString.h"
23
24
25namespace Poco {
26namespace XML {
27
28
29class EntityResolver;
30class DTDHandler;
31class ContentHandler;
32class ErrorHandler;
33class InputSource;
34class LexicalHandler;
35class NamespaceHandler;
36
37
38class XML_API XMLReader
39 /// Interface for reading an XML document using callbacks.
40 /// XMLReader is the interface that an XML parser's SAX2 driver must
41 /// implement. This interface allows an application to set and
42 /// query features and properties in the parser, to register event handlers
43 /// for document processing, and to initiate a document parse.
44 /// All SAX interfaces are assumed to be synchronous: the parse methods must not
45 /// return until parsing is complete, and readers
46 /// must wait for an event-handler callback to return before reporting the next event.
47{
48public:
49 virtual void setEntityResolver(EntityResolver* pResolver) = 0;
50 /// Allow an application to register an entity resolver.
51 ///
52 /// If the application does not register an entity resolver, the
53 /// XMLReader will perform its own default resolution.
54 ///
55 /// Applications may register a new or different resolver in the middle of a
56 /// parse, and the SAX parser must begin using the new resolver immediately.
57
58 virtual EntityResolver* getEntityResolver() const = 0;
59 /// Return the current entity resolver.
60
61 virtual void setDTDHandler(DTDHandler* pDTDHandler) = 0;
62 /// Allow an application to register a DTD event handler.
63 ///
64 /// If the application does not register a DTD handler, all DTD events reported by
65 /// the SAX parser will be silently ignored.
66 ///
67 /// Applications may register a new or different handler in the middle of a parse,
68 /// and the SAX parser must begin using the new handler immediately.
69
70 virtual DTDHandler* getDTDHandler() const = 0;
71 /// Return the current DTD handler.
72
73 virtual void setContentHandler(ContentHandler* pContentHandler) = 0;
74 /// Allow an application to register a content event handler.
75 ///
76 /// If the application does not register a content handler, all content events
77 /// reported by the SAX parser will be silently ignored.
78 ///
79 /// Applications may register a new or different handler in the middle of a parse,
80 /// and the SAX parser must begin using the new handler immediately.
81
82 virtual ContentHandler* getContentHandler() const = 0;
83 /// Return the current content handler.
84
85 virtual void setErrorHandler(ErrorHandler* pErrorHandler) = 0;
86 /// Allow an application to register an error event handler.
87 ///
88 /// If the application does not register an error handler, all error events reported by
89 /// the SAX parser will be silently ignored; however, normal processing may not continue.
90 /// It is highly recommended that all SAX applications implement an error handler to avoid
91 /// unexpected bugs.
92 ///
93 /// Applications may register a new or different handler in the middle of a parse, and the
94 /// SAX parser must begin using the new handler immediately.
95
96 virtual ErrorHandler* getErrorHandler() const = 0;
97 /// Return the current error handler.
98
99 virtual void setFeature(const XMLString& featureId, bool state) = 0;
100 /// Set the state of a feature.
101 ///
102 /// The feature name is any fully-qualified URI. It is possible for an XMLReader to
103 /// expose a feature value but to be unable to change the current value. Some feature
104 /// values may be immutable or mutable only in specific contexts, such as before, during,
105 /// or after a parse.
106 ///
107 /// All XMLReaders are required to support setting http://xml.org/sax/features/namespaces
108 /// to true and http://xml.org/sax/features/namespace-prefixes to false.
109
110 virtual bool getFeature(const XMLString& featureId) const = 0;
111 /// Look up the value of a feature.
112 ///
113 /// The feature name is any fully-qualified URI. It is possible for an XMLReader
114 /// to recognize a feature name but temporarily be unable to return its value.
115 /// Some feature values may be available only in specific contexts, such as before,
116 /// during, or after a parse. Also, some feature values may not be programmatically
117 /// accessible. (In the case of an adapter for SAX1 Parser, there is no
118 /// implementation-independent way to expose whether the underlying parser is performing
119 /// validation, expanding external entities, and so forth.)
120 ///
121 /// All XMLReaders are required to recognize the
122 /// http://xml.org/sax/features/namespaces and the
123 /// http://xml.org/sax/features/namespace-prefixes feature names.
124 /// Implementors are free (and encouraged) to invent their own features,
125 /// using names built on their own URIs.
126
127 virtual void setProperty(const XMLString& propertyId, const XMLString& value) = 0;
128 /// Set the value of a property.
129 ///
130 /// The property name is any fully-qualified URI. It is possible for an XMLReader
131 /// to recognize a property name but to be unable to change the current value.
132 /// Some property values may be immutable or mutable only in specific contexts,
133 /// such as before, during, or after a parse.
134 ///
135 /// XMLReaders are not required to recognize setting any specific property names, though a
136 /// core set is defined by SAX2.
137 ///
138 /// This method is also the standard mechanism for setting extended handlers.
139
140 virtual void setProperty(const XMLString& propertyId, void* value) = 0;
141 /// Set the value of a property.
142 /// See also setProperty(const XMLString&, const XMLString&).
143
144 virtual void* getProperty(const XMLString& propertyId) const = 0;
145 /// Look up the value of a property.
146 /// String values are returned as XMLChar*
147 /// The property name is any fully-qualified URI. It is possible for an XMLReader to
148 /// recognize a property name but temporarily be unable to return its value. Some property
149 /// values may be available only in specific contexts, such as before, during, or after a parse.
150 ///
151 /// XMLReaders are not required to recognize any specific property names, though an initial
152 /// core set is documented for SAX2.
153 ///
154 /// Implementors are free (and encouraged) to invent their own properties, using names
155 /// built on their own URIs.
156
157 virtual void parse(InputSource* pSource) = 0;
158 /// Parse an XML document.
159 ///
160 /// The application can use this method to instruct the XML reader to begin parsing an
161 /// XML document from any valid input source (a character stream, a byte stream, or a URI).
162 ///
163 /// Applications may not invoke this method while a parse is in progress (they should create
164 /// a new XMLReader instead for each nested XML document). Once a parse is complete, an
165 /// application may reuse the same XMLReader object, possibly with a different input source.
166 /// Configuration of the XMLReader object (such as handler bindings and values established for
167 /// feature flags and properties) is unchanged by completion of a parse, unless the definition of that
168 /// aspect of the configuration explicitly specifies other behavior. (For example, feature flags or
169 /// properties exposing characteristics of the document being parsed.)
170 ///
171 /// During the parse, the XMLReader will provide information about the XML document through the registered
172 /// event handlers.
173 ///
174 /// This method is synchronous: it will not return until parsing has ended. If a client application
175 /// wants to terminate parsing early, it should throw an exception.
176
177 virtual void parse(const XMLString& systemId) = 0;
178 /// Parse an XML document from a system identifier.
179 /// See also parse(InputSource*).
180
181 virtual void parseMemoryNP(const char* xml, std::size_t size) = 0;
182 /// Parse an XML document from memory.
183 /// See also parse(InputSource*).
184
185 // SAX Features
186 static const XMLString FEATURE_VALIDATION;
187 static const XMLString FEATURE_NAMESPACES;
188 static const XMLString FEATURE_NAMESPACE_PREFIXES;
189 static const XMLString FEATURE_EXTERNAL_GENERAL_ENTITIES;
190 static const XMLString FEATURE_EXTERNAL_PARAMETER_ENTITIES;
191 static const XMLString FEATURE_STRING_INTERNING;
192
193 // SAX Properties
194 static const XMLString PROPERTY_DECLARATION_HANDLER;
195 static const XMLString PROPERTY_LEXICAL_HANDLER;
196
197protected:
198 virtual ~XMLReader();
199};
200
201
202} } // namespace Poco::XML
203
204
205#endif // SAX_XMLReader_INCLUDED
206